@silverbulletmd/silverbullet 2.10.0 → 2.12.0

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

@@ -5,6 +5,14 @@ import { syscall } from "../syscall.ts";
  * @module
  */
 
+/**
+ * Whether client Sync is enabled. False when the service worker is off
+ * (`SB_DISABLE_SERVICE_WORKER` / `bootConfig.disableServiceWorker`).
+ */
+export function isEnabled(): Promise<boolean> {
+  return syscall("sync.isEnabled");
+}
+
 /**
  * Checks if an initial sync has completed
  */
@@ -12,12 +20,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
@@ -101,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,
@@ -19,6 +20,7 @@ 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),
+    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

@@ -1,5 +1,8 @@
 import type { ParseTree } from "@silverbulletmd/silverbullet/lib/tree";
-import type { PageMeta } from "@silverbulletmd/silverbullet/type/index";
+import type {
+  DocumentMeta,
+  PageMeta,
+} from "@silverbulletmd/silverbullet/type/index";
 
 export type FilterOption = {
   name: string;
@@ -33,7 +36,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,12 +49,22 @@ export type CodeWidgetContent = {
   url?: string;
 };
 
-// Document editors stuff
 export type DocumentEditorCallback = () => Promise<DocumentEditorContent>;
 export type DocumentEditorContent = {
   html: string;
 };
 
+export type DocumentCapabilityDescriptor = Pick<
+  DocumentMeta,
+  "name" | "extension" | "contentType" | "size"
+>;
+
+export type DocumentCapability = {
+  kind: "plug" | "text" | "media" | "external";
+  editor?: string;
+  reason?: string;
+};
+
 export type LintDiagnostic = {
   from: number;
   to: number;
@@ -93,6 +109,7 @@ export type AppEvent =
   | "editor:unfold"
   | "plugs:loaded"
   | "cron:secondPassed"
+  // Deprecated: dock a view at "page-top"/"page-bottom" with view.define instead.
   | "hooks:renderTopWidgets"
   | "hooks:renderBottomWidgets";
 
@@ -136,7 +153,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<
   {

package/plug-api/types/manifest.ts

@@ -77,6 +77,13 @@ export type CommandDef = {
   hide?: boolean;
   requireMode?: "rw" | "ro";
   requireEditor?: "any" | "page" | "notpage" | string;
+  /**
+   * When true, the command is omitted from the palette, menus, and
+   * `buildAllCommands()` while `bootConfig.disableServiceWorker` is set
+   * (`SB_DISABLE_SERVICE_WORKER`). Same space-wide drop as `requireMode: rw`
+   * in a read-only space.
+   */
+  requireServiceWorker?: boolean;
 
   // When true, this binding is NOT registered while vim mode is active,
   // so the key falls through to vim.

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

@@ -0,0 +1,64 @@
+export type StructuredDescription = {
+  label?: string;
+  text: string;
+  highlights?: [number, number][];
+};
+
+export type Description = string | StructuredDescription;
+
+export function normalizeDescription(value: unknown): Description | undefined {
+  if (typeof value === "string") return value;
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !("text" in value) ||
+    typeof value.text !== "string"
+  )
+    return undefined;
+  const text = value.text;
+  const boundary = (offset: number) =>
+    !(
+      offset > 0 &&
+      offset < text.length &&
+      /[\uD800-\uDBFF]/.test(text[offset - 1]) &&
+      /[\uDC00-\uDFFF]/.test(text[offset])
+    );
+  const ranges =
+    "highlights" in value && Array.isArray(value.highlights)
+      ? value.highlights
+      : [];
+  const valid = ranges
+    .filter(
+      (range): range is [number, number] =>
+        Array.isArray(range) &&
+        range.length === 2 &&
+        range.every(Number.isInteger) &&
+        range[0] >= 0 &&
+        range[1] <= text.length &&
+        range[0] < range[1] &&
+        boundary(range[0]) &&
+        boundary(range[1]),
+    )
+    .sort((a, b) => a[0] - b[0]);
+  const highlights: [number, number][] = [];
+  for (const [start, end] of valid) {
+    const previous = highlights.at(-1);
+    if (previous && start <= previous[1])
+      previous[1] = Math.max(previous[1], end);
+    else highlights.push([start, end]);
+  }
+  return {
+    text,
+    ...("label" in value && typeof value.label === "string"
+      ? { label: value.label }
+      : {}),
+    highlights,
+  };
+}
+
+export function descriptionText(description?: Description): string {
+  if (typeof description === "string") return description;
+  return description
+    ? [description.label, description.text].filter(Boolean).join(" ")
+    : "";
+}

package/plug-api/ui/hover.ts

@@ -0,0 +1,69 @@
+import { useEffect, useState } from "preact/hooks";
+
+/**
+ * Tracks hover outside parent state. Individual subscriptions re-render only
+ * the two affected rows instead of the entire expanded list.
+ */
+export class HoverTracker {
+  private key: unknown = undefined;
+  private subscribers = new Set<(key: unknown) => void>();
+  /** Where the pointer was last seen -- see `resolveHover`. */
+  private x = -1;
+  private y = -1;
+
+  get(): unknown {
+    return this.key;
+  }
+
+  set(key: unknown): void {
+    if (this.key === key) return;
+    this.key = key;
+    for (const notify of this.subscribers) notify(key);
+  }
+
+  /**
+   * A pointer event over the row container: remembers where, and over what.
+   * Any `MouseEvent` will do -- a drop is the other event that moves the
+   * pointer somewhere the tracker has to hear about (see `onDrop`), and its
+   * coordinates are the last ones a drag leaves behind.
+   */
+  track(event: MouseEvent, rowAt: (node: Element | null) => unknown): void {
+    this.x = event.clientX;
+    this.y = event.clientY;
+    this.set(rowAt(event.target as Element | null));
+  }
+
+  elementUnderPointer(): Element | null {
+    if (this.x < 0 && this.y < 0) return null;
+    return document.elementFromPoint(this.x, this.y);
+  }
+
+  subscribe(notify: (key: unknown) => void): () => void {
+    this.subscribers.add(notify);
+    return () => {
+      this.subscribers.delete(notify);
+    };
+  }
+}
+
+/**
+ * Re-answers "what is the pointer over" without the pointer having moved --
+ * after a refresh replaced the rows, or after the keyboard scrolled different
+ * ones underneath it. Identity, never position: the row that was under the
+ * pointer may be gone, and the one now in its slot was never pointed at.
+ */
+export function resolveHover(
+  tracker: HoverTracker,
+  rowAt: (node: Element | null) => unknown,
+): void {
+  tracker.set(rowAt(tracker.elementUnderPointer()));
+}
+
+export function useHovered(tracker: HoverTracker, key: unknown): boolean {
+  const [hovered, setHovered] = useState(() => tracker.get() === key);
+  useEffect(() => {
+    setHovered(tracker.get() === key);
+    return tracker.subscribe((current) => setHovered(current === key));
+  }, [tracker, key]);
+  return hovered;
+}