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
/**
* Writers Room — cross-peer federation facade (#1565).
*
* The single import surface for the peer-sync graph (peerSync.js) and tombstone
* GC (tombstoneGc.js). Routes the LWW/tombstone merge + prune through the active
* storage backend (store.js → db.js or the file backend) and owns the two
* facade-level concerns the backends can't: the file-primary draft `.md` BODY
* asset manifest (sender) + diff (receiver), and the on-disk cleanup + base-hash
* eviction when a tombstone is hard-pruned.
*
* Mirrors creativeDirector/local.js's federation re-exports + moodBoard/index.js,
* but keeps the announce hooks in local.js (the mutators live there). This module
* does NOT import peerSync — peerSync statically imports `mergeWorksFromSync`
* from here, so importing it back would close a load-order cycle.
*/
import { existsSync } from 'fs';
import { sha256File, rmGuarded } from '../../lib/fileUtils.js';
import { deleteSyncBaseHash, withBaseHashFlushBatch } from '../../lib/conflictJournal.js';
import { writersRoomStore } from './store.js';
import {
WRITERS_ROOM_WORK_KIND, WRITERS_ROOM_DRAFT_ASSET_KIND, draftAssetEntries,
WRITERS_ROOM_FOLDER_KIND, WRITERS_ROOM_EXERCISE_KIND,
} from './syncLogic.js';
import {
WORK_ID_RE, DRAFT_ID_RE, FOLDER_ID_RE, EXERCISE_ID_RE, wrWorkDir, wrDraftPath,
} from './_shared.js';
const store = () => writersRoomStore();
/** One work's manifest including a tombstone (for the LWW compare + the push). */
export async function getWorkForSync(id) {
return store().readWork(id, { includeDeleted: true });
}
/** Work ids — live only by default, or all (incl. tombstones) when asked. */
export async function listWorkIdsForSync(options = {}) {
return store().listWorkIds(options);
}
/**
* Live works as `{ id, updatedAt }` for the peer-sync backfill + full-sync
* coverage status. `updatedAt` is required by `getFullSyncCoverageForPeer` to
* detect a confirmed push gone stale — bare `{ id }` stubs would make every
* old confirmation look fresh and report a changed manuscript as fully mirrored.
*/
export async function listWorksForSync() {
const works = await store().listWorks();
return works
.filter((w) => w && typeof w.id === 'string')
.map((w) => ({ id: w.id, updatedAt: w.updatedAt }));
}
/** Merge an incoming batch of work records from a peer (LWW, tombstone-aware). */
export async function mergeWorksFromSync(remoteWorks, options = {}) {
return store().mergeWorksFromSync(remoteWorks, options);
}
/**
* Hard-remove tombstoned works older than the cutoff (called by tombstone GC).
* The backend drops the rows (PG) / identifies the dirs (file); this facade then
* rm's each work's on-disk dir (manifest + file-primary `.md` bodies) and evicts
* its conflict-journal base hash — uniform across both backends. Returns `{ pruned }`.
*/
export async function pruneTombstonedWorks(olderThanMs) {
const { pruned, ids } = await store().pruneTombstonedWorks(olderThanMs);
await withBaseHashFlushBatch(async () => {
for (const id of ids) {
if (typeof id !== 'string' || !WORK_ID_RE.test(id)) continue;
await rmGuarded(wrWorkDir(id), { recursive: true, force: true }).catch(() => {});
await deleteSyncBaseHash(WRITERS_ROOM_WORK_KIND, id);
}
});
return { pruned };
}
// ---------- folders + exercises (body-less records) ----------
//
// Folders + exercises federate as of #1645 (follow-up to #1565). Unlike works
// they have NO file-primary `.md` body — the whole record is the DB row's `data`
// JSONB (or the folders.json/exercises.json array on the file backend), so these
// facades are the works facades minus the draft-body manifest machinery. The
// only on-disk cleanup at prune time is the conflict-journal base hash (no work
// dir to rm).
// Shared prune facade for a body-less kind: the backend drops the rows/entries,
// then this evicts each pruned id's conflict-journal base hash (the only on-disk
// cleanup — no work dir to rm). `idRe` rejects a junk id before the eviction.
async function pruneTombstonedBodyless(storePruneFn, kind, idRe, olderThanMs) {
const { pruned, ids } = await storePruneFn(olderThanMs);
await withBaseHashFlushBatch(async () => {
for (const id of ids) {
if (typeof id !== 'string' || !idRe.test(id)) continue;
await deleteSyncBaseHash(kind, id);
}
});
return { pruned };
}
/** One folder including a tombstone (for the LWW compare + the push). */
export async function getFolderForSync(id) {
return store().readFolder(id, { includeDeleted: true });
}
/** Folder ids — live only by default, or all (incl. tombstones) when asked. */
export async function listFolderIdsForSync(options = {}) {
return store().listFolderIds(options);
}
/**
* Live folders as `{ id, updatedAt }` for the peer-sync backfill + full-sync
* coverage status (same `updatedAt`-bearing shape as works — a bare `{ id }`
* stub would report a renamed/moved folder as fully mirrored).
*/
export async function listFoldersForSync() {
const folders = await store().listFolders();
return folders
.filter((f) => f && typeof f.id === 'string')
.map((f) => ({ id: f.id, updatedAt: f.updatedAt }));
}
/** Merge an incoming batch of folder records from a peer (LWW, tombstone-aware). */
export async function mergeFoldersFromSync(remoteFolders, options = {}) {
return store().mergeFoldersFromSync(remoteFolders, options);
}
/**
* Hard-remove tombstoned folders older than the cutoff (called by tombstone GC).
* The backend drops the row/array entry; this facade evicts each folder's
* conflict-journal base hash. Returns `{ pruned }`.
*/
export async function pruneTombstonedFolders(olderThanMs) {
return pruneTombstonedBodyless((ms) => store().pruneTombstonedFolders(ms), WRITERS_ROOM_FOLDER_KIND, FOLDER_ID_RE, olderThanMs);
}
/** One exercise including a tombstone (for the LWW compare + the push). */
export async function getExerciseForSync(id) {
return store().readExercise(id, { includeDeleted: true });
}
/** Exercise ids — live only by default, or all (incl. tombstones) when asked. */
export async function listExerciseIdsForSync(options = {}) {
return store().listExerciseIds(options);
}
/**
* Live exercises as `{ id, updatedAt }` for the peer-sync backfill + coverage.
* Exercises carry no stored `updatedAt`; derive the LWW key the same way
* sanitizeExerciseForSync does (`finishedAt ?? startedAt`) so coverage compares
* the same value the wire merge keys on.
*/
export async function listExercisesForSync() {
const exercises = await store().listExercises();
return exercises
.filter((e) => e && typeof e.id === 'string')
.map((e) => ({ id: e.id, updatedAt: e.updatedAt ?? e.finishedAt ?? e.startedAt }));
}
/** Merge an incoming batch of exercise records from a peer (LWW, tombstone-aware). */
export async function mergeExercisesFromSync(remoteExercises, options = {}) {
return store().mergeExercisesFromSync(remoteExercises, options);
}
/** Hard-remove tombstoned exercises older than the cutoff (called by tombstone GC). */
export async function pruneTombstonedExercises(olderThanMs) {
return pruneTombstonedBodyless((ms) => store().pruneTombstonedExercises(ms), WRITERS_ROOM_EXERCISE_KIND, EXERCISE_ID_RE, olderThanMs);
}
/**
* Sender-side: hash each of a work's file-primary draft bodies so the receiver
* can pull the bytes from `/data/writers-room/works/<workId>/drafts/<draftId>.md`.
* A body with no readable file is skipped silently (can't ship bytes we don't
* have, mirroring hashImageForManifest). Tombstone callers pass `[]` upstream.
*/
export async function buildWorkBodyManifest(work) {
const entries = draftAssetEntries(work);
const out = [];
for (const { workId, draftId } of entries) {
const sha256 = await sha256File(wrDraftPath(workId, draftId)).catch(() => null);
if (sha256) out.push({ kind: WRITERS_ROOM_DRAFT_ASSET_KIND, workId, draftId, sha256 });
}
return out;
}
/**
* Receiver-side: given an incoming draft-body manifest, return the subset to
* pull. Validates every workId/draftId as a path segment before any FS op — a
* peer-supplied id is untrusted (same traversal posture as sanitizeAssetFilename
* in the generic asset pipeline). Echoes only the sanitized fields so junk can't
* round-trip.
*
* An ABSENT local body is always pulled — it can't overwrite anything, it fills
* a fresh insert, and it lets a previously-failed pull retry on the next push.
* A PRESENT-but-different local body is pulled ONLY when `includeMismatched`
* (the work-record merge actually accepted the remote, i.e. remote won/inserted).
* That gate is the data-safety boundary: when a STALE work push arrives after a
* local edit (local `updatedAt` wins the LWW merge so the metadata is kept), the
* sender's body hashes are the loser's — pulling them would clobber the newer
* local prose while leaving the newer local metadata in place. So a present
* body is only ever replaced when the receiver also took the remote's record.
*/
export async function diffWorkBodyManifest(manifest, { includeMismatched = false } = {}) {
if (!Array.isArray(manifest)) return [];
const missing = [];
for (const entry of manifest) {
if (!entry || typeof entry !== 'object') continue;
const { workId, draftId, sha256 } = entry;
if (typeof workId !== 'string' || !WORK_ID_RE.test(workId)) continue;
if (typeof draftId !== 'string' || !DRAFT_ID_RE.test(draftId)) continue;
if (typeof sha256 !== 'string' || !sha256) continue;
const sanitized = { kind: WRITERS_ROOM_DRAFT_ASSET_KIND, workId, draftId, sha256 };
const fullPath = wrDraftPath(workId, draftId);
if (!existsSync(fullPath)) {
missing.push(sanitized);
continue;
}
if (!includeMismatched) continue; // local body present + remote didn't win → keep local
const localHash = await sha256File(fullPath).catch(() => null);
if (localHash !== sha256) missing.push(sanitized);
}
return missing;
}