@silverbulletmd/silverbullet 2.9.0 → 2.11.0

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

@@ -0,0 +1,11 @@
+import { syscall } from "../syscall.ts";
+
+export function rankObjects(
+  objects: any[],
+  phrase: string,
+  options?: {
+    fields?: Record<string, number | { weight: number; segments?: boolean }>;
+  },
+): Promise<any[]> {
+  return syscall("search.rank", objects, phrase, options);
+}

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

@@ -1,11 +1,15 @@
-import { syscall } from "../syscall.ts";
-
+import type { Path, Ref } from "@silverbulletmd/silverbullet/lib/ref";
 import type {
   DocumentMeta,
   FileMeta,
   PageMeta,
 } from "../../plug-api/types/index.ts";
-import type { Ref } from "@silverbulletmd/silverbullet/lib/ref";
+import type {
+  FileRevisions,
+  SpaceLog,
+} from "../../plug-api/types/revisions.ts";
+import type { PathLookup } from "../lib/resolve_path.ts";
+import { syscall } from "../syscall.ts";
 
 /**
  * Exposes the space with its pages, documents and plugs.
@@ -134,8 +138,6 @@ export function deleteDocument(name: string): Promise<void> {
   return syscall("space.deleteDocument", name);
 }
 
-// Lower level-file operations
-
 /**
  * List all files in the space (pages, documents and plugs).
  * @returns a list of all files in the space represented as FileMeta objects
@@ -203,3 +205,118 @@ export function deleteFile(name: string): Promise<void> {
 export function fileExists(name: string): Promise<boolean> {
   return syscall("space.fileExists", name);
 }
+
+/**
+ * Every basename carried by more than one file, with the files that carry it.
+ * Small under the bare-iff-unique invariant; pair with `collisionIndex` and
+ * `writeLinkPath` from `lib/resolve_path` to decide link write formats.
+ */
+export function collidingBasenames(): Promise<Record<string, Path[]>> {
+  return syscall("space.collidingBasenames");
+}
+
+/**
+ * Looks up a batch of paths at once: for each, whether that exact path exists
+ * and which files share its basename. Pair with `lookupIndex` and `resolvePath`
+ * from `lib/resolve_path` to resolve them.
+ */
+export function lookupPaths(
+  paths: string[],
+): Promise<Record<string, PathLookup>> {
+  return syscall("space.lookupPaths", paths);
+}
+
+/**
+ * Lists the revision history of a file.
+ * @param path the path of the file to list revisions for
+ * @param before list revisions older than this revision id
+ */
+export function listRevisions(
+  path: string,
+  before?: string,
+): Promise<FileRevisions> {
+  return syscall("space.listRevisions", path, before);
+}
+
+/**
+ * Reads the text of a file as it was at a given revision, or at that
+ * revision's parent.
+ * @param path the path of the file to read
+ * @param rev the revision id to read
+ * @param parent read the file as of the revision's parent instead (e.g. the
+ * version immediately before a deletion commit)
+ */
+export function getRevision(
+  path: string,
+  rev: string,
+  parent?: boolean,
+): Promise<string> {
+  return syscall("space.getRevision", path, rev, parent);
+}
+
+/**
+ * Reads a unified diff of a revision's own change (vs its parent; a root
+ * commit reads as fully added).
+ * @param path the path of the file to diff
+ * @param rev the revision id to diff; omitted, diffs the uncommitted change
+ */
+export function getRevisionDiff(path: string, rev?: string): Promise<string> {
+  return syscall("space.getRevisionDiff", path, rev);
+}
+
+/**
+ * Lists the space-wide commit log.
+ * @param before list commits older than this revision id
+ * @param q match commits whose message or author contains this phrase
+ */
+export function getSpaceLog(before?: string, q?: string): Promise<SpaceLog> {
+  return syscall("space.getSpaceLog", before, q);
+}
+
+/**
+ * Commits everything outstanding as a revision now, rather than waiting for
+ * the automatic commit.
+ * @returns false if there was nothing to commit
+ */
+export function createRevisionSnapshot(): Promise<boolean> {
+  return syscall("space.createRevisionSnapshot");
+}
+
+export function getGitSyncStatus(): Promise<
+  import("../types/revisions.ts").GitSyncSnapshot
+> {
+  return syscall("space.getGitSyncStatus");
+}
+
+export function getGitConflicts(): Promise<
+  import("../types/revisions.ts").GitConflicts
+> {
+  return syscall("space.getGitConflicts");
+}
+
+export function syncGitNow(): Promise<void> {
+  return syscall("space.syncGitNow");
+}
+
+export function resolveGitConflict(
+  id: string,
+  generation: string,
+  contentRevision: string,
+  action: import("../types/revisions.ts").GitConflictAction,
+): Promise<import("../types/revisions.ts").GitConflicts> {
+  return syscall(
+    "space.resolveGitConflict",
+    id,
+    generation,
+    contentRevision,
+    action,
+  );
+}
+
+export function getGitConflictVersion(
+  id: string,
+  generation: string,
+  side: "local" | "remote",
+): Promise<Uint8Array> {
+  return syscall("space.getGitConflictVersion", id, generation, side);
+}

package/plug-api/syscalls/sync.ts

@@ -12,12 +12,33 @@ export function hasInitialSyncCompleted(): Promise<boolean> {
   return syscall("sync.hasInitialSyncCompleted");
 }
 
+/**
+ * For each file, whether indexing it now would read it locally or cheaply
+ * (true), or race the initial sync and expensively re-download it (false).
+ * Always all-true outside a fresh install's initial index window.
+ * @param paths the space-relative file paths
+ */
+export function areFilesReadyToIndex(paths: string[]): Promise<boolean[]> {
+  return syscall("sync.areFilesReadyToIndex", paths);
+}
+
 /**
  * Syncs a file immediately. Sync would happen automatically, but this prioritizes the file.
  * @param path the path to the file to sync
+ * @param remoteLastModified lastModified of the remote change event, used for echo suppression
+ * @param remoteRevisionHash content revision the remote change event reported, which tells a same-millisecond change from an echo
  */
-export function performFileSync(path: string): Promise<void> {
-  return syscall("sync.performFileSync", path);
+export function performFileSync(
+  path: string,
+  remoteLastModified?: number,
+  remoteRevisionHash?: string,
+): Promise<void> {
+  return syscall(
+    "sync.performFileSync",
+    path,
+    remoteLastModified,
+    remoteRevisionHash,
+  );
 }
 
 /**

package/plug-api/syscalls/system.ts

@@ -1,6 +1,7 @@
 import { syscall } from "../syscall.ts";
 import type { CommandDef } from "../types/manifest.ts";
 import type { SyscallMeta } from "@silverbulletmd/silverbullet/type/index";
+import type { Account, ClientProfile } from "../types/profile.ts";
 
 /**
  * System level syscalls
@@ -35,6 +36,34 @@ export function listCommands(): Promise<Record<string, CommandDef>> {
   return syscall("system.listCommands");
 }
 
+/**
+ * Lists the commands the command palette would show right now: context- and
+ * mode-filtered, hidden ones dropped, each with its prettified key hint and
+ * the time it was last run on this client.
+ * Note: only available on the client
+ */
+export function listPaletteCommands(): Promise<
+  {
+    name: string;
+    priority: number;
+    lastRun?: number;
+    hint?: string;
+  }[]
+> {
+  return syscall("system.listPaletteCommands");
+}
+
+/**
+ * Runs a command as if it had been picked from the command palette: records
+ * it as the most recently run (which is what orders the palette), then
+ * invokes it.
+ * Note: only available on the client
+ * @returns whatever the command returned
+ */
+export function runPaletteCommand(name: string): Promise<any> {
+  return syscall("system.runPaletteCommand", name);
+}
+
 /**
  * Lists all syscalls available
  * @returns a list of all available syscalls
@@ -51,6 +80,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.
  */
@@ -94,6 +130,23 @@ export function getVersion(): Promise<string> {
   return syscall("system.getVersion");
 }
 
+/**
+ * The current user's identity. `username` falls back to "me" when the
+ * deployment has no accounts.
+ */
+export function getProfile(): Promise<ClientProfile> {
+  return syscall("system.getProfile");
+}
+
+/**
+ * Every account with access to this space. `username` falls back to "me" for a
+ * deployment without accounts, and exactly one entry is marked `me` whenever
+ * the current user is known.
+ */
+export function listAccounts(): Promise<Account[]> {
+  return syscall("system.listAccounts");
+}
+
 export function getConfig<T = any>(
   key: string,
   defaultValue: any = undefined,

package/plug-api/syscalls.ts

@@ -14,6 +14,8 @@ export * as datastore from "./syscalls/datastore.ts";
 export * as jsonschema from "./syscalls/jsonschema.ts";
 export * as lua from "./syscalls/lua.ts";
 export * as config from "./syscalls/config.ts";
+export * as search from "./syscalls/search.ts";
+export * as icon from "./syscalls/icon.ts";
 
 // Not technically syscalls, but we want to export them for convenience
 export * as index from "./syscalls/index.ts";

package/plug-api/system_mock.ts

@@ -4,6 +4,7 @@ import { MemoryKvPrimitives } from "../client/data/memory_kv_primitives.ts";
 import { DataStoreMQ } from "../client/data/mq.datastore.ts";
 import { ObjectIndex } from "../client/data/object_index.ts";
 import { EventHook } from "../client/plugos/hooks/event.ts";
+import { configSyscalls } from "../client/plugos/syscalls/config.ts";
 import {
   dataStoreReadSyscalls,
   dataStoreWriteSyscalls,
@@ -12,13 +13,14 @@ 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 {
   spaceReadSyscalls,
   spaceWriteSyscalls,
 } from "../client/plugos/syscalls/space.ts";
+import { syncSyscalls } from "../client/plugos/syscalls/sync.ts";
 import { systemSyscalls } from "../client/plugos/syscalls/system.ts";
 import { System } from "../client/plugos/system.ts";
 import { Space } from "../client/space.ts";
@@ -45,6 +47,13 @@ export function createMockSystem() {
     space,
     config,
     eventedSpacePrimitives: spacePrimitives,
+    // Sync/index state consulted by sync syscalls; defaults simulate a
+    // steady-state client (everything synced).
+    bootConfig: {},
+    fullSyncCompleted: true,
+    fullIndexCompleted: true,
+    syncedPaths: new Set<string>(),
+    serverPingMs: undefined,
   };
 
   const objectIndex = new ObjectIndex(ds, config, eventHook, mq);
@@ -64,11 +73,13 @@ export function createMockSystem() {
     languageSyscalls(),
     jsonschemaSyscalls(),
     indexSyscalls(objectIndex, clientMock),
-    luaSyscalls(clientSystemMock),
+    configSyscalls(config),
+    luaSyscalls(system, () => clientSystemMock.spaceLuaEnv.env),
     mqSyscalls(mq),
     dataStoreReadSyscalls(ds, clientSystemMock),
     dataStoreWriteSyscalls(ds),
     systemSyscalls(clientMock, false),
+    syncSyscalls(clientMock),
   );
 
   globalThis.syscall = (name: string, ...args: any): Promise<any> => {
@@ -77,6 +88,7 @@ export function createMockSystem() {
 
   return {
     system,
+    objectIndex,
     eventHook,
     config,
     kv,
@@ -84,5 +96,6 @@ export function createMockSystem() {
     mq,
     ds,
     space,
+    clientMock,
   };
 }

package/plug-api/types/client.ts

@@ -33,7 +33,10 @@ export type Notification = {
   persistent?: boolean;
 };
 
-export type PanelMode = number;
+// A plain number is a flex-grow ratio (or, for the modal slot, a pixel
+// inset); a string is a raw CSS `flex` shorthand, e.g. "0 0 260px" for a
+// fixed-width sidebar.
+export type PanelMode = number | string;
 
 export type CodeWidgetContent = {
   html?: string;
@@ -43,7 +46,6 @@ export type CodeWidgetContent = {
   url?: string;
 };
 
-// Document editors stuff
 export type DocumentEditorCallback = () => Promise<DocumentEditorContent>;
 export type DocumentEditorContent = {
   html: string;
@@ -136,7 +138,6 @@ export type SlashCompletions = {
   options: SlashCompletionOption[];
 };
 
-// Code widget stuff
 export type CodeWidgetCallback = (
   bodyText: string,
   pageName: string,

package/plug-api/types/datastore.ts

@@ -1,4 +1,3 @@
-// Message Queue related types
 export type MQMessage = {
   id: string;
   queue: string;
@@ -13,9 +12,10 @@ export type MQStats = {
 export type MQSubscribeOptions = {
   batchSize?: number;
   pollInterval?: number;
+  /** How often a running callback refreshes its messages' processing lease. */
+  leaseRenewIntervalMs?: number;
 };
 
-// KV types
 export type KvKey = string[];
 
 export type KV<T = any> = {
@@ -26,3 +26,12 @@ export type KV<T = any> = {
 export type KvQuery = {
   prefix?: KvKey;
 };
+
+/**
+ * Body of an `indexQueue` message: a plain path, or a path a producer has
+ * already cleared the index for (a full reindex empties the index wholesale
+ * before queueing). Shared by the producers (`client/data/object_index.ts`)
+ * and the consumer (`plugs/index/queue.ts`) so the two ends of the queue
+ * cannot drift.
+ */
+export type IndexQueueBody = string | { path: string; cleared?: boolean };

package/plug-api/types/index.ts

@@ -14,6 +14,16 @@ export type PageDecoration = {
   cssClasses?: string[];
   hide?: boolean;
   renderWidgets?: boolean; // Defaults to true
+  /** A Feather name ("star"), a namespaced one ("feather:star"), or literal
+   * SVG markup, shown alongside the page in the top bar, navigation, links,
+   * and completion. */
+  icon?: string;
+  tree?: PageTreeDecoration;
+};
+export type PageTreeDecoration = {
+  /** Floats the page above its lower-priority siblings (default 0). */
+  priority?: number;
+  hide?: boolean;
 };
 export type PageMeta = ObjectValue<
   {
@@ -36,11 +46,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/types/profile.ts

@@ -0,0 +1,13 @@
+export type ClientProfile = {
+  username: string;
+  fullName?: string;
+};
+
+/** One account with access to the space. `username` is absent where the
+ * deployment keeps no accounts at all, and exactly one entry is marked `me`
+ * whenever the current user is known. */
+export type Account = {
+  username: string | null;
+  fullName?: string;
+  me: boolean;
+};

package/plug-api/types/revisions.ts

@@ -0,0 +1,67 @@
+export type RevisionEntry = {
+  rev: string;
+  timestamp: number;
+  author: string;
+  message: string;
+  added?: number;
+  removed?: number;
+};
+
+export type FileRevisions = {
+  mode: "managed" | "unmanaged" | "disabled";
+  uncommitted: boolean;
+  revisions: RevisionEntry[];
+  more: boolean;
+};
+
+export type FileStatus = "added" | "modified" | "deleted" | "renamed";
+
+export type LogFile = { path: string; status: FileStatus };
+
+export type LogCommit = RevisionEntry & { files: LogFile[] };
+
+export type SpaceLog = {
+  mode: "managed" | "unmanaged" | "disabled";
+  commits: LogCommit[];
+  more: boolean;
+  /** What differs from HEAD right now -- what a snapshot would capture. */
+  uncommitted: LogFile[];
+  sync?: SyncState | null;
+};
+
+/** Mirrors the server's `SyncState` (`revisions::engine`), which serializes
+ * with `#[serde(tag = "state", rename_all = "camelCase")]` -- that renames
+ * variant names but not their fields, so `Paused`'s field stays `reason`,
+ * not `message`. `message` is absent on the `/.events` frame, which any
+ * Read-level visitor receives; `/.revisions/` and the admin route carry it. */
+export type SyncState =
+  | { state: "idle" }
+  | { state: "syncing" }
+  | { state: "conflicted"; paths: string[] }
+  | { state: "paused"; reason: string }
+  | { state: "error"; kind: string; message?: string };
+
+export type GitSyncSnapshot = {
+  sync: SyncState;
+  lastAttempt: number | null;
+  lastSuccess: number | null;
+  version: number;
+  enabled: boolean;
+  paused: boolean;
+  dirty?: boolean;
+  pending: number | null;
+  incoming: number | null;
+};
+
+export type GitConflict = {
+  id: string;
+  path: string;
+  kind: "text" | "binary" | "deleteModify" | "unsupported";
+  local: boolean;
+  remote: boolean;
+  contentRevision: string;
+  canResolve?: boolean;
+};
+
+export type GitConflicts = { generation: string; conflicts: GitConflict[] };
+export type GitConflictAction = "local" | "remote" | "edited" | "delete";

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(" ");
 }