@alwith/module-drive

Pre-release shared Drive module. This package ships the frontend and the private native Drive library (native/); the Tauri plugin alwith-drive (crates.io) carries the public types, typed commands and the transactional Rust API. Frontend and library versions always match. The engine was extracted from ALwith Desktop; desktop-provenance.json (kept in the repository, not published) records the source revision.

Entry points

• @alwith/module-drive: generated protocol types, transport interface and controller.
• @alwith/module-drive/react: controller subscriptions, launcher/settings/status panels, permissions, badges, mass-delete confirmation, localization and pinned-entry helpers. Inject host shadcn controls and navigation.
• @alwith/module-drive/content: comments, Markdown/HTML integration, collaboration, frontmatter, versions, knowledge jobs, chat suggestions, cross-project move and file-link helpers.
• @alwith/module-drive/tauri: createTauriDriveTransport() over the plugin's commands and drive:event.
• @alwith/module-drive/commands: generated typed plugin commands and events.
• @alwith/module-drive/styles.css: scoped semantic-token styles.

Host contract

Register .plugin(alwith_drive::init(Config::new(|app| ...).event_windows(["main"]).development_directory(development_directory))); the closure opens the one DriveService from application data, a shared ownership registry, default local directory, reserved legacy application directories, device identity and a system browser opener. A start failure is kept and returned by every command. The plugin delivers drive:event to the configured windows and replaces a lagging subscriber's skipped events with a fresh snapshot (generation/sequence contract); a failed transport stream (queue overflow) is reported as an error, never as a resynchronization. Grant alwith-drive:default (allow-request) to windows that use Drive. alwith-drive:allow-session-request (MCP and collaboration credentials: mcpSessionConfig, collabSession) and alwith-drive:allow-collaborative-write (writeCollaborativeDocument) are separate permissions; grant them to every window the application trusts with the user's Drive session, such as Desktop's chat windows. The plugin does not restrict them to a window label. Keep credentials out of snapshots, logs and persisted frontend state.

Subscribe before fetching the initial snapshot. createDriveController buffers this interval and reconciles generation/sequence gaps. A window's disposal stops its listener, not the application service. Before exit call app.state::<Drive>(): begin_shutdown() once, then await shutdown() (cancels transactions, drains and stops synchronization, ends event delivery), then exit; is_stopped() tells the exit hook to let the exit through.

All native filesystem mutations that can intersect the Drive root must run through DriveService::with_filesystem (or with_collaborative_filesystem, with_move_to_filesystem) after host path authorization; dropping the future cancels the transaction. Pass exact write destinations and removed source paths. It serializes native changes with complete sync rounds, checks indexed read-only/collaboration state, and records successful removal intent. This coarse coordinator can delay operations during a transfer. It is not an OS sandbox: external editors and agents use ordinary filesystem permissions.

New roots must be empty by default. Hosts may opt into DriveService::with_existing_default_root() to adopt existing files only at their configured default root. This does not move or delete files and does not relax ownership checks for registered roots or custom directories. Ownership is persisted by canonical root, account/server and host data directory; overlapping roots and reuse by another profile are rejected. Legacy clients do not participate in the registry: sharing a default directory requires the same server/account and strictly sequential operation, with the previous sync process fully stopped. Hosts upgrading from ALwith Desktop pass OpenOptions::new().legacy_desktop(LegacyDesktopProfile { store, settings, index }) to DriveService::open: store is Desktop's drive.json named store (baseUrl, token, deviceId, localRoot, userName), settings its settings.json (drive.* keys) and index its drive/index.sqlite3. When the plugin has no profile.json yet, Drive reports the Desktop profile as configured; the first operation that needs it (normally start) identifies the account, adopts Desktop's directory, moves the index (with WAL files) into the profile and writes the profile with Desktop's preferences, download threshold, server configuration and local server overrides. Without network that operation fails and the import stays pending; logout declines it. Desktop's files other than the index are never changed, and a written profile file, signed in or not, ends the import for good.

Credentials are stored in a native atomic profile file (owner-only permissions on Unix); protect the containing app data directory on the host OS. Logout preserves local files. Revocation retains the extracted engine's cleanup/residual behavior. Use dedicated accounts and temporary directories when testing revocation.

Current boundaries

This remains an integration candidate pending real service and multi-client acceptance. The panel provides separate launcher, settings and status modes; the host supplies native directory selection, navigation, settings routing and external opening. It uses the existing workspace rather than rendering a second tree. Download preference changes reload the engine while preserving pause state.

Opt into content integration by mounting DriveContentProvider, wrapping managed documents in CommentSurface, and merging drivePreviewIntegrations into the shared editor host. Supply saveDocument and track collaboration ownership. Route authorized collaborative atomic writes through with_collaborative_filesystem; ordinary writes remain subject to with_filesystem. Lock source editing separately from collaborative preview permissions. The content entry requires its documented optional Milkdown, Yjs and editor peer dependencies.

Mount DriveMassDeleteDialog in the primary window independently of panel visibility. ChatCondenseEntry takes host preference storage for its 30-day snooze; pass approved jobs to DriveCondense.initialJob. Keep dialog ownership outside transient context menus. Hosts choose their OS link scheme; avoid claiming another application's registered protocol.

Archive is disabled by default. Hosts obtain explicit consent, export dialogue through their existing conversation owner, and provide expectedGeneration with each upload. Native code rechecks consent, private-session exclusion, workspace markers and generation before filtering and uploading. Archive metadata contains hashes and status, not a second conversation store. Knowledge and MCP configuration are resolved for each explicit session workspace. Configure a skills directory before starting the native engine.

Removal intent is inherited in-memory engine state; crash-safe delete/move recovery is not provided. The shared service adds no database schema migration. The editor host must preserve dirty buffers and check expected file versions. Native workspace size limits still apply after downloads. Cloud-only files cannot be edited locally; collaborative files require the explicit owner adapter rather than ordinary source writes.

Generated JSON numeric fields use JavaScript numbers, matching the existing transport. Values outside JavaScript's safe integer range are not supported; remote identifiers preserve string variants.

Development

bun install
bun run bindings   # regenerates src/generated/commands.ts and src/contract.ts from the plugin
bun test src
cargo test --manifest-path rust/Cargo.toml
bun run build

Use the repository's scripts/build-npm.ts builder. With the native library built, ALWITH_NATIVE_DIRECTORY=<target/debug> cargo test --manifest-path rust/Cargo.toml -- --ignored exercises the client against it. Publish only after an explicit release decision and real native, multi-process and supported-platform validation.

Desktop capabilities

• DriveService::open(options, OpenOptions) adds host choices: session_archive_directory (native session archive), default_preferences (preferences of a profile that has not chosen any; Desktop used knowledgeInject: true) and legacy_desktop (above). DriveService::new(options) keeps the previous behavior.
• Session archive: with session_archive_directory, Drive archives that conversation directory when it starts, every five minutes and on archiveSyncNow, only while sessionArchive is on, skipping sessions marked private. Each round emits archive events (syncing true, then false with the counts) and archiveStatus reports the native archive. Without the directory, hosts keep exporting conversations themselves with archiveSession, and archiveSyncNow is an error.
• Server overrides: serverOverrides / setServerOverrides { overrides } read and change webBaseUrl, collabRelayUrl, transferConcurrency (1 to 64) and maxUploadMb (0 unlimited). They persist beside the profile across sign-out. Addresses apply only while the server has not published its client configuration; maxUploadMb yields to a server limit. A running engine restarts with its pause state preserved.
• moveToCloudDirectory { sources, directory } moves Drive items into a cloud folder that has not landed locally and answers cloudMove { moved, error }.
• recheckCloudOnly answers cloudOnlyRecheck with its counts, and engine rechecks emit cloudOnly events (contract generation 2).
• searchUsers { query, limit? }: 1 to 50 users, 20 when absent.
• knowledgeContext is cached for ten minutes per workspace and cleared by any profile, preference or engine change.