markdown-playlist-archive

name	markdown-playlist-archive
description	Build append-only markdown table archives with daily file partitioning and replay-friendly history surfacing
domain	sample-runtime, persistence
confidence	high
source	earned (mood-playlist-builder sample)

Context

Some samples need lightweight persistence without introducing databases. Markdown tables are human-readable, git-friendly, and easy to inspect, but they need careful append semantics to avoid duplicate headers or accidental overwrites.

Patterns

Append-Only Table Writer

• Use one helper that:
  • creates parent directories (mkdirSync(..., { recursive: true }))
  • creates file + header + divider on first write
  • appends rows on subsequent writes
  • only re-inserts headers if a legacy file exists without the expected header
• Escape pipe characters in cell content before writing markdown rows.

Daily Partitioning + Long-Term Archive

• Daily activity file: folder/playlist-YYYY-MM-DD.md for batch-specific rows.
• Global longitudinal file: mood-archive.md with timestamped minimal entries.
• On startup, read archive and surface recent + frequent values to guide new runs.

External Link Resolution with Graceful Fallback

• Resolve external links (e.g., YouTube) to canonical URLs when possible.
• Extract validated IDs (v query, 11-char pattern) for aggregate actions.
• When resolution fails, store a deterministic search URL so the row still remains actionable.

Examples

• mood-playlist-builder/mood-logic.ts
  • appendMarkdownRow(...)
  • readMoodArchive(...)
  • extractYouTubeVideoId(...)
  • buildYouTubePlaylistUrl(...)
• mood-playlist-builder/index.ts
  • startup archive surfacing
  • daily playlist + archive append
  • browser launch from aggregated video IDs

Anti-Patterns

• Rewriting the entire markdown file every run (destroys history).
• Duplicating headers for every appended row.
• Building aggregate playback URLs from unvalidated IDs.
• Persisting only normalized values and losing the user’s original raw input.