Runbook: URL-import Deployment

Purpose

Step-by-step guide to deploy URL-import feature (master spec v1.3) к production. Not an alert runbook — this is operational checklist для new feature rollout.

URL-import has 3 deployable components:

Backend API (apps/api) — Hono Worker с new /api/v1/url-imports/* endpoints
Frontend (apps/web) — Next.js Pages с new /app/imports routes
CLI extractor (packages/url-import-extractor) — user-installable Node tool

Database changes:

Migration 0007_url_import_staged_components — new staged_component table
Migration 0008_url_import_raw_html — adds raw_html column

Pre-deployment checklist

All tests passing — pnpm --filter @arno/url-import-extractor test (95 tests)
Typechecks clean — pnpm -r typecheck (except known git-provider issue)
CI workflow green on latest main
Migration files reviewed (tools/migrate/drizzle/0007_*.sql, 0008_*.sql)
Legal review of ToS + Privacy clauses complete (см legal brief)
Tranco list snapshot prepared (для domain reputation check)
Atom catalog seeded с shadcn (one-time бутстрап)

Deployment order

Must be done in this order. Each step может be done независимо если pre-reqs met.

Step 1: Run database migrations

# Required env: DATABASE_URL=postgres://user:pass@host/db
cd /Users/vadimpianof/Desktop/Claude/ARNO/tools/migrate
 
# Verify what's pending
pnpm tsx scripts/migrate.ts status
 
# Apply pending migrations
pnpm tsx scripts/migrate.ts up
 
# Expected output:
#   ✓ 0007_url_import_staged_components.sql applied
#   ✓ 0008_url_import_raw_html.sql applied

Verification:

\d staged_component
-- Should show all columns including raw_html

Rollback (если что-то сломалось):

DROP TABLE IF EXISTS staged_component CASCADE;
-- Then revert journal entry в meta/_journal.json

Step 2: Deploy backend (apps/api)

cd apps/api
 
# Required env vars in wrangler.toml or .dev.vars (production):
#   DATABASE_URL (Neon connection string)
#   JWT_SECRET (256-bit secret)
#   GITHUB_CLIENT_ID
#   GITHUB_CLIENT_SECRET
#   LIVEBLOCKS_SECRET_KEY
#   GITHUB_APP_ID
#   GITHUB_APP_PRIVATE_KEY (base64'd)
#   GITHUB_WEBHOOK_SECRET
 
# Deploy:
pnpm wrangler deploy
 
# Verify deployment:
curl https://arno-api.vadimpianof.workers.dev/health
# Should return {"ok": true, "ts": <epoch>}

URL-import endpoints verification (после auth flow):

# Get JWT token first (sign in to /app)
TOKEN="<your jwt from browser localStorage[arno_token]>"
 
# Should return empty list initially
curl -H "Authorization: Bearer $TOKEN" \
  https://arno-api.vadimpianof.workers.dev/api/v1/me/url-imports
 
# Expected: {"items": []}

Step 3: Deploy frontend (apps/web)

cd apps/web
pnpm build
 
# Output: out/ folder ready для Cloudflare Pages
# Wrangler Pages deploy:
pnpm wrangler pages deploy out --project-name=arno-ijr
 
# Verify:
curl https://arno-ijr.pages.dev/app/imports
# Should return HTML for imports page (404 if missing, 200 ok)

Manual smoke test:

Sign in at https://arno-ijr.pages.dev/app (opens in a new tab)
Navigate to "/app/imports" (or click "URL imports →" link in projects list)
Should see empty state with CLI instructions
Tab between Preview/TSX/Types/etc should work на existing imports

Step 4: Distribute CLI extractor

CLI ships как part of monorepo, не published к npm pока. User clones repo:

git clone https://github.com/vadimpianov/arno.git
cd arno/packages/url-import-extractor
pnpm install
pnpm dlx playwright install chromium
 
# Test extraction
pnpm extract https://ui.shadcn.com
 
# Test upload (requires ARNO_TOKEN)
export ARNO_TOKEN="<jwt from /app login>"
pnpm extract https://ui.shadcn.com --upload

Distribution alternative для V2:

Publish к npm как @arno/url-import-extractor
Or bundle into ARNO CLI tool

Post-deployment verification

Smoke test 1: Empty state

1. Sign in at /app
2. Click "URL imports →"
3. See empty state с CLI instructions
4. No errors в browser console

Smoke test 2: Full upload flow

1. From terminal с ARNO_TOKEN set:
   pnpm extract https://ui.shadcn.com --upload
2. Should output "Uploaded: 8/8" (or similar)
3. Refresh /app/imports
4. Should see 8 imported components
5. Click any component
6. Preview tab should show iframe с rendered HTML
7. Tabs (tsx, types, tokens, stories, manifest) all loadable
8. Click "Edit" on tsx tab → textarea opens
9. Modify code → Save → "Saved ✓" appears
10. Refresh → changes persisted

Smoke test 3: Error paths

1. CLI без ARNO_TOKEN: `pnpm extract <url> --upload`
   Expected: error message с instructions to set token, exit code 4

2. CLI с invalid URL: `pnpm extract not-a-url`
   Expected: SSRF guard rejects, exit code 2

3. CLI с private IP: `pnpm extract http://192.168.1.1`
   Expected: SSRF guard rejects (no safe IPs)

4. Frontend без auth: visit /app/imports directly без login
   Expected: AuthGate redirects to /auth/github/login

Monitoring / alerts

URL-import-specific metrics для Grafana dashboard:

Metric	Source	Threshold
`url_imports_total{status}`	API counter	spike > 200% 7-day avg → investigate
`url_imports_extraction_duration_seconds`	CLI logs	p95 > 30s → investigate
`url_imports_size_bytes`	DB column sizes	> 4MB per row → investigate
`staged_components_count_by_user`	DB query	> 1000/user → anti-abuse

Suggested alerts (master spec §II.6):

5xx error rate on /api/v1/url-imports/* > 5% → PAGE
DB size growth > 1GB/day → review staging lifecycle policy
Failed verifications (Phase 6 fail) > 30% → algorithm regression

Known limitations / V1 caveats

Online extraction NOT deployed — only CLI works
- User runs locally, uploads to backend
- V2: deploy extractor as Modal Labs function для server-side trigger
GitHub push NOT implemented — only staging
- Staged components live in B2/Postgres
- V2: GitHub App + branch + PR creation
No Phase 7 vision fallback — pure code-only mode
- Falls back к template TSX when generation incomplete
- V2: Gemini API integration
Atom catalog NOT seeded — L3 cache hit 0% on day 1
- V2: pre-load shadcn/ui atoms (~50 components → 200 atoms)

Rollback procedure

Если URL-import deployment causes issues:

# 1. Hide UI nav link (frontend revert)
cd apps/web
# Revert commit that added nav link to projects-list.tsx
git revert <commit-sha>
pnpm build && pnpm wrangler pages deploy out
 
# 2. Disable API endpoints (backend revert)
cd apps/api
# Revert mount in index.ts:
# app.route("/", urlImportsApp);  → comment out
pnpm wrangler deploy
 
# 3. (Optional) Drop staging table if data is corrupted
psql $DATABASE_URL -c "DROP TABLE staged_component CASCADE;"
 
# Migrations 0007/0008 reversible через manual SQL.

References

url_import_spec.md — canonical feature spec
ADR 0007-0018 — design decisions
Test suite — 95 tests
Atom PoC — algorithm validation
Legal review brief — pre-launch legal items

Runbook: Liveblocks outage Runbook: URL-import SSRF guard rejection spike