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
/**
* Brain SongBook Routes
*
* Repertoire tracker (guitar tabs / chord sheets / sheet music) stored as the
* Brain entity type `songs` — all writes go through brainStorage's generic API
* so records ride the sync-log / LWW / tombstone federation pipeline.
*
* Mounted from the brain barrel at /songbook → /api/brain/songbook/...
*
* Practice: `POST /:id/practice` logs a graded run and moves the song's SM-2
* schedule (`practice`) plus its learning `stage`. Both `practice` and
* `attachments` are server-managed — the write schemas have no key for them, so
* Zod's unknown-key stripping drops a client-supplied value.
*
* Attachments: METADATA lives in the synced record (identical on all peers);
* BYTES are machine-local under data/brain/songbook/ (<uuid8>-<sanitized-name>).
* The list endpoint reports `present: boolean` per attachment so peers lacking
* the file can render "not on this machine".
*/
import { Router } from 'express';
import { join, resolve } from 'path';
import { createHash } from 'crypto';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { validateRequest } from '../lib/validation.js';
import {
songInputSchema,
songUpdateSchema,
songImportUrlSchema,
songPracticeInputSchema,
songAttachmentUploadSchema,
} from '../lib/brainValidation.js';
import { applySongPractice } from '../lib/songPractice.js';
import * as brainStorage from '../services/brainStorage.js';
import { importSongFromUrl } from '../services/brainSongbookImport.js';
import { MAX_BASE64_UPLOAD_BYTES } from '../lib/uploadLimits.js';
import { withBackupAssetPublication } from '../lib/backupSnapshotBoundary.js';
import {
pathExists, PATHS, sanitizeFilename, isPathInsideDir,
SONGBOOK_ATTACHMENT_EXTENSIONS, saveBase64Upload, serveLocalFile,
unlinkGuarded,
} from '../lib/fileUtils.js';
const router = Router();
// Bounded by the JSON body limit, not by any songbook-specific rule — see
// lib/uploadLimits.js.
const MAX_ATTACHMENT_SIZE = MAX_BASE64_UPLOAD_BYTES;
// Read lazily (not captured at module load) so test PATHS mocks with
// per-suite temp roots resolve correctly.
const songbookDir = () => PATHS.brainSongbook;
// 404 unless the storage layer returned a record (or a truthy delete result).
function requireSong(song) {
if (!song) {
throw new ServerError('Song not found', { status: 404, code: 'NOT_FOUND' });
}
return song;
}
async function getSongOr404(id) {
return requireSong(await brainStorage.getById('songs', id));
}
// Locate an attachment's meta on a song + its vetted local filepath. Throws
// 400 on a traversal-shaped filename and 404 when the meta isn't on the record.
function resolveAttachment(song, rawFilename) {
const safeFilename = sanitizeFilename(rawFilename);
const filepath = resolve(songbookDir(), safeFilename);
if (!isPathInsideDir(songbookDir(), filepath)) {
throw new ServerError('Invalid filename', { status: 400, code: 'INVALID_FILENAME' });
}
const meta = (Array.isArray(song.attachments) ? song.attachments : [])
.find((a) => a.filename === safeFilename);
if (!meta) {
throw new ServerError('Attachment not found', { status: 404, code: 'NOT_FOUND' });
}
return { meta, safeFilename, filepath };
}
// =============================================================================
// IMPORT (before /:id routes so 'import' is never treated as an id)
// =============================================================================
// POST /import/url — fetch + extract a draft; nothing is stored.
router.post('/import/url', asyncHandler(async (req, res) => {
const { url } = validateRequest(songImportUrlSchema, req.body);
const draft = await importSongFromUrl(url);
res.json({ draft });
}));
// =============================================================================
// SONG CRUD
// =============================================================================
router.get('/', asyncHandler(async (req, res) => {
// Index projection: the list view needs metadata only, and content.text can
// be 200k chars per song — a large repertoire would ship megabytes nobody
// reads. The full record (with text) comes from GET /:id.
const songs = (await brainStorage.getAll('songs')).map(({ content, ...rest }) => ({
...rest,
content: { format: content?.format || 'tab' },
}));
res.json({ songs });
}));
router.get('/:id', asyncHandler(async (req, res) => {
const song = await getSongOr404(req.params.id);
res.json(song);
}));
router.post('/', asyncHandler(async (req, res) => {
const data = validateRequest(songInputSchema, req.body);
// `attachments` is server-managed — always born empty, mutated only by the
// attachment endpoints below.
const song = await brainStorage.create('songs', { ...data, attachments: [] });
res.status(201).json(song);
}));
router.patch('/:id', asyncHandler(async (req, res) => {
// songUpdateSchema is defaults-free down to the nested `content` object, so
// an omitted field (or omitted content.format/text) is genuinely absent
// instead of resetting to its default (see brainValidation.js / zodCompat.js).
// The schema has no `attachments` key, so Zod's unknown-key stripping drops
// any client-supplied attachments — the record's server-managed list survives.
// A partial `content` deep-merges over the stored song's content inside the
// store write lock (updateWith), so `{ content: { text } }` keeps the stored
// format and `{ content: { format } }` keeps the stored text.
const data = validateRequest(songUpdateSchema, req.body);
const song = requireSong(await brainStorage.updateWith('songs', req.params.id, (fresh) => (
data.content ? { ...data, content: { ...fresh.content, ...data.content } } : data
)));
res.json(song);
}));
router.delete('/:id', asyncHandler(async (req, res) => {
// Tombstone delete (brainStorage.remove) so the deletion federates. Local
// attachment bytes are left in place — peers may still hold the meta, and
// orphaned bytes are harmless machine-local files.
requireSong(await brainStorage.remove('songs', req.params.id));
res.json({ id: req.params.id });
}));
// =============================================================================
// PRACTICE (spaced repetition)
// =============================================================================
// POST /:id/practice — log one practice run, graded 0..5. Advances the song's
// SM-2 schedule and its learning stage (see lib/songPractice.js).
//
// This earns its own endpoint rather than riding the generic PATCH because an
// SM-2 advance is computed FROM the stored schedule: the work happens inside
// `updateWith`'s locked read-modify-write, against the freshest record, so a
// concurrent edit or a peer-sync apply can't be clobbered — and the scheduler
// stays on the server instead of in the browser.
router.post('/:id/practice', asyncHandler(async (req, res) => {
const { quality } = validateRequest(songPracticeInputSchema, req.body);
const song = requireSong(await brainStorage.updateWith('songs', req.params.id,
(fresh) => applySongPractice(fresh, quality)));
console.log(`🎸 Practice logged: "${song.title}" quality=${quality} → ${song.stage}, next review in ${song.practice.intervalDays}d`);
res.json(song);
}));
// =============================================================================
// ATTACHMENTS
// =============================================================================
// Song records and their attachment bytes are both files under data/brain, so
// one backup rsync pass copies them at different moments. Each attachment
// mutation holds the backup lease (#9982) from its first byte change through
// the record write, so a snapshot never pairs a record with bytes from the
// other side of that change.
// POST /:id/attachments — base64 upload; writes bytes + appends meta to record
router.post('/:id/attachments', asyncHandler(async (req, res) => {
const song = await getSongOr404(req.params.id);
const { filename, data, label } = validateRequest(songAttachmentUploadSchema, req.body);
const { saved, attachment } = await withBackupAssetPublication(() => saveSongAttachment(song.id, { filename, data, label }));
console.log(`🎸 Song attachment saved: ${saved.filename} (${saved.size} bytes)`);
res.status(201).json({ attachment });
}));
async function saveSongAttachment(songId, { filename, data, label }) {
const saved = await saveBase64Upload(songbookDir(), { filename, data }, {
allowedExtensions: SONGBOOK_ATTACHMENT_EXTENSIONS,
maxBytes: MAX_ATTACHMENT_SIZE,
});
const attachment = {
filename: saved.filename,
label,
mime: saved.mime,
size: saved.size,
sha256: createHash('sha256').update(saved.buffer).digest('hex'),
};
// Append against the FRESH record inside the store write lock (updateWith) —
// a concurrent upload/delete or a peer-sync apply landing between the read
// above and this write would otherwise be clobbered (and win LWW). requireSong
// 404s the mid-request tombstone race instead of 201-ing meta never persisted.
requireSong(await brainStorage.updateWith('songs', songId, (fresh) => ({
attachments: [...(Array.isArray(fresh.attachments) ? fresh.attachments : []), attachment],
})));
return { saved, attachment };
}
// GET /:id/attachments — synced meta + machine-local presence
router.get('/:id/attachments', asyncHandler(async (req, res) => {
const song = await getSongOr404(req.params.id);
const metas = Array.isArray(song.attachments) ? song.attachments : [];
const attachments = await Promise.all(metas.map(async (meta) => ({
...meta,
present: await pathExists(join(songbookDir(), meta.filename)),
})));
res.json(attachments);
}));
// GET /:id/attachments/:filename — serve the local bytes. resolveAttachment
// runs first so a filename not on the record 404s even when a file exists;
// the shared server then handles the meta-synced-but-bytes-absent case.
router.get('/:id/attachments/:filename', asyncHandler(async (req, res) => {
const song = await getSongOr404(req.params.id);
resolveAttachment(song, req.params.filename);
await serveLocalFile(res, songbookDir(), req.params.filename, {
missingError: { message: 'Attachment file is not on this machine', code: 'NOT_ON_THIS_MACHINE' },
});
}));
// DELETE /:id/attachments/:filename — remove meta from record + local bytes
router.delete('/:id/attachments/:filename', asyncHandler(async (req, res) => {
const song = await getSongOr404(req.params.id);
const { safeFilename, filepath } = resolveAttachment(song, req.params.filename);
// Filter against the FRESH record inside the store write lock (updateWith) so
// a concurrent upload/peer-sync apply isn't clobbered; requireSong 404s the
// mid-request tombstone race instead of TypeError-ing on a null record.
const updated = await withBackupAssetPublication(async () => {
const next = requireSong(await brainStorage.updateWith('songs', song.id, (fresh) => ({
attachments: (Array.isArray(fresh.attachments) ? fresh.attachments : [])
.filter((a) => a.filename !== safeFilename),
})));
// Bytes may legitimately be absent on this machine (meta synced from a peer).
if (await pathExists(filepath)) {
await unlinkGuarded(filepath);
}
return next;
});
console.log(`🗑️ Song attachment deleted: ${safeFilename}`);
res.json({ success: true, filename: safeFilename, attachments: updated.attachments });
}));
export default router;