Roadmap web import/export readiness

[Fredoq]

Summary

• harden the desktop import bridge and shared import review UI
• add export/onboarding trust copy for the browser and desktop export flows
• link private beta trust and release-readiness docs from the web README

Verification

• npm run format:check
• npm run lint
• npm run typecheck
• npm test
• npm run build

These checks passed locally before publishing the branch.

Summary by CodeRabbit

• Documentation

  • Expanded README and acceptance docs with clearer private-beta guidance, data-handling links, and boundaries for desktop imports/exports
  • Clarified that desktop imports send metadata, hashes, paths and cover art — not audio files

• New Features

  • Added user confirmation dialog when confirming import drafts
  • Added export guidance explaining snapshot portability and hosted backup responsibilities
  • Onboarding/sign-in text updated to reflect private-beta and bootstrap differences

• Style

  • Improved styling for onboarding notes, import/export guidance, and responsive import layouts

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds private-beta onboarding copy, documents desktop local-folder import/export boundaries, tightens desktop-scan DTOs, introduces Electron preload/scanner tests, updates import/export UIs and tests, adds user-confirmation for imports, responsive import CSS, and centralizes Electron backend URL config.

Changes

Private Beta Desktop Import/Export & Onboarding

Layer / File(s)	Summary
Documentation & Acceptance Guidance README.md, docs/acceptance-checklist.md	Expanded README and acceptance checklist with desktop import/export guidance, private beta data-handling links, product boundaries, and acceptance steps.
Desktop Scan Request Type Contract & Validation src/features/catalog/api/catalogTypes.ts, src/features/catalog/catalogApi.protocol.test.ts	Refactors DesktopFolderScanFileRequest into `DesktopAudioScanFileRequest
Electron Preload Bridge & Folder Scanner Tests electron/preload-contract.test.cjs, electron/scanner.test.cjs	Adds tests verifying the preload cratebaseDesktop bridge shape and scanner behavior (recursive scan, SHA-256 hashing, metadata shapes, audio bytes excluded, cover base64).
Auth Onboarding Messages & Styling src/app/AuthBoundary.tsx, src/features/auth/auth.css, src/App.auth.test.tsx	Adds mode-specific onboarding copy for bootstrap vs sign-in, new .auth-onboarding-note CSS, and test assertions for the visible guidance text.
Desktop Import UI, Confirmation & Messaging src/App.imports-exports.test.tsx, src/features/imports/ImportsWorkspace.tsx, src/features/imports/ImportReviewPanels.tsx	Adds desktop-mode import tests stubbing pickAndScan, validates /api/imports/desktop-folder-scans payloads exclude audio bytes while including metadata/hashes/cover artifacts, introduces window.confirm confirmation with cancellation handling, and clarifies import guidance copy.
Imports CSS: Layout, Wrapping & Responsive src/features/imports/imports.css	Adds min-width: 0 fixes, enables wrapping for small text, and adds responsive media queries to collapse/stack import panels on narrow screens.
Export UI, Download Routing & Styling src/App.exports.test.tsx, src/features/exports/ExportsWorkspace.tsx, src/features/exports/exports.css	Adds "Private beta export boundary" and "Export v1 limits" guidance, styles for export guidance, and tests covering browser HEAD-download flows, desktop bridge routing, failure/session handling, and UI status messages.
Electron Backend Config & Tests electron/backend-config.cjs, electron/backend-config.test.cjs, electron/main.cjs	Introduces localApiBaseUrl and resolveBackendBaseUrl() exported helper, centralizes backend URL selection in main.cjs, and adds tests for env override behavior.

Sequence Diagram(s)

See the "Desktop Import and Export Flow" diagram embedded in the hidden review stack artifact above.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Fredoq/cratebase-web#24: Related desktop import-flow changes (preload contract, scanner behavior) that align with the preload/scanner tests and IPC expectations in this PR.
• Fredoq/cratebase-web#29: Related tightening of desktop scan DTOs and scanner behavior (SHA-256 contentHash) referenced by the new type tests here.
• Fredoq/cratebase-web#25: Related ExportsWorkspace UI additions that this PR extends with export boundary guidance and limits.

Poem

🐰 I hop through folders, hashes bright,
I send just metadata, not the bytes,
Private-beta signs invite the crew,
Exports and tests confirm what's true,
A tiny rabbit cheers the new!

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Roadmap web import/export readiness' is somewhat vague and generic, using the term 'Roadmap' and 'readiness' without clearly conveying the specific changes made (hardening desktop import bridge, adding trust/onboarding copy, linking docs).	Refine the title to be more specific about the main changes, such as 'Harden desktop import bridge and add export/onboarding trust copy' or 'Add import/export trust documentation and hardening'.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description includes required sections (Summary with bullet points and Verification with checklist) and provides meaningful context about the changes, though it omits the Notes section from the template.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch roadmap_next

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Fredoq]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 0

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/features/imports/imports.css (1)

445-447: ⚡ Quick win

Adjust justify-content: stretch in the mobile override for .imports-folder-picker-actions

justify-content: stretch is a syntactically valid justify-content value, but in flexbox it doesn’t actually stretch along the main axis—it behaves like a flex-start alignment. If the intent is left alignment on small screens, switch to justify-content: flex-start; if the intent is true stretching, use flex-grow on the children (or align-items: stretch on the appropriate flex container for cross-axis stretching). [src/features/imports/imports.css, mobile block around lines 445-447]

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/features/imports/imports.css` around lines 445 - 447, The mobile override
for the .imports-folder-picker-actions selector uses justify-content: stretch
which doesn’t stretch on the main axis; replace it with justify-content:
flex-start if you want left alignment, or remove that rule and instead apply
flex-grow to the child elements (or set align-items: stretch on the parent if
cross-axis stretching is intended) so the layout actually stretches; update the
.imports-folder-picker-actions rule accordingly and adjust child element styles
(add flex: 1 or flex-grow as needed) to achieve true stretching.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/features/imports/imports.css`:
- Around line 445-447: The mobile override for the
.imports-folder-picker-actions selector uses justify-content: stretch which
doesn’t stretch on the main axis; replace it with justify-content: flex-start if
you want left alignment, or remove that rule and instead apply flex-grow to the
child elements (or set align-items: stretch on the parent if cross-axis
stretching is intended) so the layout actually stretches; update the
.imports-folder-picker-actions rule accordingly and adjust child element styles
(add flex: 1 or flex-grow as needed) to achieve true stretching.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 24344382-4eda-44b0-8889-d4fa1c496660

📥 Commits

Reviewing files that changed from the base of the PR and between 4e2e8a3 and 7c7df07.

📒 Files selected for processing (4)

• electron/backend-config.cjs
• electron/backend-config.test.cjs
• electron/main.cjs
• src/features/imports/imports.css

✅ Files skipped from review due to trivial changes (2)

• electron/backend-config.test.cjs
• electron/backend-config.cjs