# Project pack: ConvertX @ 2135c6b

Facts about **ConvertX** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> ConvertX is a small self-hosted file converter. You upload a file, choose the output format, and it uses well-known tools such as FFmpeg, ImageMagick and Pandoc behind the scenes. It handles over a thousand formats and keeps a history of conversions on your own server.

## Version and source
- Repository: https://github.com/C4illin/ConvertX
- Pinned commit: `2135c6b9f1bed5c4fdf9d2b1cfb7cdf54e9e2bad`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/C4illin/ConvertX/archive/2135c6b9f1bed5c4fdf9d2b1cfb7cdf54e9e2bad.zip
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/C4illin/ConvertX bespoke-convertx
  cd bespoke-convertx
  git checkout --detach 2135c6b9f1bed5c4fdf9d2b1cfb7cdf54e9e2bad
  # Prepare development requirements and local configuration first.
  bun install
  bun run dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name convertx -p 3000:3000 -e JWT_SECRET=replace-with-a-long-random-string -e HTTP_ALLOWED=true -v convertx-data:/app/data ghcr.io/c4illin/convertx
  # then open http://localhost:3000 and create the first account
  ```

- Needs: Docker for a trial, Bun for development
- Develop: `bun run dev`
- Test: `bun test`
- Check/lint: `bun run lint`
- Stack: typescript (Bun, Elysia, HTMX, Tailwind). Difficulty for a non-developer with an AI: **easy**. A compact Bun app that wraps command-line converters. Adding a converter means a small TypeScript module that builds a command and lists the formats it supports.

## Customisation points (settings → extend → code)
- **accounts-and-cleanup** [settings]: Who can sign up and when old files vanish. → `Environment variables ACCOUNT_REGISTRATION, AUTO_DELETE_EVERY_N_HOURS`
- **formats** [settings]: Which output formats you offer. → `The converter list shown on the home page`
- **new-converter** [code]: Wrap another command-line tool. → `src/converters/`
- **pages** [code]: Screens and wording. → `src/pages/ and src/components/`

## Must keep working
- Safe command building. Never pass user input to a shell.
- Account and registration checks.
- Cleanup of old files.

## Staying updatable
Add converters in new files under src/converters and register them. Avoid changing existing converters.

## Data, costs and safety
- Personal data: **yes**. Stored in: A SQLite database and uploaded and converted files in /app/data. Converted files stay on the server until deleted. Set automatic deletion for private files.
- Setting `JWT_SECRET` (**secret**: the person enters it themselves, never in chat): Long secret used to sign logins. Never paste it into an AI chat.
- Setting `ACCOUNT_REGISTRATION`: Set to true only while you are creating accounts.
- Setting `HTTP_ALLOWED`: Set to true if you open it over plain http on your own network.
- Never expose it to the internet with ALLOW_UNAUTHENTICATED or open registration.
- Converters process untrusted files. Keep the container updated.

---

# Customising ConvertX

ConvertX is a small Bun app. Each converter is one TypeScript file that knows the command to run and the formats it supports.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Converters | src/converters/ |
| Pages and components | src/pages/ and src/components/ |
| Database setup | src/db/ |
| Helpers | src/helpers/ |
| Theme and styles | src/theme/ and public/ |
| Tests | tests/ |

## Use the gentlest change first

1. **Settings (no code):** environment variables for accounts and cleanup.
2. **Extend:** run it with extra tools installed in the image.
3. **Code:** new converters and wording.

## Recipes

- **New converter:** copy a small converter such as the one for images, change the command and list the formats, and register it in the main converter list.
- **Change cleanup time:** set `AUTO_DELETE_EVERY_N_HOURS` in the environment.

## Running and checking your changes

- `bun run dev` and convert a small file of each type you changed.
- `bun test` and `bun run lint`.

## Pitfalls

- Rebuild the Docker image if you add new system tools.
- Always pass arguments as arrays, never as a single shell string.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/convertx/2135c6b/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/convertx/2135c6b/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/convertx/2135c6b/r2/SKILL.md)