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
/**
* Background-music library for the pipeline audio stage.
*
* Storage model: a single shared directory at `PATHS.music`. Every track —
* uploaded today, locally generated tomorrow — lives here under a deterministic
* basename. The library list is just `readdir + stat` filtered to known audio
* extensions. No JSON index — the filesystem is the source of truth, which
* keeps the library robust across server restarts and direct file drops.
*
* Provider strategy mirrors `audio.js`: **local-first**. User-upload is the
* always-available path (zero infra). Local MusicGen via a Python sidecar
* (4c.2 follow-up) and a 3rd-party Suno stub (4c.3) plug in as sibling
* sources behind the same library list — the AudioStage picker doesn't
* care which one wrote the bytes.
*/
import { stat } from 'fs/promises';
import { existsSync } from 'fs';
import { join, basename, extname } from 'path';
import { randomUUID } from 'crypto';
import {
PATHS,
ensureDir,
assertSafeFilename,
isSafeFilename,
listDirectoryByExtension,
copyFileGuarded,
unlinkGuarded,
assertFileNotMediaManifest,
} from '../../lib/fileUtils.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
// Mirror of the sanitizer's MUSIC_SOURCES set in `services/pipeline/issues.js`.
// Exported so routes don't sprinkle bare strings; `'gen'` is reserved for the
// next sub-phase (local MusicGen sidecar / 3rd-party Suno stub).
export const MUSIC_SOURCE = Object.freeze({
UPLOAD: 'upload',
LIBRARY: 'library',
GEN: 'gen',
});
export const SUPPORTED_AUDIO_EXTENSIONS = Object.freeze(['.mp3', '.wav', '.m4a', '.ogg', '.flac']);
export const SUPPORTED_AUDIO_MIME = Object.freeze({
'.mp3': 'audio/mpeg',
'.wav': 'audio/wav',
'.m4a': 'audio/mp4',
'.ogg': 'audio/ogg',
'.flac': 'audio/flac',
});
export const MUSIC_UPLOAD_MAX_BYTES = 50 * 1024 * 1024;
// Returns true if the MIME or filename extension marks this as one of our
// supported audio formats. Used by the multipart fileFilter — matching either
// signal handles browsers that report `application/octet-stream` for drag-
// drop uploads while still requiring a known extension.
export function isSupportedMusicUpload(file) {
if (!file) return false;
const ext = (extname(file.originalname || '') || '').toLowerCase();
if (!SUPPORTED_AUDIO_EXTENSIONS.includes(ext)) return false;
const mime = (file.mimetype || '').toLowerCase();
if (mime.startsWith('audio/')) return true;
if (mime === 'application/octet-stream') return true;
if (mime === 'video/mp4' && ext === '.m4a') return true; // some browsers
return false;
}
/**
* Validate a stored music filename — same pattern as the rest of the codebase.
* Rejects path traversal, separators, and disallowed extensions.
*/
export function assertSafeMusicFilename(filename) {
assertSafeFilename(filename, {
extensions: [...SUPPORTED_AUDIO_EXTENSIONS],
subject: 'music filename',
});
}
/**
* The same rule as a predicate, for read-only callers that must treat a bad
* stored filename as data. `sanitizeTrack` only `trimTo`s the top-level
* `audioFilename` (unlike `renders[]`, which goes through
* `trackAudioFilename`), so a legacy or peer-synced track can carry an
* unsupported name — a preflight has to report that as one blocked asset, not
* 400 the whole sweep via `assertSafeMusicFilename`.
*/
export const isSafeMusicFilename = (filename) =>
isSafeFilename(filename, SUPPORTED_AUDIO_EXTENSIONS);
/**
* Generate a fresh deterministic basename for a newly-uploaded track. Keeps
* the original extension so the static handler picks the right Content-Type.
*/
export function buildStoredFilename(originalName) {
const ext = (extname(originalName || '') || '.mp3').toLowerCase();
const safeExt = SUPPORTED_AUDIO_EXTENSIONS.includes(ext) ? ext : '.mp3';
return `music-${randomUUID()}${safeExt}`;
}
/**
* Strip the extension off a stored filename to produce a default label for
* the library picker when the caller didn't pass one explicitly.
*/
export function deriveDefaultLabel(originalName) {
const name = basename(originalName || '');
const ext = extname(name);
return ext ? name.slice(0, -ext.length) : name;
}
/**
* List every track currently sitting in the library. Each entry carries the
* stored filename (what the audio stage persists on `music.trackFilename`),
* file size, and last-modified timestamp so the picker can show "added X
* minutes ago" without a separate metadata store.
*
* Missing directory → empty list (no surprise 500 on a fresh install).
*/
export async function listMusicLibrary() {
await ensureDir(PATHS.music);
// listDirectoryByExtension covers readdir + ENOENT → [] + extension filter
// + stat + isFile drop. ensureDir runs first, so ENOENT shouldn't trip
// anyway — but the helper preserves the original safety net.
const entries = await listDirectoryByExtension(PATHS.music, {
extensions: [...SUPPORTED_AUDIO_EXTENSIONS],
mapEntry: (name, _full, s) => ({
filename: name,
label: deriveDefaultLabel(name),
sizeBytes: s.size,
updatedAt: s.mtime.toISOString(),
}),
});
return entries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
}
/**
* Move an uploaded temp file into the library and return the persisted
* filename. Caller (the route) reads `req.file.path` from the multipart
* helper. Returns `{ filename, sizeBytes }`. The upload filter checks only the
* name and declared type, so the bytes are checked here before ffmpeg can
* probe or render the stored file; a refused temp file is removed.
*/
export async function importUploadedTrack(tempPath, originalName) {
await assertFileNotMediaManifest(tempPath).catch(async (err) => {
await unlinkGuarded(tempPath).catch(() => {});
throw err;
});
const filename = buildStoredFilename(originalName);
const dest = join(PATHS.music, filename);
// The copy is the whole publication: a snapshot copying the library while it
// runs would capture a truncated file under its final name (#9982). The temp
// file lives outside `data/`, so its cleanup stays outside the lease.
const sizeBytes = await withBackupAssetPublication(async () => {
await ensureDir(PATHS.music);
// copyFile + unlink instead of rename — the multipart helper writes to
// os.tmpdir(), which may sit on a different filesystem (rename across
// devices throws EXDEV on Linux). Copy works regardless.
await copyFileGuarded(tempPath, dest);
const s = await stat(dest).catch(() => null);
return s?.size ?? 0;
});
await unlinkGuarded(tempPath).catch(() => {});
return { filename, sizeBytes };
}
/**
* Confirm a track exists in the library. Returns the same shape as a list
* entry (`{ filename, label, sizeBytes }`) or `null` if missing. Validates
* the filename to prevent path-traversal.
*/
export async function statMusicTrack(filename) {
assertSafeMusicFilename(filename);
const full = join(PATHS.music, filename);
if (!existsSync(full)) return null;
const s = await stat(full).catch(() => null);
if (!s || !s.isFile()) return null;
return {
filename,
label: deriveDefaultLabel(filename),
sizeBytes: s.size,
};
}
/**
* Delete a track from the library by stored filename. Returns true if the
* file existed and was removed; false if it was already gone. Validates the
* filename so a path-traversal attempt can't escape `PATHS.music`.
*
* Issues and projects keep naming the removed file on purpose (see the route),
* so a snapshot copied before the unlink and dumped after it would carry rows
* naming bytes it never captured. Holding the lease makes the unlink wait out
* an open cut and a cut wait out an unlink in flight (#9982).
*/
export async function deleteMusicTrack(filename) {
assertSafeMusicFilename(filename);
const full = join(PATHS.music, filename);
return withBackupAssetPublication(async () => {
try {
await unlinkGuarded(full);
return true;
} catch (err) {
if (err.code === 'ENOENT') return false;
throw err;
}
});
}