Merge branch 'main' into asch/multi-arch

This commit is contained in:
Andras Schmelczer 2025-08-30 11:03:30 +01:00
commit 436e900e3b
No known key found for this signature in database
GPG key ID: FC8F2C3D3D1A718C
56 changed files with 2343 additions and 3971 deletions

99
CLAUDE.md Normal file
View file

@ -0,0 +1,99 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
VaultLink is a self-hosted Obsidian plugin for real-time collaborative file syncing. The project consists of a Rust-based sync server and a TypeScript frontend with three main components: an Obsidian plugin, a sync client library, and a test client.
## Architecture
### Core Components
- **sync-server/**: Rust-based WebSocket server with SQLite database for document versioning and real-time synchronization
- **frontend/sync-client/**: TypeScript library providing core sync functionality, WebSocket management, and file operations
- **frontend/obsidian-plugin/**: Obsidian plugin that integrates the sync client with Obsidian's API
- **frontend/test-client/**: CLI testing tool for the sync functionality
### Key Technologies
- **Backend**: Rust with Axum framework, SQLite with SQLx, WebSockets for real-time sync
- **Frontend**: TypeScript, Webpack for bundling, Jest for testing
- **Sync Algorithm**: Uses reconcile-text library for operational transformation
## Development Commands
### Server Development
```bash
cd sync-server
cargo run config-e2e.yml # Start development server
cargo test --verbose # Run Rust tests
cargo clippy --all-targets --all-features # Lint Rust code
cargo fmt --all -- --check # Check Rust formatting
```
### Frontend Development
```bash
cd frontend
npm run dev # Start development mode (watches sync-client and obsidian-plugin)
npm run build # Build all workspaces
npm run test # Run all tests
npm run lint # Lint and format TypeScript code
```
### Database Setup (Development)
```bash
cd sync-server
sqlx database create --database-url sqlite://db.sqlite3
sqlx migrate run --source src/app_state/database/migrations --database-url sqlite://db.sqlite3
cargo sqlx prepare --workspace
```
### Scripts
- `scripts/check.sh`: Full CI check (builds, lints, tests both server and frontend)
- `scripts/e2e.sh`: End-to-end testing
- `scripts/clean-up.sh`: Clean logs and database files
- `scripts/bump-version.sh patch`: Publish new version
- `scripts/update-api-types.sh`: Update TypeScript bindings from Rust types
## Code Structure
### Workspace Configuration
The frontend uses npm workspaces with three packages:
- `sync-client`: Core synchronization logic
- `obsidian-plugin`: Obsidian-specific integration
- `test-client`: Testing utilities
### Type Generation
Rust structs generate TypeScript types via ts-rs crate, stored in `sync-server/bindings/` and used by frontend packages.
### Key Files
- `sync-server/src/`: Rust server implementation with WebSocket handlers
- `frontend/sync-client/src/sync-client.ts`: Main sync client entry point
- `frontend/obsidian-plugin/src/vault-link-plugin.ts`: Main Obsidian plugin class
- `frontend/sync-client/src/services/sync-service.ts`: Core synchronization logic
## Testing
### Running Tests
- Server: `cargo test --verbose`
- Frontend: `npm run test` (runs Jest across all workspaces)
- E2E: `scripts/e2e.sh`
### Test Structure
- Rust: Unit tests alongside source files
- TypeScript: `.test.ts` files using Jest
- E2E: Uses test-client to simulate multiple concurrent users
## Code Style
### Rust
- Uses extensive Clippy lints (see Cargo.toml)
- Follows pedantic linting rules
- Forbids unsafe code
- Uses cargo fmt with default settings
### TypeScript
- Prettier configuration: 4-space tabs, trailing commas removed, LF line endings
- ESLint with unused imports plugin
- Consistent across all three frontend packages

View file

@ -20,7 +20,14 @@ export default [
"no-unused-vars": "off",
"@typescript-eslint/restrict-template-expressions": "off",
"@typescript-eslint/no-unused-vars": "off",
"@typescript-eslint/no-floating-promises": "error",
"@typescript-eslint/no-floating-promises": [
"error",
{
allowForKnownSafeCalls: [
{ from: "package", name: ["suite", "test"], package: "node:test" },
],
},
],
"@typescript-eslint/parameter-properties": "off",
"@typescript-eslint/require-await": "off",
"@typescript-eslint/class-methods-use-this": "off",

View file

@ -1,3 +0,0 @@
module.exports = {
preset: "ts-jest"
};

View file

@ -1,7 +1,7 @@
{
"id": "vault-link",
"name": "VaultLink",
"version": "0.6.1",
"version": "0.6.3",
"minAppVersion": "0.0.0",
"description": "Self-hosted synchronization and collaboration for your Vault.",
"author": "Andras Schmelczer",

View file

@ -1,40 +1,38 @@
{
"name": "vault-link-obsidian-plugin",
"version": "0.6.1",
"version": "0.6.3",
"description": "This is a sample plugin for Obsidian (https://obsidian.md)",
"main": "main.js",
"scripts": {
"dev": "webpack watch --mode development",
"build": "webpack --mode production",
"test": "jest",
"test": "echo \"no tests defined\" && exit 0",
"version": "node version-bump.mjs"
},
"keywords": [],
"author": "",
"license": "MIT",
"devDependencies": {
"@types/jest": "^29.5.14",
"@types/node": "^22.15.30",
"css-loader": "^7.1.2",
"date-fns": "^4.1.0",
"file-loader": "^6.2.0",
"fs-extra": "^11.3.0",
"jest": "^29.7.0",
"mini-css-extract-plugin": "^2.9.2",
"obsidian": "1.8.7",
"reconcile-text": "^0.5.0",
"resolve-url-loader": "^5.0.0",
"sass": "^1.89.1",
"sass": "^1.91.0",
"sass-loader": "^16.0.5",
"sync-client": "file:../sync-client",
"terser-webpack-plugin": "^5.3.14",
"ts-jest": "^29.3.4",
"ts-loader": "^9.5.2",
"tslib": "2.8.1",
"tsx": "^4.20.5",
"typescript": "5.8.3",
"url": "^0.11.4",
"virtual-scroller": "^1.13.1",
"webpack": "^5.99.9",
"webpack-cli": "^6.0.1",
"reconcile-text": "^0.5.0"
"webpack-cli": "^6.0.1"
}
}

View file

@ -1,7 +1,10 @@
import type { Stat, Vault, Workspace } from "obsidian";
import { MarkdownView, normalizePath } from "obsidian";
import type { FileSystemOperations, RelativePath } from "sync-client";
import { positionToLineAndColumn } from "./utils/position-to-line-and-column";
import {
utils,
type FileSystemOperations,
type RelativePath
} from "sync-client";
import { getSelectionsFromEditor } from "./views/cursors/get-selections-from-editor";
import type { TextWithCursors, CursorPosition } from "reconcile-text";
@ -105,10 +108,10 @@ export class ObsidianFileSystemOperations implements FileSystemOperations {
const from = result.cursors[2 * i];
const to = result.cursors[2 * i + 1];
const { line: fromLine, column: fromColumn } =
positionToLineAndColumn(result.text, from.position);
utils.positionToLineAndColumn(result.text, from.position);
const { line: toLine, column: toColumn } =
positionToLineAndColumn(result.text, to.position);
utils.positionToLineAndColumn(result.text, to.position);
selections.push({
anchor: { line: fromLine, ch: fromColumn },

View file

@ -1,61 +0,0 @@
import { positionToLineAndColumn } from "./position-to-line-and-column";
describe("positionToLineAndColumn", () => {
test("converts position to line and column in multi-line text", () => {
const text = "ab\ncd\n";
expect(positionToLineAndColumn(text, 0)).toEqual({
line: 0,
column: 0
});
expect(positionToLineAndColumn(text, 1)).toEqual({
line: 0,
column: 1
});
expect(positionToLineAndColumn(text, 2)).toEqual({
line: 0,
column: 2
});
expect(positionToLineAndColumn(text, 3)).toEqual({
line: 1,
column: 0
});
expect(positionToLineAndColumn(text, 4)).toEqual({
line: 1,
column: 1
});
expect(positionToLineAndColumn(text, 6)).toEqual({
line: 2,
column: 0
});
});
test("with carrige returns", () => {
expect(positionToLineAndColumn("a\nb", 3)).toEqual({
line: 1,
column: 1
});
expect(positionToLineAndColumn("a\r\nb", 3)).toEqual({
line: 1,
column: 1
});
});
test("handles empty input", () => {
expect(positionToLineAndColumn("", 0)).toEqual({ line: 0, column: 0 });
});
test("handles positions at the end of text", () => {
const text = "End";
expect(positionToLineAndColumn(text, 3)).toEqual({
line: 0,
column: 3
});
});
test("throws error for position out of range", () => {
const text = "Short text";
expect(() => positionToLineAndColumn(text, 15)).toThrow();
expect(() => positionToLineAndColumn(text, -1)).toThrow();
});
});

View file

@ -1,3 +0,0 @@
export async function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}

View file

@ -1,29 +1,33 @@
import type {
MarkdownView,
Editor,
MarkdownFileInfo,
TAbstractFile,
WorkspaceLeaf
} from "obsidian";
import type { MarkdownView } from "obsidian";
import { Platform, Plugin, TFile } from "obsidian";
import "../manifest.json";
import { HistoryView } from "./views/history/history-view";
import { StatusBar } from "./views/status-bar/status-bar";
import { LogsView } from "./views/logs/logs-view";
import { StatusDescription } from "./views/status-description/status-description";
import { SyncClient, rateLimit, DEFAULT_SETTINGS, Logger } from "sync-client";
import {
SyncClient,
rateLimit,
DEFAULT_SETTINGS,
Logger,
debugging
} from "sync-client";
import { ObsidianFileSystemOperations } from "./obsidian-file-system";
import { SyncSettingsTab } from "./views/settings/settings-tab";
import { logToConsole } from "./utils/log-to-console";
import { updateEditorStatusDisplay } from "./views/editor-sync-line/editor-sync-line";
import { EditorStatusDisplayManager } from "./views/editor-status-display-manager/editor-status-display-manager";
import { remoteCursorsTheme } from "./views/cursors/remote-cursor-theme";
import {
remoteCursorsPlugin,
RemoteCursorsPluginValue
} from "./views/cursors/remote-cursors-plugin";
import { LocalCursorUpdateListener } from "./views/cursors/local-cursor-update-listener";
import { slowFetchFactory } from "./debugging/slow-fetch-factory";
import { flakyWebSocketFactory } from "./debugging/flaky-websocket-factory";
import { renderCursorsInFileExplorer } from "./views/cursors/file-explorer";
const MIN_WAIT_BETWEEN_UPDATES_IN_MS = 250;
@ -48,8 +52,8 @@ export default class VaultLinkPlugin extends Plugin {
const debugOptions = isDebugBuild
? {
fetch: slowFetchFactory(1),
webSocket: flakyWebSocketFactory(1, new Logger())
fetch: debugging.slowFetchFactory(1),
webSocket: debugging.slowWebSocketFactory(1, new Logger())
}
: {};
@ -66,7 +70,9 @@ export default class VaultLinkPlugin extends Plugin {
...debugOptions
});
logToConsole(this.client);
if (isDebugBuild) {
debugging.logToConsole(this.client);
}
const statusDescription = new StatusDescription(this.client);
@ -94,6 +100,7 @@ export default class VaultLinkPlugin extends Plugin {
this.client.addRemoteCursorsUpdateListener((cursors) => {
RemoteCursorsPluginValue.setCursors(cursors, this.app);
renderCursorsInFileExplorer(cursors, this.app);
});
const cursorListener = new LocalCursorUpdateListener(
@ -122,17 +129,23 @@ export default class VaultLinkPlugin extends Plugin {
this.registerEditorEvents();
await this.client.start();
const interval = setInterval(() => {
updateEditorStatusDisplay(this.app.workspace, this.client);
}, 200);
const editorStatusDisplayManager = new EditorStatusDisplayManager(
this,
this.app.workspace,
this.client
);
this.disposables.push(() => {
clearInterval(interval);
editorStatusDisplayManager.stop();
});
});
}
public onunload(): void {
this.client.stop();
this.client.waitAndStop().catch((err: unknown) => {
this.client.logger.error(
`Error while stopping the sync client: ${err}`
);
});
this.disposables.forEach((disposable) => {
disposable();
});

View file

@ -0,0 +1,15 @@
.remote-users {
display: flex;
flex-wrap: wrap;
gap: var(--size-4-2);
margin-left: var(--size-4-2);
span {
border-radius: var(--radius-l);
padding: 0 var(--size-4-1);
border-width: 1.4px;
border-style: solid;
font-size: var(--font-smallest);
font-style: italic;
}
}

View file

@ -0,0 +1,55 @@
import "./file-explorer.scss";
import type { App, View } from "obsidian";
import {
utils,
type MaybeOutdatedClientCursors,
type RelativePath
} from "sync-client";
const REMOTE_USER_CONTAINER_CLASS = "remote-users";
export function renderCursorsInFileExplorer(
cursors: MaybeOutdatedClientCursors[],
app: App
): void {
const fileExplorers = app.workspace.getLeavesOfType("file-explorer");
if (fileExplorers.length == 0) return;
const [fileExplorer] = fileExplorers;
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
const fileExplorerView: View & {
fileItems: Record<RelativePath, { el: Element }>; // it's an internal API
} = fileExplorer.view as any; // eslint-disable-line
for (const key in fileExplorerView.fileItems) {
const element =
fileExplorerView.fileItems[key].el.querySelector(".tree-item-self");
const customElement = createDiv(
{
cls: REMOTE_USER_CONTAINER_CLASS
},
(parent) => {
cursors.forEach((cursor) => {
cursor.documentsWithCursors.forEach((document) => {
if (document.relative_path === key) {
parent.appendChild(
createSpan({
text: cursor.userName,
attr: {
style: `border-color: ${utils.getRandomColor(cursor.userName)}`
}
})
);
}
});
});
}
);
element?.querySelector("." + REMOTE_USER_CONTAINER_CLASS)?.remove();
element?.appendChild(customElement);
}
}

View file

@ -1,5 +1,5 @@
import type { Editor } from "obsidian";
import { lineAndColumnToPosition } from "../../utils/line-and-column-to-position";
import { utils } from "sync-client";
export interface Selection {
id: number;
@ -11,7 +11,7 @@ export function getSelectionsFromEditor(editor: Editor): Selection[] {
const text = editor.getValue();
return editor.listSelections().map(({ anchor, head }, i) => ({
id: i,
start: lineAndColumnToPosition(text, anchor.line, anchor.ch),
end: lineAndColumnToPosition(text, head.line, head.ch)
start: utils.lineAndColumnToPosition(text, anchor.line, anchor.ch),
end: utils.lineAndColumnToPosition(text, head.line, head.ch)
}));
}

View file

@ -9,12 +9,15 @@ import type {
ViewUpdate
} from "@codemirror/view";
import { RemoteCursorWidget } from "./remote-cursor-widget";
import type { CursorSpan, MaybeOutdatedClientCursors } from "sync-client";
import {
utils,
type CursorSpan,
type MaybeOutdatedClientCursors
} from "sync-client";
import type { App } from "obsidian";
import { MarkdownView } from "obsidian";
import { StateEffect } from "@codemirror/state";
import { getRandomColor } from "src/utils/get-random-color";
import type { SpanWithHistory } from "reconcile-text";
import { reconcileWithHistory } from "reconcile-text";
@ -155,7 +158,7 @@ export class RemoteCursorsPluginValue implements PluginValue {
RemoteCursorsPluginValue.cursors.forEach(
({ name, span: { start, end } }) => {
const color = getRandomColor(name);
const color = utils.getRandomColor(name);
const startLine = update.view.state.doc.lineAt(start);
const endLine = update.view.state.doc.lineAt(end);

View file

@ -0,0 +1,43 @@
.vault-link-sync-status {
position: absolute;
right: var(--size-4-4);
top: var(--size-4-2);
opacity: 0.7;
cursor: pointer;
> span {
opacity: 0;
position: absolute;
min-width: 200px;
text-align: right;
padding-right: var(--size-2-2);
top: 50%;
left: 0;
transform: translateY(-50%) translateX(-100%) translateY(-2px);
transition: opacity 200ms;
}
&:hover {
> span {
opacity: 1;
}
}
> .icon {
line-height: 0;
}
&.loading > .icon {
animation: spin 2s linear infinite;
@keyframes spin {
0% {
transform: rotate(0deg);
}
100% {
transform: rotate(360deg);
}
}
}
}

View file

@ -0,0 +1,97 @@
import type { Workspace } from "obsidian";
import { FileView, setIcon } from "obsidian";
import type { SyncClient } from "sync-client";
import { DocumentSyncStatus } from "sync-client";
import "./editor-status-display-manager.scss";
import type VaultLinkPlugin from "src/vault-link-plugin";
import { HistoryView } from "../history/history-view";
export class EditorStatusDisplayManager {
private static readonly UPDATE_INTERVAL_IN_MS = 100;
private readonly intervalId: NodeJS.Timeout;
private readonly lastStatuses = new Map<string, DocumentSyncStatus>();
public constructor(
private readonly plugin: VaultLinkPlugin,
private readonly workspace: Workspace,
private readonly client: SyncClient
) {
this.intervalId = setInterval(() => {
this.updateEditorStatusDisplay();
}, EditorStatusDisplayManager.UPDATE_INTERVAL_IN_MS);
}
public stop(): void {
clearInterval(this.intervalId);
}
private updateEditorStatusDisplay(): void {
this.workspace.iterateAllLeaves((leaf) => {
if (leaf.view instanceof FileView) {
const filePath = leaf.view.file?.path;
if (filePath == null) {
return;
}
const element = this.getElementFromLeaf(leaf.view);
if (element == null) {
return;
}
const previousStatus = this.lastStatuses.get(filePath);
const currentStatus =
this.client.getDocumentSyncingStatus(filePath);
if (previousStatus === currentStatus) {
return;
}
this.lastStatuses.set(filePath, currentStatus);
if (currentStatus == DocumentSyncStatus.SYNCING_IS_DISABLED) {
element.remove();
return;
}
if (currentStatus == DocumentSyncStatus.SYNCING) {
element.classList.add("loading");
} else {
element.classList.remove("loading");
}
const iconContainer = element.querySelector(".icon");
if (iconContainer != null) {
setIcon(
iconContainer as HTMLElement, // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
currentStatus == DocumentSyncStatus.SYNCING
? "loader"
: "circle-check"
);
}
}
});
}
private getElementFromLeaf(fileView: FileView): Element | undefined {
const parent = fileView.contentEl.querySelector(".cm-editor");
if (parent == null) {
return;
}
return (
parent.querySelector(".vault-link-sync-status") ??
parent.createDiv(
{
cls: "vault-link-sync-status"
},
(el) => {
el.createSpan({ text: "VaultLink sync state" });
el.createDiv({
cls: "icon"
});
el.onclick = async (): Promise<void> =>
this.plugin.activateView(HistoryView.TYPE);
}
)
);
}
}

View file

@ -1,55 +0,0 @@
import type { Workspace } from "obsidian";
import { FileView, setIcon } from "obsidian";
import type { SyncClient } from "sync-client";
import { DocumentSyncStatus } from "sync-client";
import "./editor-sync-line.scss";
export function updateEditorStatusDisplay(
workspace: Workspace,
client: SyncClient
): void {
workspace.iterateAllLeaves((leaf) => {
if (leaf.view instanceof FileView) {
const filePath = leaf.view.file?.path;
if (filePath == null) {
return;
}
const parent = leaf.view.contentEl.querySelector(".cm-editor");
if (parent == null) {
return;
}
const element =
parent.querySelector(".vault-link-sync-status") ??
parent.createDiv(
{
cls: "vault-link-sync-status"
},
(el) => {
el.createSpan({ text: "VaultLink sync state" });
el.createDiv({
cls: "icon"
});
}
);
const isLoading =
client.getDocumentSyncingStatus(filePath) ==
DocumentSyncStatus.SYNCING;
if (isLoading) {
element.classList.add("loading");
} else {
element.classList.remove("loading");
}
const iconContainer = element.querySelector(".icon");
if (iconContainer != null) {
setIcon(
iconContainer as HTMLElement, // eslint-disable-line @typescript-eslint/no-unsafe-type-assertion
isLoading ? "loader" : "circle-check"
);
}
}
});
}

View file

@ -8,7 +8,7 @@
"allowSyntheticDefaultImports": true,
"lib": [
"DOM",
"ESNext"
"ES2024"
]
},
"exclude": [

File diff suppressed because it is too large Load diff

View file

@ -24,7 +24,7 @@
"eslint": "9.28.0",
"eslint-plugin-unused-imports": "^4.1.4",
"npm-check-updates": "^18.0.1",
"prettier": "^3.5.3",
"typescript-eslint": "8.33.1"
"prettier": "^3.6.2",
"typescript-eslint": "8.41.0"
}
}

View file

@ -1,3 +0,0 @@
module.exports = {
preset: "ts-jest"
};

Some files were not shown because too many files have changed in this diff Show more