Add database ingestion system for custom hymnbook bundles

[Copilot]

Users needed a way to import their own hymnbook databases without server infrastructure changes.

Changes

Documentation

• DATABASE_INGESTION.md - Complete JSON schema specification for song bundles with field types, validation requirements, and ABC notation guide
• QUICK_START_INGESTION.md - Fast-track guide with key field reference and common issues
• examples/README.md - Tool usage and customization instructions

Core Import Utility

source/logic/songs/customImporter.ts

• importFromJson() / importFromObject() - Parse and validate bundle data
• bundleExists() - Duplicate detection
• Validates: UUID v4 format, required fields, verse index sequencing
• Integrates with existing SongUpdaterUtils.saveServerSongBundleToDatabase()

Tools

• create-custom-bundle.{js,py} - Generate properly formatted JSON with sample data
• validate-bundle.js - Pre-import validation (15+ checks: UUIDs, timestamps, ABC notation, metadata types)

Usage

import { CustomImporter } from './source/logic/songs/customImporter';
import bundle from './assets/custom_hymns.json';

// Validates and imports bundle
await CustomImporter.importFromObject(bundle);

// Check before importing
if (!CustomImporter.bundleExists(bundle.uuid)) {
  await CustomImporter.importFromObject(bundle);
}

Generate and validate bundles:

node examples/create-custom-bundle.js
node examples/validate-bundle.js custom_hymnbook_bundle.json

Bundle Format

{
  "id": 1,
  "abbreviation": "MYHB",
  "name": "My Hymnbook",
  "uuid": "uuid-v4-here",
  "hash": "md5-hash",
  "songs": [{
    "id": 1,
    "name": "Hymn Title",
    "verses": [{
      "id": 1,
      "name": "Verse 1",
      "content": "Line 1\nLine 2",
      "index": 0,
      "uuid": "uuid-v4-here"
    }],
    "abcMelodies": [],  // Optional ABC notation
    "metadata": []       // Optional: Author, Year, Copyright, etc.
  }]
}

Security: CodeQL scan passed (0 alerts)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• static.realm.io
  • Triggering command: /usr/local/bin/node /home/REDACTED/work/hymnbook/hymnbook/node_modules/prebuild-install/bin.js --runtime napi (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

I want to be able to ingest my own hymnbook database into this app, how do i do it.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.