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
/**
* Author personas — 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 author record is shaped, trimmed, or patched. This module
* has NO I/O — pure functions only.
*
* An Author is a reusable creative persona used as a series' cover byline and
* as the prompt source for generating an author headshot on the book cover:
* - name — display name / byline
* - writingStyle — voice / tone notes fed into stage prompts
* - bio — back-cover / about-the-author blurb
* - physicalDescription — subject description for the headshot render
* - headshotStyle — art/photography direction for the headshot render
* - headshotImageUrl — optional pointer to a generated/chosen headshot
*
* Authors are `db-primary` (PostgreSQL) and federate across peers via the
* per-record peer-sync push pipeline (`server/services/sharing/peerSync.js`,
* record kind `author`, sync category `authors`): a create auto-subscribes to
* every authors-enabled peer, every edit/delete pushes the LWW-merged record,
* and the referenced headshot image rides along as a pulled asset. A federated
* series still keeps its denormalized `author` byline string so peers render
* the cover correctly even before the author record itself has synced.
*/
import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { localImageFilename } from '../../lib/localImageFilename.js';
import { isStr, trimTo } from '../../lib/textUtils.js';
import { NAME_MAX, WRITING_STYLE_MAX, BIO_MAX, PHYSICAL_DESCRIPTION_MAX, HEADSHOT_STYLE_MAX, HEADSHOT_IMAGE_URL_MAX } from '../../lib/authorLimits.js';
export { NAME_MAX, WRITING_STYLE_MAX, BIO_MAX, PHYSICAL_DESCRIPTION_MAX, HEADSHOT_STYLE_MAX, HEADSHOT_IMAGE_URL_MAX };
export const AUTHOR_ID_RE = /^auth-[A-Za-z0-9-]{1,64}$/;
/**
* Normalize a raw author 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 sanitizeAuthor(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,
writingStyle: trimTo(raw.writingStyle, WRITING_STYLE_MAX),
bio: trimTo(raw.bio, BIO_MAX),
physicalDescription: trimTo(raw.physicalDescription, PHYSICAL_DESCRIPTION_MAX),
headshotStyle: trimTo(raw.headshotStyle, HEADSHOT_STYLE_MAX),
// Empty string = no headshot chosen; never null so the on-disk shape is stable.
headshotImageUrl: trimTo(raw.headshotImageUrl, HEADSHOT_IMAGE_URL_MAX),
createdAt,
updatedAt,
deleted,
deletedAt: deleted && isStr(raw.deletedAt) && raw.deletedAt.trim() ? raw.deletedAt : null,
};
}
/**
* Resolve an author's `headshotImageUrl` to the bare gallery-image filename
* that lives under `data/images/` — the unit the peer-sync asset pipeline can
* hash + transfer. Thin wrapper over the shared `localImageFilename` helper
* (the named export is what `peerSync.js` imports).
*/
export function headshotImageFilename(headshotImageUrl) {
return localImageFilename(headshotImageUrl);
}
/** Build a fresh author record from create input. */
export function buildAuthorRecord(input, { id, now }) {
return sanitizeAuthor({
id,
name: input.name,
writingStyle: input.writingStyle || '',
bio: input.bio || '',
physicalDescription: input.physicalDescription || '',
headshotStyle: input.headshotStyle || '',
headshotImageUrl: input.headshotImageUrl || '',
createdAt: now,
updatedAt: now,
deleted: false,
deletedAt: null,
});
}
// The user-authored scalar fields a partial patch may overwrite. This is also
// the set the conflict journal tracks + the merge can restore — mirrored in
// RESTORABLE_FIELDS.author (conflictJournal.js). `id`, the LWW/tombstone trio,
// and `createdAt` are server-owned / structural, never patchable/restorable.
const PATCHABLE = [
'name', 'writingStyle', 'bio', 'physicalDescription', 'headshotStyle', 'headshotImageUrl',
];
/**
* LWW merge decision for one incoming author record against the local copy.
*
* - remote is sanitized here (drop-on-floor on a malformed payload → returns
* `{ next: null }` so the caller skips it).
* - No local counterpart → insert the remote verbatim (`inserted: true`).
* - Both present → newer `updatedAt` wins via the shared `compareNewerWins`
* (epoch-ms compare, unparseable-loses, tie → local). Tombstones ride the
* same path: a deleted record with a newer `updatedAt` overwrites a live
* local one, and vice-versa.
*
* Returns `{ next, inserted, remoteWins, changed }`. `changed` is false when the
* winning record is byte-identical to local (sanitized both sides → canonical
* key order → JSON compare is sufficient).
*/
export function mergeAuthorRecord(local, remoteRaw) {
const remote = sanitizeAuthor(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, while a present
* empty-string value applies the clear (distinguish-absent-vs-empty per
* AGENTS.md). Always bumps `updatedAt`.
*/
export function applyAuthorPatch(current, patch = {}) {
const next = { ...current };
for (const key of PATCHABLE) {
if (key in patch) next[key] = patch[key];
}
next.updatedAt = new Date().toISOString();
return sanitizeAuthor(next);
}