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

5.7 KB
Raw Blame
/**
 * Music artists — 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 in
 * how an artist record is shaped, trimmed, or patched. This module has NO I/O —
 * pure functions only. It deliberately mirrors `services/authors/logic.js`: an
 * Artist is the music studio's analogue of an Author persona.
 *
 * An Artist is a reusable musical persona used as a track/album byline and as
 * the prompt source for generating a portrait + music:
 *   - name                — display / stage name
 *   - genre               — primary genre(s), e.g. "indie folk, dream pop"
 *   - bio                 — about-the-artist blurb
 *   - musicalStyle        — voice / production notes fed into music-gen prompts
 *                           (the audio analogue of an author's writingStyle)
 *   - physicalDescription — subject description for the portrait render
 *   - portraitStyle       — art/photography direction for the portrait render
 *   - portraitImageUrl    — optional pointer to a generated/chosen portrait
 *
 * Artists are `db-primary` (PostgreSQL `artists` table) and federate across
 * peers via the per-record peer-sync pipeline (`record kind: artist`, sync
 * category: artists). A federated album/track still keeps denormalized artist
 * text so peers render before the artist persona itself arrives.
 */

import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { localImageFilename } from '../../lib/localImageFilename.js';
import { isStr, trimTo } from '../../lib/textUtils.js';
import { NAME_MAX, GENRE_MAX, BIO_MAX, MUSICAL_STYLE_MAX, PHYSICAL_DESCRIPTION_MAX, PORTRAIT_STYLE_MAX, PORTRAIT_IMAGE_URL_MAX } from '../../lib/artistLimits.js';
export { NAME_MAX, GENRE_MAX, BIO_MAX, MUSICAL_STYLE_MAX, PHYSICAL_DESCRIPTION_MAX, PORTRAIT_STYLE_MAX, PORTRAIT_IMAGE_URL_MAX };

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


/**
 * Normalize a raw artist record into the canonical stored shape. Returns null
 * for a non-object or a record without a usable id/name (mirrors the other
 * sanitizers' "drop on the floor" contract so a malformed import can't land).
 */
export function sanitizeArtist(raw) {
  if (!raw || typeof raw !== 'object') return null;
  if (!isStr(raw.id) || !raw.id) return null;
  const name = trimTo(raw.name, NAME_MAX);
  if (!name) 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,
    name,
    genre: trimTo(raw.genre, GENRE_MAX),
    bio: trimTo(raw.bio, BIO_MAX),
    musicalStyle: trimTo(raw.musicalStyle, MUSICAL_STYLE_MAX),
    physicalDescription: trimTo(raw.physicalDescription, PHYSICAL_DESCRIPTION_MAX),
    portraitStyle: trimTo(raw.portraitStyle, PORTRAIT_STYLE_MAX),
    // Empty string = no portrait chosen; never null so the on-disk shape is stable.
    portraitImageUrl: trimTo(raw.portraitImageUrl, PORTRAIT_IMAGE_URL_MAX),
    createdAt,
    updatedAt,
    deleted,
    deletedAt: deleted && isStr(raw.deletedAt) && raw.deletedAt.trim() ? raw.deletedAt : null,
  };
}

/**
 * Resolve an artist's `portraitImageUrl` to the bare gallery-image filename that
 * lives under `data/images/` — the unit the peer-sync asset pipeline hashes +
 * transfers. Thin wrapper over the shared `localImageFilename` helper (the named
 * export is what `peerSync.js` imports).
 */
export function portraitImageFilename(portraitImageUrl) {
  return localImageFilename(portraitImageUrl);
}

/** Build a fresh artist record from create input. */
export function buildArtistRecord(input, { id, now }) {
  return sanitizeArtist({
    id,
    name: input.name,
    genre: input.genre || '',
    bio: input.bio || '',
    musicalStyle: input.musicalStyle || '',
    physicalDescription: input.physicalDescription || '',
    portraitStyle: input.portraitStyle || '',
    portraitImageUrl: input.portraitImageUrl || '',
    createdAt: now,
    updatedAt: now,
    deleted: false,
    deletedAt: null,
  });
}

// The user-authored scalar fields a partial patch may overwrite. `id`, the
// LWW/tombstone trio, and `createdAt` are server-owned / structural.
const PATCHABLE = [
  'name', 'genre', 'bio', 'musicalStyle', 'physicalDescription', 'portraitStyle', 'portraitImageUrl',
];

/**
 * LWW merge decision for one incoming artist record against the local copy.
 * Mirrors mergeAuthorRecord: sanitize remote (drop-on-floor), insert when no
 * local counterpart, else newer `updatedAt` wins (tombstone-aware). Returns
 * `{ next, inserted, remoteWins, changed }`.
 */
export function mergeArtistRecord(local, remoteRaw) {
  const remote = sanitizeArtist(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 — an absent key preserves the current value, a present empty-string
 * applies the clear (distinguish-absent-vs-empty per AGENTS.md). Bumps updatedAt.
 */
export function applyArtistPatch(current, patch = {}) {
  const next = { ...current };
  for (const key of PATCHABLE) {
    if (key in patch) next[key] = patch[key];
  }
  next.updatedAt = new Date().toISOString();
  return sanitizeArtist(next);
}