@paroicms/converter 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @paroicms/converter
+
+CLI tool to migrate field data from Quill format to Tiptap format in ParoiCMS main databases (SQLite).
+
+## Usage
+
+### Single Database Mode
+
+```bash
+npx @paroicms/converter \
+  --database /path/to/main.sqlite \
+  --quill-to-tiptap
+```
+
+This will:
+
+1. Run a dry-run pass to detect errors
+2. Run the actual conversion pass
+
+### Multisite Mode
+
+```bash
+npx @paroicms/converter \
+  --multisite-data-dir /path/to/data \
+  --quill-to-tiptap
+```
+
+This will process all databases matching the pattern `${dataDir}/*/main.sqlite`:
+
+1. Run a dry-run pass on all databases
+2. If all databases pass without errors, run the actual conversion on all databases
+3. If any database has errors in dry-run, abort the entire process
+
+## CLI Options
+
+- `--database <path>` (required*): Path to the SQLite database file
+- `--multisite-data-dir <path>` (required*): Path to the multisite data directory
+- `--quill-to-tiptap` (required): Activate Quill to Tiptap conversion
+- `--dry-run` (optional): Run in dry-run mode only (no database changes)
+- `--backup` (optional): Create a backup before conversion
+- `--force` (optional): Skip dry-run pass and convert immediately
+
+*You must specify either `--database` or `--multisite-data-dir`, but not both.
+
+## Exit Codes
+
+- `0`: All rows converted successfully
+- `1`: One or more rows failed to convert (errors will be logged)
+
+## Error Handling
+
+The tool will:
+
+- Skip failed rows and continue with others
+- Log all errors with field name, nodeId, and language
+- Return exit code 1 if any errors occurred
+- In multisite mode: abort if any database has errors during dry-run pass

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import type { CliOptions } from "./types.js";
+export declare function parseCliArguments(args: string[]): CliOptions;

package/dist/cli.js

@@ -0,0 +1,74 @@
+export function parseCliArguments(args) {
+    let database;
+    let multisiteDataDir;
+    let quillToTiptap = false;
+    let dryRun = false;
+    let backup = false;
+    let force = false;
+    for (let i = 0; i < args.length; ++i) {
+        const arg = args[i];
+        if (arg === "--database") {
+            ++i;
+            if (i >= args.length) {
+                throw new Error("Missing value for --database option");
+            }
+            database = args[i];
+        }
+        else if (arg === "--multisite-data-dir") {
+            ++i;
+            if (i >= args.length) {
+                throw new Error("Missing value for --multisite-data-dir option");
+            }
+            multisiteDataDir = args[i];
+        }
+        else if (arg === "--quill-to-tiptap") {
+            quillToTiptap = true;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--backup") {
+            backup = true;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (!arg.startsWith("--")) {
+        }
+        else {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    if (!database && !multisiteDataDir) {
+        throw new Error("Missing required option: --database or --multisite-data-dir");
+    }
+    if (database && multisiteDataDir) {
+        throw new Error("Cannot use both --database and --multisite-data-dir options");
+    }
+    if (!quillToTiptap) {
+        throw new Error("Missing required flag: --quill-to-tiptap");
+    }
+    if (database) {
+        const options = {
+            kind: "singleDatabase",
+            database,
+            quillToTiptap,
+            dryRun,
+            backup,
+            force,
+        };
+        return options;
+    }
+    if (multisiteDataDir) {
+        const options = {
+            kind: "multisite",
+            multisiteDataDir,
+            quillToTiptap,
+            dryRun,
+            backup,
+            force,
+        };
+        return options;
+    }
+    throw new Error("Invalid CLI options");
+}

package/dist/converter.d.ts

@@ -0,0 +1,6 @@
+import type { Knex } from "knex";
+import type { ConversionResult, FieldRow } from "./types.js";
+export declare function createBackup(dbPath: string): Promise<void>;
+export declare function getFieldRows(cn: Knex): Promise<FieldRow[]>;
+export declare function updateRow(cn: Knex, row: FieldRow, tiptapJson: string): Promise<void>;
+export declare function processRows(cn: Knex, rows: FieldRow[], isDryRun: boolean): Promise<ConversionResult>;

package/dist/converter.js

@@ -0,0 +1,95 @@
+import { convertQuillDeltaToTiptap } from "@paroicms/quill-delta-to-tiptap-json";
+import { copyFile } from "node:fs/promises";
+export async function createBackup(dbPath) {
+    const backupPath = `${dbPath}.bak`;
+    await copyFile(dbPath, backupPath);
+    console.log(`Backup created: ${backupPath}`);
+}
+export async function getFieldRows(cn) {
+    const rows = await cn("PaFieldText")
+        .select("field", "nodeId", "language", "val")
+        .where("plugin", "@paroicms/quill-editor-plugin");
+    return rows;
+}
+function convertRow(row) {
+    try {
+        const quillDelta = JSON.parse(row.val);
+        const converterOptions = {
+            customConverters: {
+                inlineFormats: {
+                    size: (value) => ({ type: "textSize", attrs: { value } }),
+                    obfuscate: (value) => ({ type: "obfuscate", attrs: { asALink: value } }),
+                    "internal-link-plugin": (value) => ({
+                        type: "internalLinkPlugin",
+                        attrs: { documentId: value },
+                    }),
+                    underline: (value) => (value ? { type: "italic" } : undefined),
+                },
+                embeds: {
+                    media: (value) => {
+                        const attrs = { ...value };
+                        if (attrs.zoomable === undefined || attrs.zoomable === true) {
+                            attrs.zoomable = true;
+                        }
+                        if (attrs.zoomable === false) {
+                            delete attrs.zoomable;
+                        }
+                        return { type: "media", attrs };
+                    },
+                    "html-snippet": (value) => ({ type: "htmlSnippet", attrs: { html: value } }),
+                    "video-plugin": (value) => ({ type: "videoPlugin", attrs: { videoId: value } }),
+                },
+            },
+        };
+        const conversionResult = convertQuillDeltaToTiptap(quillDelta, converterOptions);
+        const tiptapJson = JSON.stringify(conversionResult.result);
+        return { success: true, tiptapJson };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return { success: false, error: errorMessage };
+    }
+}
+export async function updateRow(cn, row, tiptapJson) {
+    await cn("PaFieldText")
+        .update({
+        val: tiptapJson,
+        plugin: "@paroicms/tiptap-editor-plugin",
+    })
+        .where({
+        field: row.field,
+        nodeId: row.nodeId,
+        language: row.language,
+    });
+}
+export async function processRows(cn, rows, isDryRun) {
+    const result = {
+        totalRows: rows.length,
+        converted: 0,
+        errors: 0,
+        errorDetails: [],
+    };
+    for (let i = 0; i < rows.length; ++i) {
+        const row = rows[i];
+        if ((i + 1) % 50 === 0 || i + 1 === rows.length) {
+            console.log(`Progress: ${i + 1}/${rows.length}...`);
+        }
+        const conversionResult = convertRow(row);
+        if (conversionResult.success) {
+            ++result.converted;
+            if (!isDryRun && conversionResult.tiptapJson) {
+                await updateRow(cn, row, conversionResult.tiptapJson);
+            }
+        }
+        else {
+            ++result.errors;
+            result.errorDetails.push({
+                field: row.field,
+                nodeId: row.nodeId,
+                language: row.language,
+                error: conversionResult.error ?? "Unknown error",
+            });
+        }
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import knex from "knex";
+import { access } from "node:fs/promises";
+import { parseCliArguments } from "./cli.js";
+import { createBackup, getFieldRows, processRows } from "./converter.js";
+import { createMultisiteResult, discoverDatabases } from "./multisite.js";
+async function processSingleDatabase(dbPath, isDryRun, doBackup) {
+    if (doBackup && !isDryRun) {
+        await createBackup(dbPath);
+    }
+    const cn = knex({
+        client: "sqlite3",
+        connection: {
+            filename: dbPath,
+        },
+        useNullAsDefault: true,
+    });
+    try {
+        const rows = await getFieldRows(cn);
+        console.log(`Found ${rows.length} rows to process\n`);
+        if (rows.length === 0) {
+            return {
+                totalRows: 0,
+                converted: 0,
+                errors: 0,
+                errorDetails: [],
+            };
+        }
+        console.log(`Processing ${rows.length} rows...`);
+        return await processRows(cn, rows, isDryRun);
+    }
+    finally {
+        await cn.destroy();
+    }
+}
+async function runSingleDatabaseMode() {
+    const startTime = Date.now();
+    console.log("Field Converter: Quill to Tiptap");
+    const options = parseCliArguments(process.argv.slice(2));
+    if (options.kind !== "singleDatabase") {
+        throw new Error("Invalid options kind");
+    }
+    console.log(`Database: ${options.database}`);
+    let exitCode = 0;
+    if (!options.force) {
+        console.log("Mode: dry-run (first pass)");
+        const dryRunResult = await processSingleDatabase(options.database, true, false);
+        console.log(`Converted: ${dryRunResult.converted} | Errors: ${dryRunResult.errors}\n`);
+        if (dryRunResult.errors > 0) {
+            console.log("Errors:");
+            for (const errorDetail of dryRunResult.errorDetails) {
+                console.log(`- Row [field=${errorDetail.field}, nodeId=${errorDetail.nodeId}, language=${errorDetail.language}]: ${errorDetail.error}`);
+            }
+            console.log();
+            exitCode = 1;
+        }
+    }
+    console.log("Mode: conversion (second pass)");
+    const conversionResult = await processSingleDatabase(options.database, false, options.backup ?? false);
+    console.log(`Converted: ${conversionResult.converted} | Errors: ${conversionResult.errors}\n`);
+    if (conversionResult.errors > 0) {
+        console.log("Errors:");
+        for (const errorDetail of conversionResult.errorDetails) {
+            console.log(`- Row [field=${errorDetail.field}, nodeId=${errorDetail.nodeId}, language=${errorDetail.language}]: ${errorDetail.error}`);
+        }
+        console.log();
+        exitCode = 1;
+    }
+    const totalTimeInSeconds = ((Date.now() - startTime) / 1000).toFixed(1);
+    console.log(`Total time: ${totalTimeInSeconds}s\n`);
+    if (exitCode === 1) {
+        console.log("Exit code: 1 (errors occurred)");
+    }
+    else {
+        console.log("Exit code: 0");
+    }
+    process.exit(exitCode);
+}
+async function runMultisiteMode() {
+    const startTime = Date.now();
+    console.log("Field Converter: Quill to Tiptap (Multisite Mode)");
+    const options = parseCliArguments(process.argv.slice(2));
+    if (options.kind !== "multisite") {
+        throw new Error("Invalid options kind");
+    }
+    console.log(`Multisite data directory: ${options.multisiteDataDir}\n`);
+    const databases = await discoverDatabases(options.multisiteDataDir);
+    console.log(`Discovered ${databases.length} site(s)\n`);
+    if (databases.length === 0) {
+        console.log("No databases found. Exit code: 0");
+        process.exit(0);
+    }
+    // Filter databases that exist
+    const existingDatabases = [];
+    for (const db of databases) {
+        try {
+            await access(db.dbPath);
+            existingDatabases.push(db);
+        }
+        catch {
+            console.log(`⚠️  Skipping ${db.siteName} - main.sqlite not found`);
+        }
+    }
+    if (existingDatabases.length === 0) {
+        console.log("No databases found. Exit code: 0");
+        process.exit(0);
+    }
+    console.log(`Processing ${existingDatabases.length} database(s)\n`);
+    // First pass: dry-run on all databases (unless force mode)
+    if (!options.force) {
+        console.log("=".repeat(80));
+        console.log("DRY-RUN PASS - Checking all databases");
+        console.log("=".repeat(80) + "\n");
+        for (const db of existingDatabases) {
+            console.log(`\n--- ${db.siteName} ---`);
+            console.log(`Database: ${db.dbPath}`);
+            db.result = await processSingleDatabase(db.dbPath, true, false);
+            console.log(`Converted: ${db.result.converted} | Errors: ${db.result.errors}`);
+            if (db.result.errors > 0) {
+                console.log("Errors:");
+                for (const errorDetail of db.result.errorDetails) {
+                    console.log(`- Row [field=${errorDetail.field}, nodeId=${errorDetail.nodeId}, language=${errorDetail.language}]: ${errorDetail.error}`);
+                }
+            }
+        }
+        const multisiteResult = createMultisiteResult(existingDatabases);
+        const totalTimeInSeconds = ((Date.now() - startTime) / 1000).toFixed(1);
+        console.log(`\n${"=".repeat(80)}`);
+        console.log("DRY-RUN SUMMARY");
+        console.log("=".repeat(80));
+        console.log(`Total databases: ${multisiteResult.totalDatabases}`);
+        console.log(`Databases with errors: ${multisiteResult.databasesWithErrors}`);
+        console.log(`Successful databases: ${multisiteResult.successfulDatabases}`);
+        console.log(`Total time: ${totalTimeInSeconds}s\n`);
+        if (multisiteResult.databasesWithErrors > 0) {
+            console.log("❌ Errors detected in dry-run pass. Aborting conversion.");
+            console.log("Exit code: 1 (errors occurred)");
+            process.exit(1);
+        }
+        if (options.dryRun) {
+            console.log("✅ Dry-run completed successfully.");
+            console.log("Exit code: 0");
+            process.exit(0);
+        }
+        console.log("✅ Dry-run pass completed with no errors. Proceeding with conversion.\n");
+    }
+    // Second pass: actual conversion on all databases
+    console.log("=".repeat(80));
+    console.log("CONVERSION PASS - Converting all databases");
+    console.log("=".repeat(80) + "\n");
+    for (const db of existingDatabases) {
+        console.log(`\n--- ${db.siteName} ---`);
+        console.log(`Database: ${db.dbPath}`);
+        db.result = await processSingleDatabase(db.dbPath, false, options.backup ?? false);
+        console.log(`Converted: ${db.result.converted} | Errors: ${db.result.errors}`);
+        if (db.result.errors > 0) {
+            console.log("Errors:");
+            for (const errorDetail of db.result.errorDetails) {
+                console.log(`- Row [field=${errorDetail.field}, nodeId=${errorDetail.nodeId}, language=${errorDetail.language}]: ${errorDetail.error}`);
+            }
+        }
+    }
+    const multisiteResult = createMultisiteResult(existingDatabases);
+    const totalTimeInSeconds = ((Date.now() - startTime) / 1000).toFixed(1);
+    console.log("\n" + "=".repeat(80));
+    console.log("FINAL SUMMARY");
+    console.log("=".repeat(80));
+    console.log(`Total databases: ${multisiteResult.totalDatabases}`);
+    console.log(`Successful databases: ${multisiteResult.successfulDatabases}`);
+    console.log(`Databases with errors: ${multisiteResult.databasesWithErrors}`);
+    console.log(`Total time: ${totalTimeInSeconds}s\n`);
+    if (multisiteResult.databasesWithErrors > 0) {
+        console.log("Exit code: 1 (errors occurred)");
+        process.exit(1);
+    }
+    console.log("Exit code: 0");
+    process.exit(0);
+}
+async function main() {
+    try {
+        const options = parseCliArguments(process.argv.slice(2));
+        if (options.kind === "singleDatabase") {
+            await runSingleDatabaseMode();
+        }
+        else {
+            await runMultisiteMode();
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${errorMessage}`);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Unhandled error:", error);
+    process.exit(1);
+});

package/dist/multisite.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseResult, MultisiteConversionResult } from "./types.js";
+export declare function discoverDatabases(multisiteDataDir: string): Promise<DatabaseResult[]>;
+export declare function createMultisiteResult(databases: DatabaseResult[]): MultisiteConversionResult;

package/dist/multisite.js

@@ -0,0 +1,40 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+export async function discoverDatabases(multisiteDataDir) {
+    const entries = await readdir(multisiteDataDir, { withFileTypes: true });
+    const siteDirs = entries.filter((entry) => entry.isDirectory());
+    const databases = [];
+    for (const siteDir of siteDirs) {
+        const siteName = siteDir.name;
+        const dbPath = join(multisiteDataDir, siteName, "main.sqlite");
+        databases.push({
+            siteName,
+            dbPath,
+            result: {
+                totalRows: 0,
+                converted: 0,
+                errors: 0,
+                errorDetails: [],
+            },
+        });
+    }
+    return databases;
+}
+export function createMultisiteResult(databases) {
+    let successfulDatabases = 0;
+    let databasesWithErrors = 0;
+    for (const db of databases) {
+        if (db.result.errors === 0 && db.result.totalRows > 0) {
+            ++successfulDatabases;
+        }
+        else if (db.result.errors > 0) {
+            ++databasesWithErrors;
+        }
+    }
+    return {
+        totalDatabases: databases.length,
+        successfulDatabases,
+        databasesWithErrors,
+        databases,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export type CliOptions = SingleDatabaseCliOptions | MultisiteDatabaseCliOptions;
+export interface SingleDatabaseCliOptions {
+    kind: "singleDatabase";
+    database: string;
+    quillToTiptap: boolean;
+    dryRun?: boolean;
+    backup?: boolean;
+    force?: boolean;
+}
+export interface MultisiteDatabaseCliOptions {
+    kind: "multisite";
+    multisiteDataDir: string;
+    quillToTiptap: boolean;
+    dryRun?: boolean;
+    backup?: boolean;
+    force?: boolean;
+}
+export interface ConversionResult {
+    totalRows: number;
+    converted: number;
+    errors: number;
+    errorDetails: Array<{
+        field: string;
+        nodeId: number;
+        language: string;
+        error: string;
+    }>;
+}
+export interface FieldRow {
+    field: string;
+    nodeId: number;
+    language: string;
+    val: string;
+}
+export interface DatabaseResult {
+    siteName: string;
+    dbPath: string;
+    result: ConversionResult;
+}
+export interface MultisiteConversionResult {
+    totalDatabases: number;
+    successfulDatabases: number;
+    databasesWithErrors: number;
+    databases: DatabaseResult[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@paroicms/converter",
+  "version": "0.1.0",
+  "description": "CLI tool to migrate field data from Quill to Tiptap format",
+  "type": "module",
+  "bin": {
+    "paroicms-converter": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clear": "rimraf dist/*",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "postbuild": "chmod +x dist/index.js"
+  },
+  "dependencies": {
+    "knex": "~3.1.0",
+    "sqlite3": "~5.1.7",
+    "@paroicms/quill-delta-to-tiptap-json": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "~24.8.1",
+    "rimraf": "~6.0.1",
+    "typescript": "~5.9.3"
+  },
+  "files": [
+    "dist"
+  ]
+}