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

11.2 KB
Raw Blame
/**
 * Writers Room — pure record transforms for cross-peer federation (#1565).
 *
 * Works (PostgreSQL `writers_room_works` + decomposed `writers_room_draft_versions`)
 * federate across peers via the per-record peer-sync push pipeline — record kind
 * `writersRoomWork`, sync category `writersRoomWorks`. A federated work record IS
 * the manifest local.js round-trips: work metadata + the active-draft pointer +
 * the version history (`drafts[]` of draft-version METADATA). The draft PROSE
 * BODIES stay file-primary (`works/<workId>/drafts/<draftId>.md`) and replicate
 * separately as assets via the body manifest in sync.js — never round-tripped
 * through this record.
 *
 * This module is storage-agnostic so the PostgreSQL backend (db.js) and the
 * test/dev file backend (store.js) can never drift in how an incoming work is
 * sanitized or LWW-merged. Mirrors creativeDirector/projectsLogic.js.
 */

import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { sanitizeSoftDeleteFields } from '../../lib/syncWire.js';
import { WORK_ID_RE, DRAFT_ID_RE, FOLDER_ID_RE, EXERCISE_ID_RE } from './_shared.js';
import { isStr } from '../../lib/textUtils.js';

// The peer-sync record kind + the asset kind its draft bodies ride. Exported so
// peerSync.js / sync.js reference one source of truth instead of bare strings.
export const WRITERS_ROOM_WORK_KIND = 'writersRoomWork';
export const WRITERS_ROOM_DRAFT_ASSET_KIND = 'writers-room-draft';
// Folders + exercises federate too (#1645 — follow-up to #1565). Both are
// body-less records (no file-primary `.md`, no asset manifest), so their wiring
// is the same per-record LWW push as works minus the draft-body machinery.
export const WRITERS_ROOM_FOLDER_KIND = 'writersRoomFolder';
export const WRITERS_ROOM_EXERCISE_KIND = 'writersRoomExercise';

/**
 * Normalize a raw work manifest into the canonical stored shape for a sync
 * round-trip. Returns null for a non-object or a record without a usable id
 * (the "drop on the floor" contract every sanitizer shares, so a malformed peer
 * payload can't land). The work body (title/kind/status/drafts/links/liveMode)
 * is passed through verbatim — it is all app-authored data — while the LWW key
 * (`updatedAt`) and the soft-delete trio are normalized so the wire/hash shape
 * is stable regardless of on-disk key position. Mirrors `sanitizeProjectForSync`.
 */
export function sanitizeWorkForSync(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  // The id is used as a filesystem path segment (works/<id>/...) and the path
  // helpers enforce WORK_ID_RE — so drop a peer-supplied id that isn't a valid
  // work id BEFORE merge/persist, rather than letting it throw in the file
  // backend's saveManifest or plant an unaddressable PG row.
  if (!isStr(raw.id) || !WORK_ID_RE.test(raw.id)) return null;
  const createdAt = isStr(raw.createdAt) ? raw.createdAt : new Date().toISOString();
  const updatedAt = isStr(raw.updatedAt) ? raw.updatedAt : createdAt;
  const { deleted, deletedAt } = sanitizeSoftDeleteFields(raw);
  // Draft-version ids are ALSO filesystem path segments (drafts/<draftId>.md), so
  // ALWAYS normalize to a filtered array — drop any draft whose id isn't
  // DRAFT_ID_RE-valid (and coerce a missing/non-array `drafts` to []). Otherwise
  // a malformed peer payload persists a work whose body read throws in
  // wrDraftPath(), or whose `manifest.drafts` isn't the array local readers
  // assume. Clamp the active pointer to a surviving draft (or null). Legitimate
  // works (live or tombstone) always carry a drafts[] array, so this is a no-op
  // for them — only malformed input is reshaped.
  const out = { ...raw, createdAt, updatedAt, deleted, deletedAt };
  const draftsArray = Array.isArray(raw.drafts) ? raw.drafts : [];
  out.drafts = draftsArray.filter((d) => d && typeof d === 'object' && isStr(d.id) && DRAFT_ID_RE.test(d.id));
  const ids = new Set(out.drafts.map((d) => d.id));
  out.activeDraftVersionId = isStr(raw.activeDraftVersionId) && ids.has(raw.activeDraftVersionId)
    ? raw.activeDraftVersionId
    : (out.drafts[0]?.id ?? null);
  return out;
}

/**
 * LWW merge decision for one incoming work record against the local copy —
 * mirrors `mergeProjectRecord` (creativeDirector/projectsLogic.js):
 *   - remote sanitized here (drop-on-floor on a malformed payload → `next: null`).
 *   - No local counterpart → insert the remote verbatim (`inserted: true`).
 *   - Both present → newer `updatedAt` wins (`compareNewerWins`: epoch-ms,
 *     unparseable-loses, tie → local). Tombstones ride the same path.
 * Returns `{ next, inserted, remoteWins, changed }`; `changed` is false when the
 * winner is byte-identical to local. The whole manifest is LWW-overwritten (no
 * field-union), so it is hashed in full by `contentHashForRecord`.
 */
export function mergeWorkRecord(local, remoteRaw) {
  const remote = sanitizeWorkForSync(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);
  // The remote arrives wire-stripped of `liveMode.usage`/`renderUsage` (local-only
  // daily budgets — see sanitizeRecordForWire). When the remote wins the LWW,
  // carry the RECEIVER's own counters forward onto it so a peer's manuscript edit
  // doesn't reset this machine's budget state. When local wins, `next` is already
  // local (counters intact).
  const next = remoteWins ? preserveLocalLiveCounters(remote, local) : local;
  const changed = JSON.stringify(next) !== JSON.stringify(local);
  return { next, inserted: false, remoteWins, changed };
}

/** Re-attach the receiver's local-only live-mode counters onto a winning remote. */
function preserveLocalLiveCounters(remote, local) {
  const localLive = local?.liveMode;
  if (!localLive || typeof localLive !== 'object' || Array.isArray(localLive)) return remote;
  const carried = {};
  if (localLive.usage !== undefined) carried.usage = localLive.usage;
  if (localLive.renderUsage !== undefined) carried.renderUsage = localLive.renderUsage;
  if (Object.keys(carried).length === 0) return remote;
  return { ...remote, liveMode: { ...(remote.liveMode || {}), ...carried } };
}

/**
 * The draft-version → file-body asset references a work carries: one entry per
 * draft version whose id + work id are valid path segments. Pure (no disk I/O) —
 * sync.js hashes the on-disk `.md` per entry to build the wire manifest, and the
 * receiver resolves each `{ workId, draftId }` to `works/<workId>/drafts/<draftId>.md`.
 * Skips drafts with a malformed id so a hand-edited/corrupt manifest can't smuggle
 * a path-traversal filename into the asset pull.
 */
export function draftAssetEntries(work) {
  const drafts = Array.isArray(work?.drafts) ? work.drafts : [];
  const workId = work?.id;
  if (!isStr(workId) || !WORK_ID_RE.test(workId)) return [];
  const out = [];
  for (const d of drafts) {
    const draftId = d?.id;
    if (!isStr(draftId) || !DRAFT_ID_RE.test(draftId)) continue;
    out.push({ workId, draftId });
  }
  return out;
}

// ---------- folders + exercises (body-less records) ----------

/**
 * LWW merge decision for a body-less record (folder/exercise) against the local
 * copy. Same contract as `mergeWorkRecord` minus the live-counter carry-forward
 * (these records have no local-only counters): the remote is sanitized here
 * (drop-on-floor → `next: null`), a missing local inserts the remote, and
 * otherwise newer `updatedAt` wins (`compareNewerWins`: epoch-ms, unparseable-
 * loses, tie → local). The whole record is LWW-overwritten (no field-union) and
 * hashed in full by `contentHashForRecord`. Tombstones ride the same path.
 */
function mergeBodylessRecord(local, remoteRaw, sanitize) {
  const remote = sanitize(remoteRaw);
  if (!remote) return { next: null, inserted: false, remoteWins: false, changed: false };
  if (!local) return { next: remote, inserted: true, remoteWins: true, changed: true };
  // Derive the LOCAL lww key through the SAME sanitizer as the remote so the
  // compare is symmetric. Exercises predate federation and may carry no stored
  // `updatedAt` (the sanitizer derives it from `finishedAt ?? startedAt`); the
  // stored local record is raw (unsanitized), so an `undefined` local.updatedAt
  // would lose to ANY parseable remote — `compareNewerWins` treats an
  // unparseable incumbent as always-loses — letting a STALE push clobber a
  // newer local. `sanitize(local)` can't be null here (local came from our own
  // store with a valid id); fall back to the raw key defensively.
  const localKey = sanitize(local)?.updatedAt ?? local.updatedAt;
  const remoteWins = compareNewerWins(remote.updatedAt, localKey);
  const next = remoteWins ? remote : local;
  const changed = JSON.stringify(next) !== JSON.stringify(local);
  return { next, inserted: false, remoteWins, changed };
}

/**
 * Normalize a raw folder into the canonical stored shape for a sync round-trip.
 * Drops a non-object or a record without a usable `wr-folder-` id (the
 * drop-on-floor contract). The body (`name`/`parentId`/`sortOrder`) passes
 * through verbatim; the LWW key (`updatedAt`) + soft-delete trio are normalized
 * so the wire/hash shape is stable regardless of on-disk key position.
 */
export function sanitizeFolderForSync(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  if (!isStr(raw.id) || !FOLDER_ID_RE.test(raw.id)) return null;
  const createdAt = isStr(raw.createdAt) ? raw.createdAt : new Date().toISOString();
  const updatedAt = isStr(raw.updatedAt) ? raw.updatedAt : createdAt;
  const { deleted, deletedAt } = sanitizeSoftDeleteFields(raw);
  return { ...raw, createdAt, updatedAt, deleted, deletedAt };
}

/**
 * Normalize a raw exercise into the canonical stored shape for a sync round-trip.
 * Drops a non-object or a record without a usable `wr-ex-` id. Exercises predate
 * federation and carry no `updatedAt`/`createdAt` — derive both from the existing
 * timestamps (`startedAt` is the creation moment; `finishedAt ?? startedAt` is the
 * last mutation) so an OLD pre-federation exercise still gets a stable LWW key and
 * a fresh one (stamped by local.js) round-trips unchanged. Soft-delete trio is
 * normalized for the tombstone-aware merge even though no current path deletes an
 * exercise (a future peer might).
 */
export function sanitizeExerciseForSync(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  if (!isStr(raw.id) || !EXERCISE_ID_RE.test(raw.id)) return null;
  const createdAt = isStr(raw.createdAt) ? raw.createdAt
    : (isStr(raw.startedAt) ? raw.startedAt : new Date().toISOString());
  const updatedAt = isStr(raw.updatedAt) ? raw.updatedAt
    : (isStr(raw.finishedAt) ? raw.finishedAt : createdAt);
  const { deleted, deletedAt } = sanitizeSoftDeleteFields(raw);
  return { ...raw, createdAt, updatedAt, deleted, deletedAt };
}

/** LWW merge decision for one incoming folder record. */
export function mergeFolderRecord(local, remoteRaw) {
  return mergeBodylessRecord(local, remoteRaw, sanitizeFolderForSync);
}

/** LWW merge decision for one incoming exercise record. */
export function mergeExerciseRecord(local, remoteRaw) {
  return mergeBodylessRecord(local, remoteRaw, sanitizeExerciseForSync);
}