tsview/readme.md

# @git.zone/tsview

A powerful developer tool for browsing and managing S3-compatible storage and MongoDB databases through a sleek web UI. Built with TypeScript, designed for developers who need quick, visual access to their data stores during development. 🚀

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
# Global installation (recommended for CLI usage)
npm install -g @git.zone/tsview
# or
pnpm add -g @git.zone/tsview

# Local installation (for programmatic usage)
npm install @git.zone/tsview
# or
pnpm add @git.zone/tsview
```

## Features ✨

### 🗄️ S3 Storage Browser
- **Column View Navigation** - Mac Finder-style interface with resizable columns for intuitive file browsing
- **List View** - Traditional key-based view with hierarchical navigation
- **Real-time Preview** - View images, JSON, text files, and more directly in the browser
- **Bucket Management** - Create, delete, and switch between buckets
- **File Operations** - Upload, download, delete objects with ease
- **Smart Content Type Detection** - Automatic content type recognition for 20+ file types
- **Breadcrumb Navigation** - Easy path traversal with clickable breadcrumbs

### 🍃 MongoDB Browser
- **Database Explorer** - Hierarchical navigation through databases and collections
- **Document Viewer** - Paginated table view with sorting and filtering
- **Document Editor** - Full CRUD operations with JSON syntax highlighting
- **Index Management** - View, create, and drop indexes
- **Aggregation Pipeline** - Run custom aggregation queries (coming soon)
- **Collection Stats** - View document counts, sizes, and storage metrics
- **Server Status** - Monitor connection info and server health

### 🎨 Modern Web UI
- 🌙 Dark theme designed for developer comfort
- 📱 Responsive layout with resizable panels
- ⌨️ Keyboard-friendly navigation
- 🔌 Zero external runtime dependencies in the browser

## Quick Start 🚀

### 1. Configure Your Connection

Create a `.nogit/env.json` file in your project root:

```json
{
  "S3_ENDPOINT": "localhost",
  "S3_PORT": "9000",
  "S3_ACCESSKEY": "minioadmin",
  "S3_SECRETKEY": "minioadmin",
  "S3_USESSL": false,
  "MONGODB_URL": "mongodb://localhost:27017",
  "MONGODB_NAME": "mydb"
}
```

### 2. Launch the Viewer

```bash
tsview
```

That's it! 🎉 Your browser will automatically open to the viewer interface.

## CLI Usage

```bash
# Start viewer with auto-detected port (starts from 3010)
tsview

# Force a specific port
tsview --port 3000

# S3 browser only
tsview s3

# MongoDB browser only
tsview mongo
# or
tsview mongodb
```

## Configuration via npmextra.json

For project-level configuration, add a `@git.zone/tsview` section to your `npmextra.json`:

```json
{
  "@git.zone/tsview": {
    "port": 3015,
    "killIfBusy": true,
    "openBrowser": false
  }
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | `number` | auto | Fixed port to use (auto-finds from 3010 if not set) |
| `killIfBusy` | `boolean` | `false` | Kill existing process if port is busy |
| `openBrowser` | `boolean` | `true` | Automatically open browser on start |

**Priority order:** CLI `--port` flag > `npmextra.json` config > auto-detect

## Programmatic API

Use tsview as a library in your own tools:

```typescript
import { TsView } from '@git.zone/tsview';

const viewer = new TsView();

// Option 1: Load from .nogit/env.json (gitzone service format)
await viewer.loadConfigFromEnv();

// Option 2: Configure programmatically for local development
viewer.setS3Config({
  endpoint: 'localhost',
  port: 9000,
  accessKey: 'minioadmin',
  accessSecret: 'minioadmin',
  useSsl: false
});

viewer.setMongoConfig({
  mongoDbUrl: 'mongodb://localhost:27017',
  mongoDbName: 'mydb'
});

// Option 3: Configure for cloud services
viewer.setS3Config({
  endpoint: 's3.amazonaws.com',
  accessKey: 'AKIAXXXXXXX',
  accessSecret: 'your-secret-key',
  useSsl: true,
  region: 'us-east-1'
});

viewer.setMongoConfig({
  mongoDbUrl: 'mongodb+srv://user:pass@cluster.mongodb.net',
  mongoDbName: 'production'
});

// Start the server
const port = await viewer.start();
console.log(`Viewer running on http://localhost:${port}`);

// Or specify a port
await viewer.start(3500);

// Graceful shutdown
await viewer.stop();
```

## Environment Variables

The following environment variables are supported in `.nogit/env.json`:

### S3 Configuration
| Variable | Description |
|----------|-------------|
| `S3_ENDPOINT` | S3 server hostname |
| `S3_PORT` | S3 server port (optional) |
| `S3_ACCESSKEY` | Access key ID |
| `S3_SECRETKEY` | Secret access key |
| `S3_USESSL` | Use HTTPS (`true`/`false`) |

### MongoDB Configuration
| Variable | Description |
|----------|-------------|
| `MONGODB_URL` | Full MongoDB connection string |
| `MONGODB_NAME` | Default database name |

Or use individual MongoDB variables:
| Variable | Description |
|----------|-------------|
| `MONGODB_HOST` | MongoDB hostname |
| `MONGODB_PORT` | MongoDB port |
| `MONGODB_USER` | Username |
| `MONGODB_PASS` | Password |
| `MONGODB_NAME` | Database name |

## Supported S3 Providers

tsview works with any S3-compatible storage:

| Provider | Status |
|----------|--------|
| **MinIO** | ✅ Perfect for local development |
| **AWS S3** | ✅ Amazon's object storage |
| **DigitalOcean Spaces** | ✅ Simple object storage |
| **Backblaze B2** | ✅ S3-compatible API |
| **Cloudflare R2** | ✅ Zero egress fees |
| **Wasabi** | ✅ Hot cloud storage |
| **Self-hosted** | ✅ Any S3-compatible server |

## Supported File Types for Preview

| Category | Extensions |
|----------|------------|
| **Images** | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg` |
| **Text** | `.txt`, `.md`, `.log`, `.sh`, `.env` |
| **Code** | `.json`, `.js`, `.ts`, `.tsx`, `.jsx`, `.html`, `.css` |
| **Data** | `.csv`, `.xml`, `.yaml`, `.yml` |
| **Documents** | `.pdf` |

## Development

```bash
# Clone the repository
git clone https://code.foss.global/git.zone/tsview.git
cd tsview

# Install dependencies
pnpm install

# Build (bundles frontend + compiles TypeScript)
pnpm build

# Development mode with hot reload
pnpm run watch

# Run tests
pnpm test
```

## Architecture

```
tsview/
├── ts/                    # Backend TypeScript source
│   ├── api/               # TypedRequest API handlers
│   │   ├── handlers.s3.ts
│   │   └── handlers.mongodb.ts
│   ├── config/            # Configuration management
│   ├── server/            # Web server (TypedServer)
│   ├── interfaces/        # Shared TypeScript interfaces
│   └── tsview.classes.tsview.ts  # Main class
├── ts_web/                # Frontend TypeScript source
│   ├── elements/          # Web components (LitElement)
│   ├── services/          # API client service
│   ├── styles/            # Shared theme styles
│   └── utilities/         # Helper functions
└── cli.ts.js              # CLI entry point
```

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.