Harden data export, import, backup, and generated-state rebuild flows #80

New issue

Closed

opened 2026-05-22 11:30:32 +00:00 by steve · 0 comments

steve commented

2026-05-22 11:30:32 +00:00

Owner

Improve the app's data safety and recovery flows so users can export, import,
back up, and rebuild generated state without risking canonical notes.

Problem

Lapis is local-first and file-oriented, but browser-local storage such as OPFS
is opaque to many users. A complete notes app needs explicit export, import,
backup, and rebuild flows so users can trust that their notes remain portable
and recoverable.

Goal

Add or harden user-facing data safety flows for browser-local vaults,
Electron-backed vaults, and generated-state rebuild paths across the app.

Sequencing

This is step 4 of the recommended six-issue sequence.
Start this issue after 78 so data recovery and rebuild flows align with the Safe Mode model and canonical-versus-generated-state recovery language.
Complete this issue before 79 and 81.
Notebook and test work that depends on generated-state semantics should inherit the terminology and commands defined here.

Scope

For browser or PWA vaults, support export and import of a portable vault
format and show that OPFS storage is browser-local.
For Electron vaults, support revealing the backing folder and provide a clear
export or copy path.
For all platforms, distinguish canonical user files from generated app data.
Add actions to rebuild metadata, search, and notebook-generated state.
Surface progress and errors for import, export, backup, and rebuild flows.
Link these flows from release-readiness and data-safety docs.

Non-goals

Real-time sync.
Cloud backup.
Multi-device conflict resolution.
End-to-end encrypted remote storage.
Git integration.

Acceptance Criteria

Browser users can export a vault into a portable format.
Browser users can import a previously exported vault.
Electron users can reveal or open the underlying vault folder.
Users can rebuild metadata and search generated state without deleting notes.
Users can clear notebook outputs without deleting notebook source files.
Data-safety docs explain what is canonical and what is generated.
The app displays a warning or explanation for OPFS or browser-local vaults.
Import and export operations surface progress and errors.
At least one test covers export, import, or rebuild behavior.
The release checklist links to these data-safety flows.

Implementation Notes

Prioritize clear, reliable behavior over clever sync semantics.
Keep import and export formats simple and inspectable.
If browser folder export is harder than zip export, implement zip first.
Make rebuild actions idempotent where practical.
Ensure the app can recover from missing generated state on startup.

Suggested Files or Specs To Inspect

spec/src/20-packages/workspace/
spec/src/30-cross-package-contracts/storage-metadata-search.md
spec/src/20-packages/notebook/
spec/src/40-testing/current-state.md

Validation Commands

pnpm check
pnpm test:smoke

Follow-up Tasks

Split browser-only and Electron-only implementation follow-ups if the main
issue becomes too broad.
After this lands, move directly to 79.

Implementation Summary

Added browser-vault export with progress reporting, exposed reveal-folder and rebuild-generated-state commands, exposed notebook output clearing as a command, documented canonical-versus-generated data safety flows, and covered browser export in API storage tests.

Improve the app's data safety and recovery flows so users can export, import, back up, and rebuild generated state without risking canonical notes. ## Problem Lapis is local-first and file-oriented, but browser-local storage such as OPFS is opaque to many users. A complete notes app needs explicit export, import, backup, and rebuild flows so users can trust that their notes remain portable and recoverable. ## Goal Add or harden user-facing data safety flows for browser-local vaults, Electron-backed vaults, and generated-state rebuild paths across the app. ## Sequencing - This is step 4 of the recommended six-issue sequence. - Start this issue after [78](78-add-safe-mode-and-recovery-flows-for-startup-plugin-layout-metadata-and-search-failures.md) so data recovery and rebuild flows align with the Safe Mode model and canonical-versus-generated-state recovery language. - Complete this issue before [79](79-polish-notebook-v0-into-a-reliable-understandable-feature.md) and [81](81-add-journey-based-e2e-and-smoke-tests-for-the-complete-daily-use-path.md). - Notebook and test work that depends on generated-state semantics should inherit the terminology and commands defined here. ## Scope - For browser or PWA vaults, support export and import of a portable vault format and show that OPFS storage is browser-local. - For Electron vaults, support revealing the backing folder and provide a clear export or copy path. - For all platforms, distinguish canonical user files from generated app data. - Add actions to rebuild metadata, search, and notebook-generated state. - Surface progress and errors for import, export, backup, and rebuild flows. - Link these flows from release-readiness and data-safety docs. ## Non-goals - Real-time sync. - Cloud backup. - Multi-device conflict resolution. - End-to-end encrypted remote storage. - Git integration. ## Acceptance Criteria - Browser users can export a vault into a portable format. - Browser users can import a previously exported vault. - Electron users can reveal or open the underlying vault folder. - Users can rebuild metadata and search generated state without deleting notes. - Users can clear notebook outputs without deleting notebook source files. - Data-safety docs explain what is canonical and what is generated. - The app displays a warning or explanation for OPFS or browser-local vaults. - Import and export operations surface progress and errors. - At least one test covers export, import, or rebuild behavior. - The release checklist links to these data-safety flows. ## Implementation Notes - Prioritize clear, reliable behavior over clever sync semantics. - Keep import and export formats simple and inspectable. - If browser folder export is harder than zip export, implement zip first. - Make rebuild actions idempotent where practical. - Ensure the app can recover from missing generated state on startup. ## Suggested Files or Specs To Inspect - `spec/src/20-packages/workspace/` - `spec/src/30-cross-package-contracts/storage-metadata-search.md` - `spec/src/20-packages/notebook/` - `spec/src/40-testing/current-state.md` ## Validation Commands - `pnpm check` - `pnpm test:smoke` ## Follow-up Tasks - Split browser-only and Electron-only implementation follow-ups if the main issue becomes too broad. - After this lands, move directly to [79](79-polish-notebook-v0-into-a-reliable-understandable-feature.md). ## Implementation Summary Added browser-vault export with progress reporting, exposed reveal-folder and rebuild-generated-state commands, exposed notebook output clearing as a command, documented canonical-versus-generated data safety flows, and covered browser export in API storage tests.

steve added the

subsystem:desktop-electron

data-safety

labels

2026-05-22 11:30:32 +00:00