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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* 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);
}