TOME Metadata Manager VSCode Extension

A VSCode extension for previewing and editing metadata of TOME archive files.

Features

📋 Preview Mode

Beautiful UI display of TOME metadata
Cover image thumbnail
Title, authors, and description
Type-specific fields (ISBN for books, narrators for audiobooks, volume info for comics)
File information and archive contents listing

✏️ Editor Mode

Direct JSON editing of tome.json
Real-time validation against TOME specification
Support for all TOME types (book, audio_book, comic_series, comic_volume, comic_chapter)
Type-specific field requirement enforcement
Save changes back to the TOME archive

🎯 Integration

Default preview on file open - Double-click a .tome file to open it in preview mode
Right-click context menu for .tome files
Command palette integration
Keyboard shortcuts support
Seamless file handling

Installation

From VS Code Marketplace (Coming Soon)

When published, install directly from VS Code:

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Search for "TOME Metadata Manager"
Click Install
Double-click any .tome file to use the extension

Development Installation

For development or testing:

Open the vscode-extension folder in VS Code
Install dependencies:
```
npm install
```
Compile the extension:
```
npm run compile
```
Run the extension in debug mode:
- Press F5 to start debugging
- A new VS Code window will open with the extension active

Development

Project Structure

src/
├── extension.ts              # Main extension entry point
├── webviewPanel.ts           # Webview panel management
├── utils/
│   └── tomeParser.ts         # TOME file parsing and validation
└── commands/
    ├── openPreview.ts        # Preview command handler
    └── editMetadata.ts       # Edit metadata command handler

Building

Compile: npm run compile
Watch mode: npm run watch
Lint: npm run lint

Testing the Extension

Double-click a TOME file (.tome) in VS Code to open it in preview mode (default)
Right-click and select "TOME: Open Preview" to view metadata
Right-click and select "TOME: Edit Metadata" to edit the JSON
Use the Preview or Edit Metadata buttons to switch between modes

TOME File Format

TOME files are ZIP archives with the following structure:

archive.tome
├── tome.json          # Metadata (required)
├── cover.jpg          # Cover image (optional)
├── content.html       # Main content file (type-dependent)
└── ...other files

Supported TOME Types

Type	Required Fields	Common Fields
book	`type`, `title`, `content`	`authors`, `cover_image`, `published_date`, `isbn`, `description`
audio_book	`type`, `title`	`authors`, `narrators`, `duration`, `cover_image`, `description`
comic_series	`type`, `volumes_file`	`title`, `authors`, `cover_image`, `description`
comic_volume	`type`, `chapters_file`	`title`, `comic_series`, `volume_number`, `cover_image`
comic_chapter	`type`, `title`, `chapter_number`	`comic_title`, `volume_number`, `cover_image`

Example tome.json

{
  "type": "book",
  "title": "The Great Adventure",
  "authors": ["Jane Smith"],
  "content": "book.html",
  "cover_image": "cover.jpg",
  "published_date": "2024-01-15",
  "language": "en",
  "isbn": "978-0-123456-78-9",
  "description": "An epic tale of adventure and discovery.",
  "tags": ["fantasy", "adventure"]
}

Commands

From Command Palette

TOME: Open Preview - Open metadata preview for the current TOME file
TOME: Edit Metadata - Open JSON editor for the current TOME file

Right-click on any .tome file to see:

Preview
Edit Metadata

Publishing

To publish this extension to the VS Code Marketplace:

Quick summary:

# One-time setup
npm install -g vsce
# Create publisher account at https://marketplace.visualstudio.com/manage
# Generate Personal Access Token at https://dev.azure.com/

# For each release
npm run compile
vsce package
vsce publish --pat YOUR_TOKEN

Features in Progress

Phase 2 (Planned)

Visual form-based metadata editor
Type selector with dynamic fields
Image picker for cover art
Date picker for publication dates
Narrators/authors multi-field editor

Phase 3 (Planned)

Advanced validation with detailed suggestions
Schema-based validation
File existence verification
Performance optimizations for large TOME files

Architecture

Extension Flow

Extension Activation
    ↓
Register Commands
    ↓
User Right-clicks .tome file
    ↓
Command Executed
    ↓
TomeParser reads archive
    ↓
WebviewPanel created
    ↓
HTML UI rendered (Preview or Editor)
    ↓
User interaction → Validation → Save/Close

Key Components

TomeParser (utils/tomeParser.ts)
- Parses ZIP archives
- Extracts and validates metadata
- Handles file updates
- Validates against TOME spec
WebviewPanelManager (webviewPanel.ts)
- Creates and manages webview panels
- Handles resource URIs
- Tracks panel lifecycle
Command Handlers (commands/)
- openPreview.ts - Displays metadata in a formatted UI
- editMetadata.ts - Provides JSON editor with validation

Dependencies

adm-zip - ZIP file reading/writing
ajv - JSON schema validation (ready for future use)
vscode - VS Code API
typescript - Type safety

License

MIT

Contributing

Contributions are welcome! Please follow the existing code style and structure.

Roadmap

[ ] Visual form-based metadata editor
[ ] Schema validation with detailed error messages
[ ] File reference validation
[ ] Support for nested metadata structures
[ ] Batch editing for multiple TOME files
[ ] Integration with TOME Studio for advanced editing
[ ] Template support for quick metadata creation

Support

For issues, questions, or feature requests, please create an issue in the repository.

TOME Metadata Manager

Keegan Bruer