Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

6.1 KB
Raw Blame
/**
 * Music albums — shared mutation logic (backend-agnostic).
 *
 * The file backend (file.js) and the PostgreSQL backend (db.js) both import the
 * sanitizer + record builders from here so the two backends can never drift.
 * This module has NO I/O — pure functions only. Mirrors `services/artists/
 * logic.js` (the persona store) with album-specific fields.
 *
 * An Album groups ordered tracks under an artist, with cover art:
 *   - title          — album title
 *   - artistId       — FK to the owning artist (`artist-…`), or '' for none
 *   - artist         — denormalized artist name, so a peer/cover renders before
 *                      the artist record itself has synced (mirrors series→author)
 *   - description    — liner-notes blurb
 *   - genre          — primary genre(s)
 *   - releaseYear    — integer year, or null
 *   - coverImageUrl  — optional pointer to a generated/uploaded cover image
 *   - trackIds       — ordered list of track ids (`track-…`) on the album
 *
 * Albums are `db-primary` (PostgreSQL `albums` table) and federate across peers
 * via the per-record peer-sync pipeline (`record kind: album`, sync category:
 * albums). Tracks still carry denormalized artist/album context so they render
 * before related records arrive.
 */

import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { localImageFilename } from '../../lib/localImageFilename.js';
import { isStr, trimTo } from '../../lib/textUtils.js';
import { TITLE_MAX, ARTIST_ID_MAX, ARTIST_NAME_MAX, DESCRIPTION_MAX, GENRE_MAX, COVER_IMAGE_URL_MAX, TRACK_IDS_MAX, TRACK_ID_MAX, RELEASE_YEAR_MIN, RELEASE_YEAR_MAX } from '../../lib/albumLimits.js';
export { TITLE_MAX, ARTIST_ID_MAX, ARTIST_NAME_MAX, DESCRIPTION_MAX, GENRE_MAX, COVER_IMAGE_URL_MAX, TRACK_IDS_MAX, TRACK_ID_MAX, RELEASE_YEAR_MIN, RELEASE_YEAR_MAX };

export const ALBUM_ID_RE = /^album-[A-Za-z0-9-]{1,64}$/;

// Sane bounds for a release year — wide enough for archival reissues, narrow
// enough to reject a fat-fingered/garbage value.

// Clamp an integer release year into the supported band; null when unparseable
// so an album without a year stays distinct from one pinned to a bound.
function sanitizeReleaseYear(v) {
  if (typeof v !== 'number' || !Number.isFinite(v)) return null;
  const y = Math.round(v);
  if (y < RELEASE_YEAR_MIN || y > RELEASE_YEAR_MAX) return null;
  return y;
}

// Ordered, deduped list of track ids — keeps the first occurrence's position,
// drops blanks/non-strings, and bounds the length. Order IS the track order.
function sanitizeTrackIds(arr) {
  const seen = new Set();
  return (Array.isArray(arr) ? arr : [])
    .map((v) => trimTo(v, TRACK_ID_MAX))
    .filter((id) => id && !seen.has(id) && seen.add(id))
    .slice(0, TRACK_IDS_MAX);
}

/**
 * Normalize a raw album record into the canonical stored shape. Returns null for
 * a non-object or a record without a usable id/title (drop-on-floor contract).
 */
export function sanitizeAlbum(raw) {
  if (!raw || typeof raw !== 'object') return null;
  if (!isStr(raw.id) || !raw.id) return null;
  const title = trimTo(raw.title, TITLE_MAX);
  if (!title) return null;
  const createdAt = isStr(raw.createdAt) ? raw.createdAt : new Date().toISOString();
  const updatedAt = isStr(raw.updatedAt) ? raw.updatedAt : createdAt;
  const deleted = raw.deleted === true;
  return {
    id: raw.id,
    title,
    artistId: trimTo(raw.artistId, ARTIST_ID_MAX),
    artist: trimTo(raw.artist, ARTIST_NAME_MAX),
    description: trimTo(raw.description, DESCRIPTION_MAX),
    genre: trimTo(raw.genre, GENRE_MAX),
    releaseYear: sanitizeReleaseYear(raw.releaseYear),
    // Empty string = no cover chosen; never null so the on-disk shape is stable.
    coverImageUrl: trimTo(raw.coverImageUrl, COVER_IMAGE_URL_MAX),
    trackIds: sanitizeTrackIds(raw.trackIds),
    createdAt,
    updatedAt,
    deleted,
    deletedAt: deleted && isStr(raw.deletedAt) && raw.deletedAt.trim() ? raw.deletedAt : null,
  };
}

/**
 * Resolve an album's `coverImageUrl` to the bare gallery-image filename under
 * `data/images/` for peer-sync asset transfer. Thin wrapper over the shared
 * `localImageFilename` helper (the named export is what `peerSync.js` imports).
 */
export function coverImageFilename(coverImageUrl) {
  return localImageFilename(coverImageUrl);
}

/** Build a fresh album record from create input. */
export function buildAlbumRecord(input, { id, now }) {
  return sanitizeAlbum({
    id,
    title: input.title,
    artistId: input.artistId || '',
    artist: input.artist || '',
    description: input.description || '',
    genre: input.genre || '',
    releaseYear: input.releaseYear ?? null,
    coverImageUrl: input.coverImageUrl || '',
    trackIds: input.trackIds || [],
    createdAt: now,
    updatedAt: now,
    deleted: false,
    deletedAt: null,
  });
}

// The user-authored fields a partial patch may overwrite. `id`, the LWW/
// tombstone trio, and `createdAt` are server-owned / structural.
const PATCHABLE = [
  'title', 'artistId', 'artist', 'description', 'genre', 'releaseYear', 'coverImageUrl', 'trackIds',
];

/**
 * LWW merge decision for one incoming album record against the local copy.
 * Mirrors mergeArtistRecord. Returns `{ next, inserted, remoteWins, changed }`.
 */
export function mergeAlbumRecord(local, remoteRaw) {
  const remote = sanitizeAlbum(remoteRaw);
  if (!remote) return { next: null, inserted: false, remoteWins: false, changed: false };
  if (!local) return { next: remote, inserted: true, remoteWins: true, changed: true };
  const remoteWins = compareNewerWins(remote.updatedAt, local.updatedAt);
  const next = remoteWins ? remote : local;
  const changed = JSON.stringify(next) !== JSON.stringify(local);
  return { next, inserted: false, remoteWins, changed };
}

/**
 * Apply a partial patch onto an existing record. Only keys PRESENT in `patch`
 * overwrite — absent preserves, present-empty clears (per AGENTS.md). Bumps
 * updatedAt.
 */
export function applyAlbumPatch(current, patch = {}) {
  const next = { ...current };
  for (const key of PATCHABLE) {
    if (key in patch) next[key] = patch[key];
  }
  next.updatedAt = new Date().toISOString();
  return sanitizeAlbum(next);
}