vibed/nbd/.beans/nbd-s16w--multiple-file-format-support-md-toml-jsonb.md

title	status	type	priority	created_at	updated_at
Multiple file format support (md, toml, jsonb)	completed	feature	normal	2026-03-10T23:30:30Z	2026-03-10T23:30:30Z

Add --ftype flag to create and update to write tickets in markdown, TOML, or binary JSON (CBOR) in addition to the existing JSON format. Format is detected from file extension on read.

Motivation

Markdown format lets agents write long-form ticket bodies with full markdown syntax, and makes tickets human-readable in a file browser. TOML is a natural config format. CBOR offers compact binary storage.

Approach

New crate dependencies (Cargo.toml)

Evaluate and add:

• toml — TOML serialisation (likely toml = "0.8")
• serde_yml or serde_yaml — YAML frontmatter (for .md files)
• ciborium — CBOR binary JSON (.jsonb)

ticket.rs

No changes needed — Ticket already derives Serialize/Deserialize.

store.rs

New enum FileFormat { Json, Markdown, Toml, Jsonb }.

New function detect_format(path: &Path) -> FileFormat:

• .json → Json
• .md → Markdown
• .toml → Toml
• .jsonb → Jsonb
• Unknown → Json (fallback)

Update ticket_path(root, id, format) to use the format-appropriate extension. This is a breaking change to the function signature — update all callers.

Update read_ticket(root, id):

1. Try each known extension in order until a file is found.
2. Read the file and dispatch to the format-appropriate deserialiser.

Serialisation helpers (private):

• serialize_json(ticket) -> String
• serialize_toml(ticket) -> String
• serialize_markdown(ticket) -> String — TOML frontmatter (+++ delimiters) with body as file content
• serialize_jsonb(ticket) -> Vec<u8>

Deserialization helpers (private):

• deserialize_markdown(bytes) -> Result<Ticket> — parse frontmatter + body

Update list_tickets to scan for *.json, *.md, *.toml, *.jsonb files.

Update write_ticket to accept format: FileFormat and write in the appropriate format.

main.rs

Add --ftype [json|md|toml|jsonb] option (default json) to create and update. Conversion on update --ftype: read old file, write new format, delete old file (if extension changed).

Markdown format (TOML frontmatter)

+++
id = "a3f9c2"
title = "Fix login bug"
priority = 8
status = "in_progress"
ticket_type = "bug"
dependencies = ["b7d41e"]
+++

Long-form body text goes here. Supports full markdown.

Tests

• Unit tests: roundtrip each format (JSON already tested).
• Integration tests: nbd create --ftype md creates a .md file; nbd read finds and parses it.
• Integration test: nbd update <id> --ftype toml converts format and removes old file.

Files touched

• Cargo.toml — new dependencies
• src/store.rs — format detection, multi-format read/write, updated list_tickets
• src/main.rs — --ftype flags
• src/tests.rs — format roundtrip tests
• tests/integration.rs — format integration tests
• README.md — document --ftype
• docs/ARCHITECTURE.md — update storage layout section