Files
jsonPrism/docs/ROADMAP.md
T
poli0981andClaude Opus 5.5 14f593c7a7 chore: 2.1.1 — dependencies to their latest releases (#170)
npm (minor/patch only): react-router 8.5.1, i18next 26.7.1,
react-i18next 17.1.12, i18next-browser-languagedetector 8.3.0,
lucide-react 1.67.0, fast-xml-parser 5.12.0, cbor-x 1.6.9,
@tauri-apps/plugin-dialog 2.8.4; dev: eslint 10.14, typescript-eslint
8.72.1, globals 17.14, vitest + coverage-v8 5.1, plugin-react 6.2.1,
tailwindcss + @tailwindcss/vite 4.3.4, knip 6.44.1, wrangler 4.157,
@types/node 26.6.6. Transitive packages refreshed; Vite and Tailwind
now share one lightningcss.

Cargo: cargo update within semver (tauri-plugin-dialog 2.8.4,
tauri-plugin-single-instance 2.5.5, wry 0.57.1, tao 0.37.2, ...).

Actions: sonarqube-scan-action 8.4.1; everything else was current.

knip 6.44 sees @testing-library/user-event, so it leaves
ignoreDependencies. THIRD-PARTY.md re-synced with the lockfiles.

minimatch < 11.0.1 (GHSA-g3hv-75wg-m249) stays: eslint and
typescript-eslint pin minimatch 10, the vulnerable path needs
optimizationLevel >= 2 and both use the default 1 on our own
config patterns.

Supersedes #163, #164, #165, #166, #167, #168, #169.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 09:53:47 +07:00

23 KiB
Raw Blame History

JSONPrism Roadmap

This document is the single source of truth for what's done, what's next, and why.

Update it as work lands — keep the project status honest.

Current release: v2.1.1 (2026-11-04). The web app runs at https://jsonprism.poli0981.dev (Cloudflare Workers); desktop and Android builds are on GitHub Releases.


Phase 0 — Scaffold ✅

Status: complete (2026-05-12) Duration: ~1 day

Foundation: build tooling, app shell, converter framework, four working converters, full docs.

What landed:

  • Vite 6 + React 19 + TypeScript 5.7 strict
  • Tailwind v4 + shadcn-ready theme tokens
  • Routing, theming, i18n (EN + VI), error boundary
  • Converter interface + registry + shape detection
  • Working: JSONL, CSV, TSV, YAML
  • Stubs with detailed plans: XML, TOML, Markdown, SQL, RESX
  • CI + GH Pages deploy workflows
  • Full documentation suite

Phase 1 — Polish & Foundations ✅

Status: complete (2026-05-12) Actual: ~1 day

Goal: make the four working converters production-quality and the UX delightful enough to share publicly.

Tasks

1.1 Editor upgrade

  • Replace <textarea> input with CodeMirror 6 + @codemirror/lang-json
  • Line numbers + active-line highlight
  • Folding for nested structures
  • Theme: custom Prism Spectrum tokens applied to lezer highlight tags
  • Parse-error linting (visible gutter markers)
  • Output panel uses CodeMirror in read-only mode with format-specific syntax — deferred at the time; landed in 2.0.0 (Phase 8)

1.2 Settings panel

  • Side sheet (Radix Dialog) that opens per-converter options
  • Form widgets auto-generated from optionSchema: Switch, segmented enum, number input, text input
  • Settings persist to localStorage per format
  • "Reset to defaults" button with toast confirmation

1.3 Per-format options exposed in UI

  • JSONL: pretty toggle
  • CSV/TSV: header toggle, newline (LF/CRLF), nested strategy (json/flatten)
  • YAML: indent (2–8), quote style

1.4 File handling

  • Drag-drop a single .json file onto the input panel
  • "Open file…" button via hidden file input
  • Drop overlay with Prism Spectrum styling
  • Auto-detect file encoding — non-issue; FileReader uses UTF-8 by default and modern editors don't emit BOM

1.5 Notifications

  • Sonner toast for: copy success/failure, download started, file loaded/failed, options reset
  • Dismissible, bottom-right, dark/light aware via ThemeProvider integration

1.6 Testing

  • Vitest + @testing-library/react + jsdom configured
  • Unit tests for all Phase 1 converters (happy path + edge cases): 35+ tests
  • Tests for parseJsonInput, detectShape, options-storage
  • CI runs tests between typecheck and build

1.7 Polish

  • Keyboard shortcuts: ⌘/Ctrl+K (clear), ⌘/Ctrl+S (download) — ⌘/Ctrl+K removed in 2.0.0: it clashed with the browser's search shortcut
  • Status bar showing: input bytes, output bytes, parse time, shortcut hints
  • Shape detection hint (scalar / object / array / flat-object / array-of-objects)
  • Disabled-format chips show "P2"/"P3" badge with tooltip
  • Cmd/Ctrl+, to open settings — deferred at the time; added in a later 1.x release

Deliverable

A polished, single-file converter UX with four production-grade converters. Ready to demo publicly and share in the Discord open-source server. 35+ unit tests passing.


Phase 2 — Four more formats + batch + Tauri

Split into three sub-phases for digestibility.

Phase 2A — Four new converters ✅

Status: complete (2026-05-12) Actual: ~1 day

XML converter

  • fast-xml-parser XMLBuilder integration
  • Configurable root element name, item name, declaration, indent
  • Attribute convention: keys starting with @_ become attributes
  • Array handling: each item wrapped with itemName element when array is root
  • XML declaration prepended conditionally
  • 8 unit tests including round-trip via XMLParser

TOML converter

  • smol-toml stringify integration
  • Rejects non-object roots (array, scalar, null) with clear error
  • sortKeys option, recursive
  • Nested tables emitted naturally via smol-toml
  • 7 unit tests including round-trip via parse

Markdown table converter

  • Hand-rolled, zero deps
  • Header row from union of all object keys (preserve insertion order)
  • Alignment markers per column (left/center/right/none)
  • Pipe escaping in cell values
  • Newlines → <br> per GFM
  • Nested values JSON-stringified
  • 11 unit tests

SQL INSERT converter

  • Hand-rolled, zero deps
  • Dialect support: standard / postgres / mysql / sqlite / mssql
  • Identifier quoting per dialect (double-quote / backtick / bracket) with proper escaping
  • Value escaping per dialect (booleans differ across all 5)
  • Multi-row INSERT with configurable chunk size
  • Optional CREATE TABLE inference from first row's types
  • Missing keys across rows → NULL
  • 19 unit tests (helpers + integration; 5 dialects × value types)

Phase 2B — Batch processing ✅

Status: complete (2026-05-12) Actual: ~1 day

  • Drag-drop multiple files onto a dropzone (react-dropzone)
  • Batch queue panel showing: filename, size, status (queued/processing/done/error), output size
  • Hard limit: 500 files (BATCH_MAX_FILES)
  • Process in chunks to keep UI responsive (requestIdleCallback with setTimeout(0) fallback)
  • "Download all (.zip)" via fflate (chosen over JSZip for ~12× smaller bundle)
  • Per-file error display without blocking the rest of the queue
  • AbortController-based cancellation
  • Smart drop routing: 1 file → editor, 2+ files → batch panel auto-opens
  • Zustand store with item map + display order for O(1) per-item updates
  • Filename collision handling in the zip
  • 20+ unit tests including round-trip zip decode

Phase 2C — Tauri 2 desktop wrapper ✅

Status: complete (2026-05-12) Actual: ~1 day

  • src-tauri/ scaffold with Tauri 2.x (Cargo.toml, tauri.conf.json, lib.rs)
  • Tauri serves Vite-built dist/; dev mode runs Vite + Tauri window with HMR
  • Native file open/save dialogs via plugin-dialog + plugin-fs
  • OS drag-drop integration via tauri://drag-drop events (hook: useTauriDragDrop)
  • App icons: SVG source committed (src-tauri/icons/icon.svg), generated formats via npm run tauri:icon
  • Bundle targets: Windows (MSI + NSIS .exe), macOS (DMG + .app, min 12.0), Linux (AppImage + deb)
  • CSP and capability file locked down (scoped to user dirs only)
  • Custom Rust command host_info for diagnostics
  • GitHub Actions release workflow (matrix: Windows / macOS ARM / macOS Intel / Linux); draft release on v* tag
  • Vite config detects Tauri context and adjusts base path + dev server
  • Frontend isTauri() runtime gate keeps web bundle free of Tauri imports (tree-shaken)
  • Velopack skipped — using Tauri's native bundler (avoids the two-tool overhead PhantomMAC has)

Deliverable (full Phase 2)

8/9 formats production-ready. Batch up to 500 files. Desktop builds for Windows / macOS / Linux. JSONPrism becomes a "real" tool, not just a website.

Currently at Phase 2A — only RESX (Phase 3) remains as a stub.


Phase 3 — RESX & i18n integration ✅

Status: complete (2026-05-12) Actual: ~1 day

Goal: ship the .NET RESX converter and integrate with existing AutoClickForge / PhantomMAC localization workflows.

Tasks

3.1 RESX converter

  • Hand-rolled XML output (skip fast-xml-parser; the template is too rigid)
  • Standard RESX 2.0 header with xsd:schema + 4 resheader elements (resmimetype, version, reader, writer)
  • Input contract: flat object { "Key": "value" }; nested objects → reject with helpful error
  • Optional _comment key (configurable via commentKey option) → emits <comment> element on the <data>
  • XML escaping for text content (&, <, >) and attribute context (quotes)
  • Number and boolean coercion to string
  • Null/undefined coerced to empty string
  • sortKeys option for stable diffs across locale files
  • includeSchema option (Visual Studio expects schema; tests verify byte-exact match)
  • 17 unit tests covering schema, comment shape, escaping, sort order, error paths

3.2 Smart UI for the RESX use case

  • Format picker highlights suggested formats based on detectShape output via subtle ring
  • Flat-object detection surfaces RESX first in the suggestion list
  • Batch processor preserves locale segment in filenames: strings.vi.json → strings.vi.resx

3.3 Documentation

  • docs/RESX-MIGRATION.md — tutorial: i18next JSON → .NET RESX, with flatten script, batch flow, Visual Studio verification, comment support, CI sketch
  • Cross-link with PhantomMAC / AutoClickForge i18n docs in the worked example

Deliverable

9/9 formats production-ready. RESX integration documented as a real migration path between i18next-based web projects and .NET WPF projects. JSONPrism reaches 1.0.


Phase 4 — Binary formats & reverse conversion ✅

Status: complete (shipped in v1.1.0)

Post-1.0 expansion: three binary target formats and bidirectional conversion.

  • BSON / CBOR / MessagePack converters — output rendered as base64 (default) or hex; downloads decode back to raw bytes. New ConverterMeta.binary flag.
  • Reverse conversion — optional Converter<T>.reverse() interface method; JSONL, CSV/TSV, YAML, TOML, RESX → JSON. New DirectionToggle component, direction persisted to localStorage.
  • Reverse batch processing — drop non-JSON files, get a .zip of .json outputs back.

12/12 formats production-ready.


Phase 5 — Maintenance & refactor ✅

Status: complete (shipped in v1.5.0)

Codebase hygiene plus a small UX addition — no converter behavior changed.

  • Decomposed three oversized components (BatchPanel, ConverterWorkspace, InputPanel) into focused pure utilities, leaf components, and hooks — behavior-preserving, all 193 tests still green.
  • Integrated knip for dead-code analysis: knip.json config, npm run knip script, and a CI step. Initial sweep removed orphaned code and a phantom dependency.
  • Scroll-to-top button on the long, scrollbar-hidden About page (respects prefers-reduced-motion).

Status: complete (shipped in v1.6.0)

Compliance + reliability + first-paint performance. No converter behavior changed.

  • Custom error pages: reusable ErrorState, 404 catch-all, generic /error/:code (403/419/5xx variants), offline banner, and a chunk-load error boundary folded into the existing crash boundary's look.
  • GitHub Pages SPA deep-link fix (public/404.html + index.html decoder for the /jsonPrism/ base). Removed in 2.0.0: the web app moved to Cloudflare Workers, which has an SPA fallback.
  • First-launch legal consent gate (web only) — accept License/Terms/Privacy/Disclaimer, persisted to localStorage with a version for re-prompting; skipped on desktop.
  • Windows installer license-acceptance page via Tauri bundle.licenseFile (src-tauri/license.rtf), covering both NSIS .exe and WiX .msi.
  • Lazy-load routes + the CodeMirror editor; refined manualChunks (react/router/i18n/cm-core/cm-langs/per-parser/ui); removed the bson initial-graph leak via lib/bytes.ts. +16 tests (209 total).

Phase 7 — Android (sideload APK) 🔜

Status: in progress — the APK has shipped with every release since v1.7.0 (2026-06-16); only the real-device checks below remain.

Goal: ship JSONPrism as an Android app users sideload from a .apk. Same React UI, no behavior change to the converters. Minimum Android 12 (API 31) — older devices are blocked by the OS.

Tasks

  • bundle.android in tauri.conf.json: minSdkVersion: 31, deterministic versionCode (MAJOR*10000+MINOR*100+PATCH)
  • tauri android init → Android Gradle project at src-tauri/gen/android/, committed (source only; build outputs + secrets gitignored via nested + root .gitignore)
  • Verified minSdk = 31 propagated to app/build.gradle.kts; Rust compiles for all 4 ABIs (validated against NDK r27/r30)
  • Release signing wired in app/build.gradle.kts from a gitignored keystore.properties (graceful unsigned fallback when absent)
  • Self-hosted fonts via @fontsource (Geist / Instrument Serif / JetBrains Mono) — removed Google Fonts <link>, tightened CSP, app renders correctly offline (Instrument Serif dropped in 2.0.0: it has no Vietnamese glyphs)
  • Local scripts: tauri:android:init / tauri:android:dev / tauri:android:build (universal APK; chains tauri:icon)
  • CI: android job in release.yml builds + signs (keystore from secrets) + uploads the universal APK to the same draft release
  • Docs: README / README.vi "Android" sections + maintainer notes in docs/TAURI-NOTES.md
  • Emulator-validated: signed APK installs on Android 12+, blocked on API < 31 (INSTALL_FAILED_OLDER_SDK), launches, renders (CodeMirror + self-hosted fonts), runs converters, fully offline
  • Native file open works — plugin-dialog fires the SAF picker, plugin-fs reads the content:// URI; basenameFromPath() recovers a clean filename (unit-tested)
  • Found: layout needs WebView Chromium ≥ 111 (Tailwind v4); fine on updated Android 12+ devices, broken on the API 31 emulator's stock Chromium 91 — see docs/TAURI-NOTES.md
  • Add CI signing secrets (ANDROID_KEYSTORE_BASE64, ANDROID_KEYSTORE_PASSWORD, …) — maintainer action; the signed APK is attached to v1.7.0–v1.7.2
  • Remaining manual checks: save .zip via SAF, all 12 converters end-to-end, theme + 4 locales, upgrade-in-place on a real device

Deliverable

A signed universal .apk attached to each GitHub release, installable on Android 12+. Same converter feature set as web/desktop, fully offline.


Phase 8 — 2.0.0: Cloudflare, hardening & technical UI ✅

Status: complete (shipped in v2.0.0, 2026-10-22)

A platform release: a new home for the web app, a human check and analytics confined to the web build, a toolchain jump, an audit of every converter, a UI refresh and a hardened pipeline. Same 12 formats, same layout.

Tasks

8.1 Cloudflare Workers + custom domain

  • Web app served by the Cloudflare Worker jsonprism (Workers Static Assets, SPA fallback) at https://jsonprism.poli0981.dev; config in wrangler.jsonc, operations in docs/DEPLOYMENT.md
  • Cloudflare Workers Builds deploys every push to main; the GitHub Pages deploy workflow and public/404.html are gone
  • /api/* Worker in worker/: POST /api/turnstile/verify (same-origin only, 4 KB body cap, 30 requests / 60 s rate limit) and GET /api/health; structured Workers Logs without IPs, tokens or user content
  • 2.0.2: per-client rate limits for the whole site — the Worker runs first for everything except the hashed /assets/* bundles; pages 120 / 60 s, API 60 / 60 s, verify 30 / 60 s; IPv6 keyed on its /64; 429 with Retry-After
  • Static headers in public/_headers (CSP, HSTS, COOP, Permissions-Policy, immutable /assets/*), /jsonPrism/* → 301 in public/_redirects, robots.txt, sitemap.xml, .well-known/security.txt, Open Graph image
  • GitHub Pages keeps only a path-preserving redirect to the new domain (pages-redirect.yml, run by hand)
  • production-smoke.yml waits for each pushed commit to go live, then checks headers, routes, redirects and the API

8.2 Turnstile & Web Analytics (web only)

  • Cloudflare Turnstile inside the Consent Gate, verified server-side by the Worker; a pass is remembered for 7 days; if Cloudflare is unreachable the user may continue after a warning
  • Cloudflare Web Analytics (cookieless page views): production hostname only, after consent, toggle under Appearance, off by default when the browser sends Global Privacy Control
  • Neither service exists in desktop or Android builds
  • CONSENT_VERSION 2 asks every user again; the gate shows on web, Android, macOS and Linux (Windows relies on the installer license page)

8.3 Toolchain: TypeScript 7 / Node 26

  • Node.js 26 (.nvmrc, engines), npm 11; CI installs with npm ci --ignore-scripts
  • TypeScript 7 native compiler for tsc, plus a TypeScript 6 API alias for typescript-eslint; ES2025 target with an ES2023 lib to keep the Android WebView (Chromium 111) and macOS 12 floors
  • Majors: React 19.3, React Router 8.5 (react-router only), Vite 8.3, Tailwind CSS 4.3, i18next 26, ESLint 10, Vitest 5 (app + worker projects), Knip 6, Tauri 2.12
  • Removed: react-router-dom, Instrument Serif, the Tauri os plugin

8.4 Audit fixes

  • CSV: columns from every row (not just the first), optional escapeFormulae guard, reverse only converts canonical numbers
  • SQL: MySQL backslash escaping, MSSQL N'…' + NVARCHAR and 1000-row batches, CREATE TABLE types inferred across all rows, dotted table names quoted per part
  • RESX: reverse keeps strings such as "007", rejects DOCTYPE, validates XML; resheaders always written; CR encoded
  • XML: invalid element names sanitised, nested arrays wrapped, control characters replaced, output validated
  • BSON > 16 MiB → clear error; YAML quoteStyle works again + alias/merge-key limits; TOML reports nulls with their path, keeps big integers, stable key order
  • Batch: real binary in the ZIP for BSON/CBOR/MessagePack, processing twice keeps results, abort returns items to the queue
  • Accurate JSON error line/column on every engine; precision warning for integers beyond 2^53
  • Desktop/Android: trimmed capabilities and fs scope, stricter CSP, allowBackup="false", downloads through the native save dialog
  • Performance: inputs > 256 KB and all batches convert in a Web Worker; read-only, virtualised output editor; streaming ZIP
  • Accessibility (live regions, editor names, ≥ 24 px targets, <html lang>), i18n (ja + zh-CN completed, parity test in CI), local-only logger + "Copy diagnostics" on About

8.5 Technical UI refresh

  • Blueprint grid, mono uppercase labels, corner ticks, per-theme prism colours (light-theme contrast ≥ 4.5:1)
  • Header: animated wordmark, v2.0.0 · <commit> chip, EN/VI/JA/ZH switcher, Appearance menu (theme, hide scrollbars, analytics)
  • Terminal-style status bar, thin custom scrollbars, animations only under motion-safe, no theme flash, per-route document titles

8.6 CI hardening

  • Actions pinned to full commit SHAs, persist-credentials: false, least-privilege job permissions
  • CI: format, lint, knip, TypeScript 7 typecheck, tests + coverage, build, Worker deploy dry run; SonarQube Cloud (CI-based analysis); Rust fmt + clippy
  • Release: tag = package.json = Cargo.toml version check, one draft release, tauri-action v1, macOS universal build, JSONPrism_<version>_android-universal.apk, SHA256SUMS.txt + build-provenance attestations
  • Discord notifiers called with explicit webhook secrets; Dependabot grouped by package family with a cooldown

Deliverable

JSONPrism 2.0.0 on its own domain, with the human check and analytics confined to the web build. 864 tests in 92 files, 97% line coverage (converters incl. regression + contract tests, every UI component, hooks, stores, the Web Worker client, i18n parity across 4 locales, Worker).


Phase 9 — 2.1.0: JSONC → JSON ✅

Status: complete (shipped in v2.1.0, 2026-10-29)

The most common "this isn't valid JSON" paste — config files with comments — now converts in one step.

  • src/converters/jsonc.ts: hand-written, no dependency. Comments and trailing commas become spaces at the same offsets (error line/column match the input), JSON.parse validates, then a token-level printer lays the result out without building JS values — big integers, number spelling, duplicate and __proto__ keys survive. Iterative, with an output-size guard for pathological nesting.
  • Input-only formats: ConverterMeta.inputOnly; the chip is disabled in the JSON → direction, switching to JSON → falls back to JSONL, and a stored input-only format opens in → JSON.
  • Reverse errors carry an optional line/column (ConversionFailure), shown like JSON input errors.
  • JSONC input editor: legacy JSON mode for comment highlighting plus a linter that shares the converter's parser.
  • JSON → input that is valid JSONC gets a one-click "Convert JSONC → JSON" hint.
  • Accepts .jsonc and .json (plus .txt) in the single-file and batch flows; strings in all four locales.
  • 2.1.1 (2026-11-04): every npm, Cargo and GitHub Actions dependency at its latest release within the current majors; THIRD-PARTY.md re-synced with the lockfiles

Deliverable

13 chips — 12 target formats plus JSONC as an input. 932 tests in 94 files.


Beyond — Ideas (no commitment)

Deferred from 2.0.0

  • Lazy-load non-English locales — about 20 KB gzip off the first load
  • PWA / offline install for the web app
  • Code signing — Windows Authenticode and macOS notarization — plus a signed updater
  • SBOM for release builds
  • OpenSSF Scorecard
  • End-to-end tests — Playwright (web), tauri-driver (desktop)
  • JSON tools — JSON Schema, JSONPath and diff features
  • More formats — INI, .env, Java .properties, Excel .xlsx
  • JSONC as input for every target — accept comments in the JSON → direction (e.g. tsconfig.json straight to YAML) instead of converting to JSON first; changes the strict parseJsonInput contract, so it needs its own design
  • Streaming NDJSON for very large files
  • Community translation workflow (ja and zh-CN are AI-translated today)
  • Drop the TypeScript 6 alias once TypeScript 7 ships an API that typescript-eslint supports

Other ideas

  • Type generation: TypeScript types or Go structs from sample JSON
  • CLI version: same converter modules, exposed as a Node CLI for CI pipelines
  • VS Code extension: surface the converters in the editor command palette
  • Sharing: hash-based shareable URLs (#data=...) for sample inputs (privacy: opt-in only)

Nothing here is scheduled. An item moves into a numbered phase when work on it starts.


Tracking

Update this file when:

  • A task is completed (mark it - [x] and add a date if significant)
  • An estimate changes meaningfully
  • The phase plan changes (and explain why in the commit message)
  • A new phase is added to the "Beyond" section

The goal: anyone reading this should be able to answer "What's the current state of JSONPrism?" in 30 seconds.