@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/plugos/syscalls/index.ts

@@ -1,160 +1,306 @@
-import type { SysCallMapping } from "../system.ts";
-import type {
-  LuaCollectionQuery,
-  LuaQueryCollection,
-} from "../../space_lua/query_collection.ts";
+import type { ObjectValue } from "@silverbulletmd/silverbullet/type/index";
+import type { Client } from "../../client.ts";
 
 import {
   type ObjectIndex,
   ObjectValidationError,
 } from "../../data/object_index.ts";
-import type { ObjectValue } from "@silverbulletmd/silverbullet/type/index";
-import type { Client } from "../../client.ts";
+import type {
+  LuaCollectionQuery,
+  LuaQueryCollection,
+} from "../../space_lua/query_collection.ts";
 import type { LuaTable } from "../../space_lua/runtime.ts";
+import type { SysCallMapping } from "../system.ts";
+import { describeSchemas, tagSchema } from "./schema_introspection.ts";
 
 export function indexSyscalls(
   objectIndex: ObjectIndex,
   client: Client,
 ): SysCallMapping {
   return {
-    // Query collection API
-    "index.tag": (_ctx, tagName: string): LuaQueryCollection => {
-      return objectIndex.objectsWithTag(tagName);
+    "index.tag": {
+      callback: (_ctx, tagName: string): LuaQueryCollection => {
+        return objectIndex.objectsWithTag(tagName);
+      },
+      description: "Returns objects carrying a tag as a query collection.",
+      signatures: ["index.tag(tagName)"],
     },
     // Alias for tag
-    "index.objects": (_ctx, tagName: string): LuaQueryCollection => {
-      return objectIndex.objectsWithTag(tagName);
+    "index.objects": {
+      callback: (_ctx, tagName: string): LuaQueryCollection => {
+        return objectIndex.objectsWithTag(tagName);
+      },
+      description: "Returns objects carrying a tag as a query collection.",
+      signatures: ["index.objects(tagName)"],
+    },
+    "index.pages": {
+      callback: (_ctx, tagName?: string): LuaQueryCollection => {
+        return objectIndex.rootTaggedObjects("page", tagName);
+      },
+      description:
+        "Returns all pages, optionally filtered by an additional tag, as a query collection.",
+      signatures: ["index.pages(tagName?)"],
+    },
+    "index.subPages": {
+      callback: (_ctx, pageName: string): LuaQueryCollection => {
+        return objectIndex.subPages(pageName);
+      },
+      description:
+        "Returns pages nested below a page name as a query collection.",
+      signatures: ["index.subPages(pageName)"],
     },
-    "index.pages": (_ctx, tagName?: string): LuaQueryCollection => {
-      return objectIndex.rootTaggedObjects("page", tagName);
+    "index.documents": {
+      callback: (): LuaQueryCollection => {
+        return objectIndex.objectsWithTag("document");
+      },
+      description: "Returns all indexed documents as a query collection.",
     },
-    "index.subPages": (_ctx, pageName: string): LuaQueryCollection => {
-      return objectIndex.subPages(pageName);
+    "index.links": {
+      callback: (): LuaQueryCollection => {
+        return objectIndex.objectsWithTag("link");
+      },
+      description: "Returns all indexed links as a query collection.",
     },
-    "index.documents": (): LuaQueryCollection => {
-      return objectIndex.objectsWithTag("document");
+    "index.relations": {
+      callback: (_ctx, kind?: string): LuaQueryCollection => {
+        return objectIndex.relations(kind);
+      },
+      description:
+        "Returns all indexed relations, optionally filtered by kind, as a query collection.",
+      signatures: ["index.relations(kind?)"],
     },
-    "index.links": (): LuaQueryCollection => {
-      return objectIndex.objectsWithTag("link");
+    "index.contentPages": {
+      callback: (_ctx, tagName?: string): LuaQueryCollection => {
+        return objectIndex.contentPages(tagName);
+      },
+      description:
+        "Returns non-meta pages, optionally filtered by an additional tag, as a query collection.",
+      signatures: ["index.contentPages(tagName?)"],
     },
-    "index.relations": (): LuaQueryCollection => {
-      return objectIndex.objectsWithTag("relation");
+    "index.metaPages": {
+      callback: (): LuaQueryCollection => {
+        return objectIndex.metaPages();
+      },
+      description: "Returns all meta pages as a query collection.",
     },
-    "index.contentPages": (_ctx, tagName?: string): LuaQueryCollection => {
-      return objectIndex.contentPages(tagName);
+    "index.tasks": {
+      callback: (_ctx, tagName?: string): LuaQueryCollection => {
+        return objectIndex.rootTaggedObjects("task", tagName);
+      },
+      description:
+        "Returns all tasks, optionally filtered by an additional tag, as a query collection.",
+      signatures: ["index.tasks(tagName?)"],
     },
-    "index.metaPages": (): LuaQueryCollection => {
-      return objectIndex.metaPages();
+    "index.headers": {
+      callback: (_ctx, tagName?: string): LuaQueryCollection => {
+        return objectIndex.rootTaggedObjects("header", tagName);
+      },
+      description:
+        "Returns all headers, optionally filtered by an additional tag, as a query collection.",
+      signatures: ["index.headers(tagName?)"],
     },
-    "index.tasks": (_ctx, tagName?: string): LuaQueryCollection => {
-      return objectIndex.rootTaggedObjects("task", tagName);
+    "index.items": {
+      callback: (_ctx, tagName?: string): LuaQueryCollection => {
+        return objectIndex.rootTaggedObjects("item", tagName);
+      },
+      description:
+        "Returns all list items, optionally filtered by an additional tag, as a query collection.",
+      signatures: ["index.items(tagName?)"],
     },
-    "index.headers": (_ctx, tagName?: string): LuaQueryCollection => {
-      return objectIndex.rootTaggedObjects("header", tagName);
+    "index.paragraphs": {
+      callback: (_ctx, tagName?: string): LuaQueryCollection => {
+        return objectIndex.rootTaggedObjects("paragraph", tagName);
+      },
+      description:
+        "Returns indexed paragraphs, optionally filtered by an additional tag, as a query collection.",
+      signatures: ["index.paragraphs(tagName?)"],
     },
-    "index.items": (_ctx, tagName?: string): LuaQueryCollection => {
-      return objectIndex.rootTaggedObjects("item", tagName);
+    "index.tables": {
+      callback: (_ctx, tagName?: string): LuaQueryCollection => {
+        return objectIndex.rootTaggedObjects("table", tagName);
+      },
+      description:
+        "Returns indexed table rows, optionally filtered by an additional tag, as a query collection.",
+      signatures: ["index.tables(tagName?)"],
     },
-    "index.paragraphs": (_ctx, tagName?: string): LuaQueryCollection => {
-      return objectIndex.rootTaggedObjects("paragraph", tagName);
+    "index.tags": {
+      callback: (): LuaQueryCollection => {
+        return objectIndex.objectsWithTag("tag");
+      },
+      description: "Returns all indexed tag objects as a query collection.",
     },
-    "index.tables": (_ctx, tagName?: string): LuaQueryCollection => {
-      return objectIndex.rootTaggedObjects("table", tagName);
+    "index.describeSchema": {
+      callback: (): Record<string, unknown> => {
+        return describeSchemas(client.config.get(["tags"], {}));
+      },
+      description:
+        "Returns raw JSON Schemas for every configured tag that declares one.",
     },
-    "index.tags": (): LuaQueryCollection => {
-      return objectIndex.objectsWithTag("tag");
+    "index.tagSchema": {
+      callback: (_ctx, tagName: string): unknown | null => {
+        return tagSchema(client.config.get(["tags"], {}), tagName);
+      },
+      description:
+        "Returns the raw JSON Schema for a tag, or nil when none is declared.",
+      signatures: ["index.tagSchema(tagName)"],
     },
-    "index.aspiringPages": (): LuaQueryCollection => {
-      return objectIndex.aspiringPages();
+    "index.isAvailable": {
+      callback: (): Promise<boolean> => objectIndex.isIndexAvailable(),
+      description: `Whether a full indexing pass has ever completed for this space. False on a fresh client, and for as long as the first index takes on a large one: every object query answers with whatever has been indexed so far, which is nothing to begin with. Code that must work in that window reads the space directly instead.`,
+      returns: [
+        { type: "boolean", description: "Whether the index can be trusted." },
+      ],
     },
-    // Internals
-    "index.aggregates": (): LuaQueryCollection => {
-      return objectIndex.aggregates();
+    "index.aspiringPages": {
+      callback: (): LuaQueryCollection => {
+        return objectIndex.aspiringPages();
+      },
+      description:
+        "Returns linked but not yet created pages as a query collection.",
     },
-    "index.ensureFullIndex": () => {
-      return objectIndex.ensureFullIndex(client.space);
+    "index.ambiguousLinks": {
+      callback: (): LuaQueryCollection => {
+        return objectIndex.ambiguousLinks();
+      },
+      description:
+        "Returns links whose page name matches more than one page as a query collection.",
     },
-    "index.reindexSpace": () => {
-      return objectIndex.reindexSpace(client.space);
+    "index.aggregates": {
+      callback: (): LuaQueryCollection => {
+        return objectIndex.aggregates();
+      },
+      description: "Returns stored aggregate records as a query collection.",
     },
-    "index.indexObjects": (
-      _ctx,
-      page: string,
-      objects: ObjectValue[],
-    ): Promise<void> => {
-      return objectIndex.indexObjects(page, objects);
+    "index.ensureFullIndex": {
+      callback: () => {
+        return objectIndex.ensureFullIndex(client.space);
+      },
+      description:
+        "Ensures the complete object index is available and current.",
     },
-    "index.validateObjects": async (
-      _ctx,
-      page: string,
-      objects: ObjectValue[],
-    ): Promise<{ error: string; object: ObjectValue } | null> => {
-      try {
-        await objectIndex.validateObjects(page, objects);
-        return null;
-      } catch (e: any) {
-        if (e instanceof ObjectValidationError) {
-          return {
-            error: e.message,
-            object: e.object,
-          };
-        } else {
-          throw e;
+    "index.reindexSpace": {
+      callback: () => {
+        return objectIndex.reindexSpace(client.space);
+      },
+      description: "Rebuilds the object index for the entire space.",
+    },
+    "index.indexObjects": {
+      callback: (_ctx, page: string, objects: ObjectValue[]): Promise<void> => {
+        return objectIndex.indexObjects(page, objects);
+      },
+      description: "Indexes a collection of objects for a page.",
+      signatures: ["index.indexObjects(page, objects)"],
+    },
+    "index.validateObjects": {
+      callback: async (
+        _ctx,
+        page: string,
+        objects: ObjectValue[],
+      ): Promise<{ error: string; object: ObjectValue } | null> => {
+        try {
+          await objectIndex.validateObjects(page, objects);
+          return null;
+        } catch (e: any) {
+          if (e instanceof ObjectValidationError) {
+            return {
+              error: e.message,
+              object: e.object,
+            };
+          } else {
+            throw e;
+          }
         }
-      }
-    },
-    "index.previewProcessedObjects": (
-      _ctx,
-      page: string,
-      objects: ObjectValue[],
-    ): Promise<{ tag: string; object: ObjectValue }[]> => {
-      return objectIndex.previewProcessedObjects(page, objects);
-    },
-    "index.getObjectByRef": (
-      _ctx,
-      page: string,
-      tag: string,
-      ref: string,
-    ): Promise<ObjectValue | undefined> => {
-      return objectIndex.getObjectByRef(page, tag, ref);
-    },
-    "index.queryLuaObjects": (
-      _ctx,
-      tag: string,
-      query: LuaCollectionQuery,
-      scopedVariables?: Record<string, any>,
-    ): Promise<ObjectValue[]> => {
-      return objectIndex.queryLuaObjects(
-        client.clientSystem.spaceLuaEnv.env,
-        tag,
-        query,
-        scopedVariables,
-      );
+      },
+      description:
+        "Validates objects for a page and returns the first validation error, if any.",
+      signatures: ["index.validateObjects(page, objects)"],
+    },
+    "index.previewProcessedObjects": {
+      callback: (
+        _ctx,
+        page: string,
+        objects: ObjectValue[],
+      ): Promise<{ tag: string; object: ObjectValue }[]> => {
+        return objectIndex.previewProcessedObjects(page, objects);
+      },
+      description:
+        "Runs the indexing pipeline without writing and returns processed tag/object pairs.",
+      signatures: ["index.previewProcessedObjects(page, objects)"],
+    },
+    "index.getObjectByRef": {
+      callback: (
+        _ctx,
+        page: string,
+        tag: string,
+        ref: string,
+      ): Promise<ObjectValue | undefined> => {
+        return objectIndex.getObjectByRef(page, tag, ref);
+      },
+      description:
+        "Returns an indexed object identified by page, tag, and reference.",
+      signatures: ["index.getObjectByRef(page, tag, ref)"],
+    },
+    "index.queryLuaObjects": {
+      callback: (
+        _ctx,
+        tag: string,
+        query: LuaCollectionQuery,
+        scopedVariables?: Record<string, any>,
+      ): Promise<ObjectValue[]> => {
+        return objectIndex.queryLuaObjects(
+          client.clientSystem.spaceLuaEnv.env,
+          tag,
+          query,
+          scopedVariables,
+        );
+      },
+      description:
+        "Executes a structured Lua collection query against indexed objects.",
+      signatures: ["index.queryLuaObjects(tag, query, scopedVariables?)"],
     },
 
-    "index.deleteObject": (
-      _ctx,
-      page: string,
-      tag: string,
-      ref: string,
-    ): Promise<void> => {
-      return objectIndex.deleteObject(page, tag, ref);
-    },
-    "lua:index.defineTag": (_ctx, tagDef: LuaTable) => {
-      // Using 'lua:' prefix to _not_ convert tagDef to a JS version (but keep original LuaTable)
-      if (!tagDef.has("name")) {
-        throw new Error("A tag name is required");
-      }
-      const currentTag = client.config.get(["tags", tagDef.get("name")], null);
-      if (!currentTag) {
-        client.config.set(["tags", tagDef.get("name")], {
-          name: tagDef.get("name"),
-        });
-      }
-      client.config.set(
-        ["tags", tagDef.get("name"), "metatable"],
-        tagDef.get("metatable"),
-      );
+    "index.clearFileIndex": {
+      callback: (_ctx, path: string): Promise<void> =>
+        objectIndex.clearFileIndex(path),
+      description:
+        "Drops every indexed object belonging to a file, so a re-index replaces them rather than merging on top.",
+      signatures: ["index.clearFileIndex(path)"],
+    },
+    "index.deleteObject": {
+      callback: (
+        _ctx,
+        page: string,
+        tag: string,
+        ref: string,
+      ): Promise<void> => {
+        return objectIndex.deleteObject(page, tag, ref);
+      },
+      description:
+        "Deletes an indexed object identified by page, tag, and reference.",
+      signatures: ["index.deleteObject(page, tag, ref)"],
+    },
+    "lua:index.defineTag": {
+      callback: (_ctx, tagDef: LuaTable) => {
+        // Using 'lua:' prefix to _not_ convert tagDef to a JS version (but keep original LuaTable)
+        if (!tagDef.has("name")) {
+          throw new Error("A tag name is required");
+        }
+        const currentTag = client.config.get(
+          ["tags", tagDef.get("name")],
+          null,
+        );
+        if (!currentTag) {
+          client.config.set(["tags", tagDef.get("name")], {
+            name: tagDef.get("name"),
+          });
+        }
+        client.config.set(
+          ["tags", tagDef.get("name"), "metatable"],
+          tagDef.get("metatable"),
+        );
+      },
+      description: "Defines or updates a tag and its Lua metatable.",
+      signatures: ["index.defineTag(tagDefinition)"],
     },
   };
 }

package/client/plugos/syscalls/jsonschema.ts

@@ -2,7 +2,6 @@ import type { SysCallMapping } from "../system.ts";
 import { type OutputUnit, Validator, format } from "@cfworker/json-schema";
 import { stripFunctions } from "../util.ts";
 
-// Register custom formats
 format.email = (data: string) => data.includes("@");
 format["page-ref"] = (data: string) =>
   data.startsWith("[[") && data.endsWith("]]");
@@ -75,17 +74,116 @@ export function validateSchema(schema: any): undefined | string {
   return;
 }
 
+/**
+ * Best-effort: infer a JSON Schema (draft 2020-12) from the *shape* of a single
+ * sample value. Types are guessed from one example, so the result is a hint,
+ * not a contract — the top-level schema is marked `"x-inferred": true`.
+ *
+ * Useful when a tag/object type has no declared schema but an example object
+ * exists and you want a plausible schema for it.
+ */
+export function inferFromObject(value: any): any {
+  const schema = inferSchemaNode(value);
+  schema["$schema"] = "https://json-schema.org/draft/2020-12/schema";
+  schema["x-inferred"] = true;
+  return schema;
+}
+
+/** Infer a bare JSON Schema node for a value, recursing into arrays/objects. */
+function inferSchemaNode(value: any): any {
+  if (value === null || value === undefined) {
+    return { type: "null" };
+  }
+  if (Array.isArray(value)) {
+    const node: any = { type: "array" };
+    if (value.length > 0) {
+      node.items = inferSchemaNode(value[0]);
+    }
+    return node;
+  }
+  switch (typeof value) {
+    case "boolean":
+      return { type: "boolean" };
+    case "number":
+      return { type: Number.isInteger(value) ? "integer" : "number" };
+    case "string":
+      return { type: "string" };
+    case "object": {
+      const properties: Record<string, any> = {};
+      for (const [k, v] of Object.entries(value)) {
+        properties[k] = inferSchemaNode(v);
+      }
+      return { type: "object", properties };
+    }
+    default:
+      // functions, symbols, bigint, … — not representable in JSON Schema.
+      return {};
+  }
+}
+
 export function jsonschemaSyscalls(): SysCallMapping {
   return {
-    "jsonschema.validateObject": (
-      _ctx,
-      schema: any,
-      object: any,
-    ): undefined | string => {
-      return validateObject(schema, object);
+    "jsonschema.validateObject": {
+      callback: (_ctx, schema: any, object: any): undefined | string => {
+        return validateObject(schema, object);
+      },
+      description: "Validates a value against a JSON Schema.",
+      parameters: [
+        {
+          name: "schema",
+          type: "table",
+          description: "JSON Schema to apply.",
+        },
+        { name: "object", description: "Value to validate." },
+      ],
+      returns: [
+        {
+          type: "string",
+          description: "Validation error, or nil when valid.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local schema = {type = "object", properties = {name = {type = "string"}}, required = {"name"}}\nlocal err = jsonschema.validateObject(schema, {name = "John"})',
+        },
+      ],
+    },
+    "jsonschema.validateSchema": {
+      callback: (_ctx, schema: any): undefined | string => {
+        return validateSchema(schema);
+      },
+      description:
+        "Checks whether a JSON Schema has a supported top-level shape.",
+      parameters: [{ name: "schema", description: "JSON Schema to validate." }],
+      returns: [
+        { type: "string", description: "Schema error, or nil when valid." },
+      ],
+      examples: [
+        {
+          code: 'local err = jsonschema.validateSchema({type = "object"})',
+        },
+      ],
     },
-    "jsonschema.validateSchema": (_ctx, schema: any): undefined | string => {
-      return validateSchema(schema);
+    "jsonschema.inferFromObject": {
+      callback: (_ctx, object: any): any => {
+        return inferFromObject(object);
+      },
+      description:
+        "Infers a best-effort draft 2020-12 JSON Schema from a sample value.",
+      parameters: [
+        {
+          name: "object",
+          description: "Sample value whose shape is inferred.",
+        },
+      ],
+      returns: [
+        { type: "table", description: "Inferred schema marked x-inferred." },
+      ],
+      examples: [
+        {
+          code: 'local schema = jsonschema.inferFromObject({name = "Widget", count = 3})',
+        },
+      ],
     },
   };
 }

package/client/plugos/syscalls/language.ts

@@ -9,19 +9,45 @@ import {
 
 export function languageSyscalls(): SysCallMapping {
   return {
-    "language.parseLanguage": async (
-      _ctx,
-      language: string,
-      code: string,
-    ): Promise<ParseTree> => {
-      const lang = languageFor(language) ?? await loadLanguageFor(language);
-      if (!lang) {
-        throw new Error(`Unknown language ${language}`);
-      }
-      return parse(lang, code);
+    "language.parseLanguage": {
+      callback: async (
+        _ctx,
+        language: string,
+        code: string,
+      ): Promise<ParseTree> => {
+        const lang = languageFor(language) ?? (await loadLanguageFor(language));
+        if (!lang) {
+          throw new Error(`Unknown language ${language}`);
+        }
+        return parse(lang, code);
+      },
+      description: "Parses code using a supported fenced-code-block language.",
+      parameters: [
+        {
+          name: "language",
+          type: "string",
+          description: "Language name or alias.",
+        },
+        {
+          name: "code",
+          type: "string",
+          description: "Source code to parse.",
+        },
+      ],
+      returns: [{ type: "table", description: "Parsed syntax tree." }],
+      examples: [
+        {
+          code: 'local tree = language.parseLanguage("javascript", "const answer = 42")',
+        },
+      ],
     },
-    "language.listLanguages": (): string[] => {
-      return allLanguageNames;
+    "language.listLanguages": {
+      callback: (): string[] => {
+        return allLanguageNames;
+      },
+      description: "Lists all supported fenced-code-block languages.",
+      returns: [{ type: "table", description: "Supported language names." }],
+      examples: [{ code: "local languages = language.listLanguages()" }],
     },
   };
 }