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
/**
* Chiptune score service (#2911) — LLM generation, offline render into the
* shared music library, and publish into a managed app's repo.
*
* generateChiptuneScore — prompt + any configured AI provider/model →
* validated score JSON persisted on the track (`chiptuneScore` +
* `chiptunePrompt`). User-triggered only (no cold-bootstrap LLM calls).
* renderChiptuneTrack — score → WAV (lib/chiptuneRender) → OGG via the
* system ffmpeg when available (WAV fallback otherwise), landed in the
* shared music library and appended to the track's render history.
* publishChiptuneTrack — render the CURRENT score straight into a managed
* app's repoPath (default `game/assets/music/`) as `<slug>.ogg` +
* `<slug>.score.json`, path-safety anchored to the app's repo. The game
* repo owns its own git — we only write files.
*/
import { mkdir, realpath, stat } from 'fs/promises';
import { join, resolve, isAbsolute } from 'path';
import { ServerError } from '../lib/errorHandler.js';
import { atomicWrite, isPathInsideDir } from '../lib/fileUtils.js';
import { isSymlinkFreeRepoPath } from '../lib/repoPublishPath.js';
import { writeWavAudioFile } from '../lib/wavAudioFile.js';
import { chiptuneScoreSchema, CHIPTUNE_LIMITS, CHIPTUNE_NOISE_PRESETS, scoreDurationSec } from '../lib/chiptuneScore.js';
import { renderScoreToWav } from '../lib/chiptuneRender.js';
import { resolveProviderAndModel, assertProvider, runPromptThroughProvider } from './promptRunner.js';
import * as tracks from './tracks/index.js';
import { publishMusicTake } from './musicTakePublication.js';
import { getAppById, PORTOS_APP_ID } from './apps.js';
export const DEFAULT_PUBLISH_SUBDIR = 'game/assets/music';
const requireTrack = async (trackId) => {
const track = await tracks.getTrack(trackId);
if (!track) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });
return track;
};
const requireScore = (track) => {
if (!track.chiptuneScore) {
throw new ServerError('This track has no chiptune score yet — generate one first', {
status: 400, code: 'CHIPTUNE_NO_SCORE',
});
}
return track.chiptuneScore;
};
/** The generation contract sent to the LLM. Exported for tests. */
export function buildChiptunePrompt({ prompt, currentScore }) {
const iterate = currentScore
? `\nCURRENT SCORE (revise this per the request above — keep what works, change what's asked):\n${JSON.stringify(currentScore)}\n`
: '';
return `You are a chiptune composer writing a seamlessly LOOPING 8-bit background-music score for a game.
MUSIC REQUEST: ${prompt}
${iterate}
Return ONLY a JSON object (no prose, no code fence) in exactly this shape:
{
"version": 1,
"title": "<short title>",
"bpm": <number ${CHIPTUNE_LIMITS.BPM_MIN}-${CHIPTUNE_LIMITS.BPM_MAX}>,
"stepsPerBeat": <int 1-${CHIPTUNE_LIMITS.STEPS_PER_BEAT_MAX}, 4 = sixteenth notes>,
"beatsPerBar": <int 1-${CHIPTUNE_LIMITS.BEATS_PER_BAR_MAX}, usually 4>,
"channels": [
{"id": "pulse1", "wave": "square", "duty": 0.5, "gain": 0.5},
{"id": "pulse2", "wave": "square", "duty": 0.25, "gain": 0.4},
{"id": "triangle", "wave": "triangle", "gain": 0.55},
{"id": "noise", "wave": "noise", "gain": 0.35}
],
"patterns": {
"A": {"bars": <int 1-${CHIPTUNE_LIMITS.BARS_PER_PATTERN_MAX}>, "notes": {
"pulse1": [{"step": 0, "pitch": "C5", "len": 2, "vel": 0.8}, ...],
"noise": [{"step": 0, "pitch": "kick", "len": 1}, ...]
}}
},
"order": ["A", "A", "B", "A"]
}
Rules:
- pulse1 carries melody, pulse2 harmony/counter-melody, triangle the bassline, noise the drums.
- Tonal pitches are scientific notation ("C5", "F#3", "Bb2"). Noise pitches are ONLY: ${CHIPTUNE_NOISE_PRESETS.join(', ')}.
- "step" is the note's onset within its pattern (0-indexed, stepsPerBeat × beatsPerBar × bars steps per pattern); "len" is its length in steps. Notes must fit inside their pattern.
- 1-${CHIPTUNE_LIMITS.PATTERNS_MAX} patterns, order length 1-${CHIPTUNE_LIMITS.ORDER_MAX}, total loop under ${CHIPTUNE_LIMITS.MAX_LOOP_SEC}s. Aim for a 15-40 second loop that ends back where it starts musically (the playback loops the whole order seamlessly).
- Write real music: a memorable melody, movement in the bass, drums that groove. Vary velocity for feel.`;
}
/**
* Generate (or iterate on) a track's chiptune score with the chosen provider.
* When the track already has a score and `fresh` is not set, the current score
* is included so the LLM revises rather than starting over.
*/
export async function generateChiptuneScore({ trackId, prompt, providerId, model, fresh = false }) {
const track = await requireTrack(trackId);
const { provider, selectedModel } = await resolveProviderAndModel({ providerId, model });
assertProvider(provider, {
message: 'No AI provider available for chiptune generation',
code: 'CHIPTUNE_NO_PROVIDER',
});
const currentScore = fresh ? null : track.chiptuneScore;
const run = await runPromptThroughProvider({
provider,
prompt: buildChiptunePrompt({ prompt, currentScore }),
source: 'chiptune-score',
model: selectedModel ?? undefined,
responseSchema: chiptuneScoreSchema,
});
// The runner validated/coerced the response against the schema; a failure
// here means the runner contract broke — surface it rather than persisting.
const parsed = chiptuneScoreSchema.safeParse(JSON.parse(run.text));
if (!parsed.success) {
throw new ServerError('Chiptune response failed schema validation after runner coercion', {
status: 502, code: 'CHIPTUNE_BAD_RESPONSE',
});
}
const updated = await tracks.updateTrack(trackId, { chiptuneScore: parsed.data, chiptunePrompt: prompt });
return { track: updated, providerId: run.provider?.id || provider.id, model: run.model ?? selectedModel ?? null };
}
const renderScoreToFile = (score, dir, basename) => writeWavAudioFile(renderScoreToWav(score), dir, basename);
/**
* Render the track's current score into the shared music library and append
* it to the render history (same contract as the diffusion generate route).
*/
export async function renderChiptuneTrack({ trackId }) {
const track = await requireTrack(trackId);
const score = requireScore(track);
const wav = renderScoreToWav(score);
const durationSec = Math.max(1, Math.round(scoreDurationSec(score)));
const { track: updated, filename } = await publishMusicTake({
trackId, wav, take: { prompt: track.chiptunePrompt, engine: 'chiptune', durationSec },
});
return { track: updated, filename, durationSec };
}
const SLUG_RE = /[^a-z0-9-]+/g;
const slugify = (s) => String(s || '').toLowerCase().trim().replace(SLUG_RE, '-').replace(/^-+|-+$/g, '').slice(0, 64);
const badSubdir = (message) => new ServerError(message, { status: 400, code: 'CHIPTUNE_BAD_SUBDIR' });
// A publish subdir must stay inside the app repo: relative, no traversal, no
// backslashes (Windows-style separators would dodge the segment check).
function assertSafeSubdir(subdir) {
if (isAbsolute(subdir) || subdir.includes('\\') || subdir.includes('\0') || subdir.split('/').some((seg) => seg === '..')) {
throw badSubdir('Publish subdir must be a relative path inside the app repo');
}
}
/**
* Render the track's current score directly into a managed app's repo:
* `<repoPath>/<subdir>/<slug>.ogg` + `<slug>.score.json` (the editable source
* travels with the audio). Path-safety anchored to the app's repoPath.
*/
export async function publishChiptuneTrack({ trackId, appId, subdir, slug }) {
const track = await requireTrack(trackId);
const score = requireScore(track);
const app = await getAppById(appId);
if (!app || !app.repoPath) {
throw new ServerError('Managed app not found (or it has no repo path)', { status: 404, code: 'CHIPTUNE_APP_NOT_FOUND' });
}
// Enforce the publishable-target policy server-side (the panel's app filter
// is just a mirror of this rule): never write generated assets into PortOS's
// own working tree, and archived apps aren't valid destinations.
if (app.id === PORTOS_APP_ID || app.archived) {
throw new ServerError('That app is not a publishable target', { status: 400, code: 'CHIPTUNE_APP_NOT_PUBLISHABLE' });
}
const repoStat = await stat(app.repoPath).catch(() => null);
if (!repoStat?.isDirectory()) {
throw new ServerError(`App repo path does not exist: ${app.repoPath}`, { status: 400, code: 'CHIPTUNE_APP_REPO_MISSING' });
}
// Anchor on the REAL root: a lexical check cannot see a directory symlink
// inside the checkout that points elsewhere (#10894).
const repoRoot = await realpath(app.repoPath);
// Validate the RAW subdir before any normalization — stripping a leading
// slash first would launder an absolute path into a relative-looking one.
const rawSubdir = subdir || DEFAULT_PUBLISH_SUBDIR;
assertSafeSubdir(rawSubdir);
const cleanSubdir = rawSubdir.replace(/\/+$/g, '');
const targetDir = resolve(repoRoot, cleanSubdir);
if (targetDir !== repoRoot && !isPathInsideDir(repoRoot, targetDir)) {
throw badSubdir('Publish target escapes the app repo');
}
const name = slugify(slug) || slugify(track.title) || 'track';
const scoreFilename = `${name}.score.json`;
// Preflight EVERY destination (WAV fallback, OGG, score sidecar) before the
// first mutation so a bad one can't leave a partial publish behind.
const assertDestinationsContained = async () => {
const targetOk = await isSymlinkFreeRepoPath(repoRoot, targetDir, { leaf: 'dir' });
const leavesOk = targetOk && (await Promise.all(
[`${name}.wav`, `${name}.ogg`, scoreFilename].map((f) => isSymlinkFreeRepoPath(repoRoot, join(targetDir, f), { leaf: 'file' })),
)).every(Boolean);
if (!leavesOk) throw badSubdir('Publish target must stay inside the app repo without symlinks');
};
await assertDestinationsContained();
// Create the directory ourselves and re-check the completed parent, so a
// link planted after the preflight (or created mid-path) is still caught.
await mkdir(targetDir, { recursive: true });
await assertDestinationsContained();
const audioFilename = await renderScoreToFile(score, targetDir, name);
await atomicWrite(join(targetDir, scoreFilename), `${JSON.stringify(score, null, 2)}\n`);
const rel = (f) => (cleanSubdir ? `${cleanSubdir}/${f}` : f);
const isOgg = audioFilename.endsWith('.ogg');
console.log(`🎮 Published chiptune "${name}" to app ${app.name} (${rel(audioFilename)})`);
return {
appId: app.id,
appName: app.name,
files: [rel(audioFilename), rel(scoreFilename)],
format: isOgg ? 'ogg' : 'wav',
note: isOgg
? 'Godot auto-imports the OGG; enable "Loop" in its import settings for seamless background playback.'
: 'ffmpeg was not found, so the loop was published as WAV. Install ffmpeg for OGG output.',
};
}