headquarter/openspec/changes/archive/2026-05-19-file-editor/specs/spec.md

File Editor Specification

Requirements

Functional Requirements

1. File Display: Show file contents with syntax highlighting for all text files
2. Language Detection: Automatically detect language from file extension
3. View Mode: Read-only display with line numbers and copy button
4. Edit Mode: Rich text editing with syntax highlighting
5. Commit Flow: Save changes via commit dialog with custom message
6. Diff Preview: Show changes before committing
7. File Support: All text-based files (source code, config, markdown, etc.)

Non-Functional Requirements

1. Performance: Load files < 500ms, highlighting < 100ms
2. Responsiveness: UI remains responsive during editing
3. Accessibility: Keyboard navigation, screen reader support
4. Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge)

API Specification

GET /projects/{project_id}/repositories/{repo_id}/files/content

Get file content (existing endpoint).

Query Parameters:

• branch (required): Branch name
• path (required): File path

Response 200:

{
  "path": "src/main.py",
  "branch": "main",
  "content": "function hello() {\n  return 'world';\n}",
  "size": 42,
  "encoding": "utf-8",
  "language": "python",
  "is_binary": false
}

POST /projects/{project_id}/repositories/{repo_id}/files/content

Update file content (existing endpoint).

Request Body:

{
  "path": "src/main.py",
  "branch": "main",
  "content": "new content",
  "commit_message": "Update greeting",
  "author_name": "User Name",
  "author_email": "user@example.com"
}

Frontend Specification

Components

FileEditor

Main component managing view/edit modes.

Props:

interface FileEditorProps {
  projectId: string;
  repoId: string;
}

State:

interface FileEditorState {
  mode: 'view' | 'edit';
  content: string;
  originalContent: string;
  language: string;
  filePath: string | null;
  branch: string;
  loading: boolean;
  error: string | null;
  showCommitDialog: boolean;
  isBinary: boolean;
}

SyntaxHighlighter

Read-only syntax highlighted display.

Props:

interface SyntaxHighlighterProps {
  code: string;
  language: string;
  showLineNumbers?: boolean;
}

CodeEditor

Editable code with syntax highlighting.

Props:

interface CodeEditorProps {
  value: string;
  onChange: (value: string) => void;
  language: string;
  readOnly?: boolean;
}

CommitDialog

Commit flow dialog.

Props:

interface CommitDialogProps {
  isOpen: boolean;
  filePath: string;
  originalContent: string;
  newContent: string;
  onCommit: (message: string) => Promise<void>;
  onCancel: () => void;
}

Language Support

Supported languages (from Prism.js):

• JavaScript/TypeScript (js, ts, jsx, tsx)
• Python (py)
• HTML/XML (html, xml)
• CSS/SCSS (css, scss)
• JSON (json)
• Markdown (md)
• YAML (yaml, yml)
• Shell/Bash (sh, bash)
• Docker (dockerfile)
• SQL (sql)
• And 280+ more via Prism.js

Keyboard Shortcuts

• Ctrl/Cmd + E: Toggle edit mode
• Ctrl/Cmd + S: Save (shows commit dialog)
• Escape: Cancel edit mode
• Tab: Insert 2 spaces

URL State

Editor state synced to URL:

/projects/:projectId?repo=:repoId&branch=:branch&file=:path&edit=true

Error Codes

Error Code	Description	User Message
BINARY_FILE	File is binary	"Binary files cannot be edited"
FILE_TOO_LARGE	File > 1MB	"File too large to edit"
LOAD_ERROR	Failed to load	"Failed to load file"
SAVE_ERROR	Failed to save	"Failed to save changes"
EMPTY_COMMIT	No changes	"No changes to commit"

Testing Strategy

Unit Tests

• Language detection
• Syntax highlighting output
• Diff generation
• Commit validation

Integration Tests

• File loading
• Mode switching
• Commit flow
• Error handling

Manual Tests

• Various file types
• Large files
• Binary files
• Network failures