Phase 2: Backend Service & GitHub Integration for Component Schema PR Authoring

# Component Schema PR Authoring - Phase 2

This issue tracks Phase 2+ of the Component Schema PR Authoring feature, building on the completed Phase 1 schema conversion library.

## ✅ Phase 1 Complete

The `@adobe/component-schema-converter` package has been implemented with:
- Pure functions for bidirectional conversion between plugin format and official JSON Schema
- Comprehensive validation (plugin format, official schema, JSON Schema 2020-12)
- 135 passing tests with >95% coverage
- Full documentation with API reference and examples

**Package Location:** `packages/component-schema-converter/`
**Plan Document:** `.cursor/plans/component_schema_pr_integration_38e21d48.plan.md`

## 🎯 Phase 2: Backend Service & PR Creation

### Overview
Enable the Component Options Editor Figma plugin to create pull requests against `packages/component-schemas` with schema changes via a backend service.

### Components Needed

#### 1. Backend Service (Node.js/Express)
- **Endpoint:** `POST /api/convert-and-create-pr`
- **Responsibilities:**
- Receive plugin format JSON from Figma plugin
- Convert to official schema using `@adobe/component-schema-converter`
- Create changeset file following repo conventions
- Create branch, commit changes, and open PR via GitHub API
- Return PR URL to plugin

**Technical Requirements:**
- Use ES modules (matches project standards)
- Follow monorepo tooling standards (pnpm, moon, AVA)
- Implement rate limiting and error handling
- Add comprehensive logging

#### 2. GitHub App Setup & OAuth
- **Create GitHub App** for authentication
- Configure OAuth flow
- Set required permissions (contents: write, pull_requests: write)
- Generate and securely store app credentials

- **OAuth Implementation:**
- Backend handles OAuth callback
- Issues temporary tokens to plugin
- Token refresh mechanism
- Secure token storage

**Alternative:** Support Personal Access Token (PAT) flow as fallback

#### 3. Figma Plugin Integration
- **UI Updates:**
- Add "Create PR" button to plugin interface
- Authentication flow (GitHub App or PAT input)
- PR creation progress indicator
- Success screen with PR link
- Error handling and user feedback

- **Communication:**
- Plugin sends schema data to backend service
- Backend returns PR URL or error details
- Store auth state in Figma plugin storage

#### 4. Changeset Generation
- **Auto-generate changeset files** following `.changeset/` conventions:
- Template: `"Add {component-name} component schema"` for new components
- Template: `"Update {component-name} component schema"` for existing
- Semver type: `minor` for new components, `patch` for updates
- Include detailed change description

#### 5. File Conflict Resolution
- **Scenarios to handle:**
- New component schema (straightforward)
- Update existing schema (check for conflicts)
- Schema already exists with different structure
- Branch naming conflicts

- **Strategy:**
- Generate unique branch names: `component-schema/{component-name}-{timestamp}`
- Detect file conflicts before PR creation
- Provide clear error messages to user

### Acceptance Criteria

- [ ] Backend service deployed and accessible from Figma plugin
- [ ] GitHub App created and OAuth flow functional
- [ ] Figma plugin can authenticate users via GitHub
- [ ] Plugin successfully converts and submits schema changes
- [ ] Backend creates properly formatted PRs with:
- [ ] Converted schema file in `packages/component-schemas/schemas/components/`
- [ ] Generated changeset file in `.changeset/`
- [ ] Descriptive PR title and body
- [ ] Proper branch naming
- [ ] Error handling covers all failure scenarios
- [ ] Documentation updated with:
- [ ] Backend service setup instructions
- [ ] GitHub App configuration guide
- [ ] Figma plugin usage guide for PR creation
- [ ] Tests added for:
- [ ] Backend endpoints (unit + integration)
- [ ] Changeset generation
- [ ] Error scenarios

### Architecture Diagram

```mermaid
flowchart TD
FigmaPlugin[Figma Plugin UI]
Backend[Backend Service]
Converter[Schema Converter Library]
GitHub[GitHub API]

FigmaPlugin -->|1. Authenticate| Backend
Backend -->|2. OAuth Flow| GitHub
FigmaPlugin -->|3. Submit Schema| Backend
Backend -->|4. Convert| Converter
Backend -->|5. Generate Changeset| Backend
Backend -->|6. Create Branch & PR| GitHub
Backend -->|7. Return PR URL| FigmaPlugin
```

### Implementation Notes

**Security Considerations:**
- Never expose GitHub App secrets in client code
- Use HTTPS for all backend communication
- Implement CSRF protection
- Rate limit API endpoints
- Validate all input data

**Testing Strategy:**
- Unit tests for backend endpoints
- Integration tests with GitHub API (using test repos)
- E2E tests from Figma plugin through PR creation
- Mock GitHub API for fast test execution

**Deployment:**
- Backend service needs to be hosted (consider: Vercel, AWS Lambda, Azure Functions)
- Environment variables for GitHub App credentials
- CI/CD pipeline for automatic deployment

### Related Files

- Schema converter library: `packages/component-schema-converter/`
- Figma plugin: `tools/component-options-editor/`
- Component schemas: `packages/component-schemas/`
- Changesets config: `.changeset/config.json`
- Plan document: `.cursor/plans/component_schema_pr_integration_38e21d48.plan.md`

### Dependencies

- `@adobe/component-schema-converter` (Phase 1 - ✅ Complete)
- GitHub API client (e.g., `@octokit/rest`)
- Express or similar web framework
- Authentication library for GitHub OAuth

### Future Enhancements (Phase 3+)

- Preview schema changes before PR creation
- Batch PR creation for multiple components
- Schema validation against existing components
- Automated tests in PR for schema changes
- Integration with design review process
- Metrics and analytics for schema submissions

---

**Started:** Phase 1 completed on 2026-01-21
**Estimated Effort:** Phase 2 is a substantial undertaking requiring backend infrastructure setup

Start with .cursor/plans/component_schema_pr_integration_38e21d48.plan.md, then inspect packages/component-schema-converter/ and tools/component-options-editor/ to understand the completed Phase 1 and plugin boundary. The work is done when the backend, authentication flow, PR and changeset creation, plugin UI integration, tests, deployment, and documentation meet the listed acceptance criteria.

Written by the indexing model from the issue text.