diff --git a/AGENTS.md b/AGENTS.md index aafe4a0..143db4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,30 @@ This package converts Pro Cycling Manager CDB binary database files to and from - Low-level binary format handling lives in [src/reader.ts](src/reader.ts), [src/writer.ts](src/writer.ts), [src/types.ts](src/types.ts), and [src/tableMetadata.ts](src/tableMetadata.ts). - Compression helpers live in [src/compression.ts](src/compression.ts). +### Terminology + +Two words, deliberately not interchangeable (same meanings as in `pcm-mcp`): + +- **database** — a `.cdb` file. Cyanide's binary database format, and what this + library exists to read and write. It may be a player save, an official release + or a community update; nothing in the conversion path cares which. Here it is + always handled as a *buffer*, never a path: the public API takes `cdbBuffer` / + returns `Uint8Array`, and only the CLI in [src/cli.ts](src/cli.ts) touches the + filesystem. The format internals live in [src/reader.ts](src/reader.ts), + [src/writer.ts](src/writer.ts), [src/compression.ts](src/compression.ts) and + [src/tableMetadata.ts](src/tableMetadata.ts). +- **save** — a `.cdb` the *game itself wrote* as the player played, as opposed to + an official release or a community update. This repository has no notion of + save discovery, so the word belongs only where provenance is the actual point: + the reverse-engineering notes in [src/keyInference.ts](src/keyInference.ts) and + [src/tableMetadata.ts](src/tableMetadata.ts) ("observed in real saves"). Never + use it as a generic name for the input file. + +Because this repository is the one place both formats are live at once, the +SQLite side is *always* qualified: "SQLite database", the `.sqlite` file, or the +`sql.js` `Database` instance (aliased `SqlDatabase`). Bare "database" in prose +means the `.cdb`. + ## Commands - Install: `npm install` diff --git a/LICENSE b/LICENSE index 1af42c5..ddb588c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2025 Mathieu Picciolli +Copyright (c) 2025 PCMStack Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 94fb2ca..584af51 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # cdb-converter [![npm version](https://img.shields.io/npm/v/cdb-converter.svg)](https://www.npmjs.com/package/cdb-converter) -[![CI](https://github.com/mpicciolli/cdb-converter/actions/workflows/ci.yml/badge.svg)](https://github.com/mpicciolli/cdb-converter/actions/workflows/ci.yml) +[![CI](https://github.com/PCMStack/converter/actions/workflows/ci.yml/badge.svg)](https://github.com/PCMStack/converter/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/npm/l/cdb-converter.svg)](./LICENSE) [![Node.js](https://img.shields.io/node/v/cdb-converter.svg)](https://nodejs.org) Convert **Pro Cycling Manager CDB** database files to and from SQLite, straight from the command line or your own code. Lightweight, isomorphic (Node.js **and** the browser), and zero-configuration. -The conversion is **lossless**: a full `cdb → sqlite → cdb` round-trip preserves every table, column, data type, and flag — so you can edit a save in any SQLite tool and load it back into the game. Optionally, it can reconstruct the save's relationships as real `PRIMARY KEY` / `FOREIGN KEY` constraints, turning the export into a normalized database you can explore with JOINs and ER-diagram tools. +The conversion is **lossless**: a full `cdb → sqlite → cdb` round-trip preserves every table, column, data type, and flag — so you can edit a database in any SQLite tool and load it back into the game. Optionally, it can reconstruct the database relationships as real `PRIMARY KEY` / `FOREIGN KEY` constraints, turning the export into a normalized database you can explore with JOINs and ER-diagram tools. > [!NOTE] > Based on [agfor/pcmdbedit](https://github.com/agfor/pcmdbedit/) — many thanks to agfor for the foundational work. @@ -53,7 +53,7 @@ npm install cdb-converter The fastest way to try it is the CLI: ```bash -npx cdb-converter save.cdb +npx cdb-converter database.cdb ``` ## Command line @@ -61,17 +61,17 @@ npx cdb-converter save.cdb The package ships a `cdb-converter` command. The conversion direction is auto-detected from the input file extension. ```bash -# CDB → SQLite (default output: save.sqlite) -npx cdb-converter save.cdb +# CDB → SQLite (default output: database.sqlite) +npx cdb-converter database.cdb -# SQLite → CDB (default output: save.cdb) -npx cdb-converter save.sqlite +# SQLite → CDB (default output: database.cdb) +npx cdb-converter database.sqlite # Provide an explicit output path (directories are created as needed) -npx cdb-converter save.cdb data/save.sqlite +npx cdb-converter database.cdb data/database.sqlite # Reconstruct PRIMARY KEY / FOREIGN KEY constraints (CDB → SQLite only) -npx cdb-converter save.cdb save.sqlite --normalize +npx cdb-converter database.cdb database.sqlite --normalize # Help / version npx cdb-converter --help @@ -83,10 +83,10 @@ npx cdb-converter --version | `.cdb` | CDB → SQLite | `.sqlite` | | `.sqlite` / `.db` | SQLite → CDB | `.cdb` | -| Option | Effect | -| ------------------- | -------------------------------------------------------------------------------------------------- | +| Option | Effect | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `-n`, `--normalize` | (CDB → SQLite only) reconstruct PK/FK constraints from PCM naming conventions. See [Normalized schema](#normalized-schema). | -| `--index-fk` | Implies `--normalize`; also indexes every FK column for faster JOINs (roughly doubles output size). | +| `--index-fk` | Implies `--normalize`; also indexes every FK column for faster JOINs (roughly doubles output size). | ## Library usage @@ -100,7 +100,7 @@ import { cdbToSql } from "cdb-converter"; const SQL = await initSqlJs(); // Read and convert a CDB file -const cdbBuffer = fs.readFileSync("save.cdb"); +const cdbBuffer = fs.readFileSync("database.cdb"); const db = cdbToSql(cdbBuffer, SQL); // Query it like any SQLite database @@ -108,7 +108,7 @@ const result = db.exec("SELECT * FROM Teams LIMIT 5"); console.log(result[0].values); // Export to a .sqlite file -fs.writeFileSync("save.sqlite", db.export()); +fs.writeFileSync("database.sqlite", db.export()); ``` > [!IMPORTANT] @@ -154,11 +154,11 @@ import { sqlToCdb } from "cdb-converter"; const SQL = await initSqlJs(); // Load a SQLite database and convert back to CDB -const sqliteBuffer = fs.readFileSync("save.sqlite"); +const sqliteBuffer = fs.readFileSync("database.sqlite"); const db = new SQL.Database(sqliteBuffer); const cdbBuffer = sqlToCdb(db); // automatically compressed -fs.writeFileSync("save.cdb", Buffer.from(cdbBuffer)); +fs.writeFileSync("database.cdb", Buffer.from(cdbBuffer)); ``` ### Compression @@ -269,11 +269,11 @@ A full `cdb → sqlite → cdb` round-trip on a real ~60k-row database stays wel Normalization is opt-in and costs only what you ask for (measured against the default conversion, ~60k rows): -| Mode | Conversion time | Output size | -| --------------------------------------------- | --------------- | ----------- | -| Default (flat) | baseline | baseline | -| `normalize` | +~10% | +~40% | -| `normalize` + `indexForeignKeys` | +~40% | +~130% | +| Mode | Conversion time | Output size | +| -------------------------------- | --------------- | ----------- | +| Default (flat) | baseline | baseline | +| `normalize` | +~10% | +~40% | +| `normalize` + `indexForeignKeys` | +~40% | +~130% | See **[bench/README.md](bench/README.md)** for the full per-fixture numbers, the bundle breakdown, and how to reproduce them (`npm run bench`). diff --git a/package.json b/package.json index ac7409b..8d38a5b 100644 --- a/package.json +++ b/package.json @@ -3,11 +3,15 @@ "version": "0.3.0", "description": "Convert Pro Cycling Manager CDB files to/from SQLite and other formats. TypeScript library with zero configuration.", "license": "MIT", - "author": "mpicciolli", + "author": "PCMStack", "repository": { "type": "git", - "url": "https://github.com/mpicciolli/cdb-converter" + "url": "https://github.com/PCMStack/converter" }, + "bugs": { + "url": "https://github.com/PCMStack/converter/issues" + }, + "homepage": "https://github.com/PCMStack/converter#readme", "keywords": [ "cdb", "database", diff --git a/samples/browser/index.html b/samples/browser/index.html index aa679a0..0e8fd38 100644 --- a/samples/browser/index.html +++ b/samples/browser/index.html @@ -3,7 +3,7 @@ - cdb-converter + cdb-converter: PCMStack
+

PCMStack

cdb-converter

-

Convert Pro Cycling Manager save files to SQLite in one line.

+

Convert any Pro Cycling Manager database to SQLite in one line.

MIT ESM + CJS @@ -32,6 +33,10 @@

cdb-converter

Try it

+

+ Everything runs in your browser. Your database is never uploaded: it is + read, converted and downloaded entirely on this machine. +