- Date: 2026-05-24
- Status: Accepted
- Feature: URL-import (Extension MVP — §V «Small-company path / ARNO Studio» continuation)
- Affects: extractor_mvp_spec.md, url_import_spec.md § V, packages/url-import-extension, apps/api CORS, apps/web/settings
Context
CLI extractor (packages/url-import-extractor) уже production для public/scriptable use cases. Но он не покрывает основной use case target audience'a:
«Я залогинен на liveblocks.io / app.notion.so / dashboard.stripe.com своим аккаунтом. Я хочу импортировать компоненты с этой залогиненной страницы».
CLI не может — Playwright login flow эфемерный, cookies persisten не сохраняются, SAML/MFA блокируются. Нужен браузерный путь: extension работает в user session с user cookies/JWTs.
Это поднимает 4 связанных решения, которые надо зафиксировать вместе:
Q1. Persistence strategy для импортированных компонентов
Три camps обсуждались:
| Camp | Storage | Pros | Cons |
|---|---|---|---|
| Camp 1 — ARNO БД | Neon Postgres + R2 (existing) | Margin ~100% subscription revenue; matches existing infra; instant write; no GitHub coupling | We own infra cost; export-as-feature, не free side effect |
| Camp 2 — User GitHub | User connects repo, мы push'им | Free storage; familiar to devs | ~$4/user/мес GitHub Team requirement → margin падает до ~80%; non-devs не имеют GitHub; auth coupling; rate limits |
| Camp 3 — Hybrid | Cache в ARNO + sync к GitHub | Best of both | Двойная complexity; sync conflicts; неясный source-of-truth |
Q2. Auth provider stack
CLI/web использует GitHub OAuth (Phase 9). Target audience'у этого недостаточно — индивидуальные designers + small-mid enterprise часто не имеют GitHub аккаунта. Какие провайдеры включить?
| Option | Coverage | Cost | Implementation |
|---|---|---|---|
| GitHub only | ~30% target | 0 (existing) | Done |
| +75% global | $0 (free tier) | OAuth2 standard | |
| + Apple | +iOS/Mac users | $99/year Apple Dev | form_post + JWT parse |
| + Email magic link | universal fallback | Resend $20/mo (10k emails) | Backend KV TTL 15min |
| SAML/SSO | enterprise only | High (Auth0/WorkOS $0.50/user) | Defer to Phase 16+ |
Q3. Extension auth UX — auto-handoff с day 1 vs manual paste MVP
Auto-handoff (popup кнопка → arno.app/auth → OAuth → externally_connectable handshake → JWT в chrome.storage) требует:
- Stable EXTENSION_ID → manifest.key pinning → Web Store publish ($5 dev account + Google review 1-3 дня)
- externally_connectable manifest entry → matches только web origin → нельзя test на load-unpacked dev install
- Real branding icons (Web Store отклоняет placeholder)
Это блокирует validation cycle — мы не знаем работает ли capture на real auth-gated sites пока не запустим store-ready версию.
Q4. Destination model — direct project import vs inbox
| Option | Flow | Cons |
|---|---|---|
| Direct project | Popup → project picker → save → project's component lib | Project picker UX complexity; mid-capture project creation; multi-project edge cases |
| Inbox + promotion | Save → user's stagedComponent inbox → later promote к project | Extra UX step но clean separation; existing stagedComponent table reusable; promotion = Phase 15b feature |
Decision
D1. Camp 1 persistence — ARNO БД + R2
Все captured компоненты идут в stagedComponent table (existing, Phase 12-ish). GitHub integration становится opt-in export feature, не core data plane.
Импликация: Phase 13 GitHub App "Sync с репой" reframe'ится — теперь это «GitHub Export», не mandatory storage. Pure data flows ARNO БД → user может опционально push'ить к connected repo.
D2. 4-provider auth stack — Google + Apple + Email + GitHub
Покрывает ~95% target audience. SAML/SSO defer до enterprise demand (likely Phase 16+ когда первый enterprise prospect appears).
Backend changes parked для Phase 15a (~18-22h):
0010_user_provider.sqlmigration — adduser.providercolumn, relax GitHub-only constraints- 4 new endpoint sets: Google OAuth (
/auth/google/{login,callback}), Apple Sign In (/auth/apple/{login,callback}с form_post + JWT parsing), Email magic link (/auth/email/{request,verify}через Resend), GitHub existing - Multi-provider user upsert logic
D3. Manual paste MVP — auto-handoff в Phase 15d
Extension MVP (эта сессия — 6-8h) — temporary token paste textarea в popup. Юзер заходит на arnomake.com/app/settings → копирует JWT → paste в popup. Это работает с любым dev install (random extension ID).
После validation cycle:
- Phase 15a — auth backend (~18-22h)
- Phase 15b — onboarding wizard + 4-card chooser (~12-15h)
- Phase 15c — Web Store publish ($5 + 1-3 days Google review)
- Phase 15d — auto-handoff replace manual paste (~4-6h)
Полный UX путь = ~50-60h focused work + 1 week Google review = 2-3 недели до full UX.
D4. stagedComponent inbox destination
Capture сохраняется в stagedComponent table (user_id-scoped, no project_id). Юзер видит inbox в /app/imports. Promotion компонентов к specific project — Phase 15b feature, decoupled от capture validation.
Импликация: capture pipeline валидируется независимо от persistence redesign. Если quality плохая — не инвестируем дальше; если хорошая — Phase 15b добавляет project promotion.
Consequences
Positive
- Validation-driven roadmap. MVP отвечает на «работает ли capture на real auth SPAs?» за 6-8h. Если ответ «нет» — не инвестируем оставшиеся ~50h в Phase 15a-d.
- Margin предсказуем. Camp 1 даёт ~100% gross margin на subscription revenue, vs ~80% у Camp 2.
- Inclusive auth от MVP. К моменту publish multi-provider готов — мы не теряем 70% target audience requiring GitHub аккаунт.
- No locked-in vendor. Camp 1 = наша инфра (CF + Neon), уже там.
- Stable Phase 13 reframe. Connected repo + sync остаётся valuable feature, но как opt-in export.
Negative
- Storage cost на ARNO. Per Camp 2, юзер платил бы GitHub storage. Per Camp 1 — мы. Mitigation: R2 cheap ($0.015/GB-month), components small (~5KB each).
- MVP UX неполный. Manual paste — не «one-click install». Юзер должен зайти на сайт, скопировать токен. Acceptable для dogfood, не для Web Store launch.
- 4 auth providers = 4 OAuth integrations. ~18-22h Phase 15a effort. Apple особенно tricky (form_post mode + JWT parsing).
- Email magic link = Resend cost. ~$20/mo для 10k emails. Compared to Google/Apple/GitHub OAuth (free). Mitigation: пользователи default'ятся на social.
- Inbox model = extra promotion step. Юзер сохранил, но компоненты not yet in project. Mitigation: Phase 15b promotion UX = простой «assign to project» dropdown.
Reversibility
| Decision | Reversible? | Cost to reverse |
|---|---|---|
| D1 Camp 1 | Soft yes — можно добавить optional GitHub mirror в Phase 13 reframe | Low: existing sync code |
| D2 4-provider | Yes — drop unused providers если статистика shows один доминирует | Low: removed code, migration rolls back column |
| D3 MVP manual paste | Yes by design — Phase 15d explicitly replaces | Zero — спланировано |
| D4 inbox destination | Yes — Phase 15b promotion makes project_id assignment trivial | Low: добавляем column nullable, backfill optional |
Alternatives considered
A1. Hybrid Camp 3 (cache + GitHub sync)
Rejected: double complexity, sync conflicts unclear, doubles failure modes. Camp 1 single source-of-truth is simpler. Could revisit если enterprise customers требуют both.
A2. GitHub-only auth (status quo)
Rejected: target audience analysis showed indie designers и Figma-first product designers большинство не имеют активного GitHub аккаунта. Locking auth к GitHub = locking adoption к dev segment.
A3. Auth0 / WorkOS SSO
Rejected for MVP: $0.50/MAU стоимость для small-biz target unsustainable. Native OAuth implementations при 4 providers ~18-22h one-time cost, no ongoing per-user fee.
A4. Skip auto-handoff entirely, manual paste forever
Rejected: doesn't pass Web Store UX bar (one-click install expected by users), и manual paste = friction at moment user'a максимум готов engage (first install).
A5. Direct project picker в popup
Rejected for MVP: project picker UX adds 2-3 UI states, mid-capture project creation edge case complex. Inbox model = simpler validation, promotion can be added cleanly later.
A6. Safari + Firefox MVP support
Rejected for MVP scope: Safari requires $99 Apple Developer + Xcode build pipeline (paired с Mac desktop launch when Apple Dev is needed anyway). Firefox AMO publish process отличается от Chrome Web Store, low priority до Chrome Edge market saturation.
Cross-references
- docs/extractor_mvp_spec.md — canonical implementation spec этой сессии (Camp 1 + 4-provider + roadmap)
- docs/url_import_spec.md § V — master URL-import spec
- packages/url-import-extension/_index.md — MVP package layout
- packages/url-import-extractor/_index.md — CLI sibling, source для port'a
- ADR 0006 — backend-driven OAuth foundation (extended by D2)
- ADR 0016 — staging area decision (extended by D4 inbox)
- ADR 0017 — shadow data ToS (applies к extension capture data flow)