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
import { shotActionPrompt } from '../../lib/musicVideoActionContract.js';
import { shotCameraPrompt } from '../../lib/cameraMovements.js';
import { musicVideoCreativeContext, musicVideoDirectorLook } from '../../lib/musicVideoCreativeContext.js';
import { MOTION_CONTINUITY_CLAUSE } from '../../lib/musicVideoMotion.js';
import { isOutsideMusicVideoReference } from '../../lib/musicVideoConditioning.js';
import { musicVideoFrameModelInput, visualDirection } from '../../lib/musicVideoShotPrompt.js';
/**
* Music Video external-asset handoff (#8965) — provider-neutral export/import
* for tools PortOS does not drive, such as Midjourney.
*
* PortOS never automates the external tool (Midjourney's guidelines prohibit
* unauthorized automation and it has no general public API): the director
* exports a manifest of per-scene prompts and reference files, generates by
* hand, then imports the downloaded files through the ordinary gallery upload
* routes. Scene association survives the round trip through a FILE TAG
* (`S03-1a2b3c4d`) the manifest assigns each scene: a downloaded file whose
* name carries the tag is matched back to its exact scene by the scene id the
* tag encodes — the `S03` order prefix is cosmetic, so reordering the board
* between export and import can't misfile an asset.
*
* The manifest is built from an explicit field allowlist, so machine-local
* render pins, renderer settings and server paths never leave the install.
*/
import { readFile } from 'fs/promises';
import { resolveGalleryImage } from '../../lib/pathSafety.js';
import { createZip } from '../../lib/zipWriter.js';
export const HANDOFF_FORMAT = 'portos.music-video.handoff';
export const HANDOFF_VERSION = 1;
const sceneShortId = (sceneId) => String(sceneId || '')
.replace(/^mvs-/, '')
.replace(/[^a-z0-9]/gi, '')
.slice(0, 8)
.toLowerCase();
/** The tag a scene's externally generated files carry in their filename. */
function sceneFileTag(scene, index) {
return `S${String(index + 1).padStart(2, '0')}-${sceneShortId(scene.sceneId)}`;
}
// Up to eight id characters: a normal `mvs-<uuid>` scene yields exactly eight,
// but a short hand-authored id yields fewer and must still round-trip.
const FILE_TAG_RE = /(?:^|[^a-z0-9])s\d{1,3}[-_]([a-z0-9]{1,8})(?![a-z0-9])/gi;
/**
* Resolve an imported file's original name to the scene whose tag it carries.
* Returns null when the name carries no tag, a tag no scene owns, or tags for
* two different scenes — an ambiguous file is never guessed onto a scene.
*/
export function matchSceneByFileTag(scenes, originalName) {
if (typeof originalName !== 'string' || !originalName) return null;
const byShort = new Map();
for (const scene of scenes || []) {
const short = sceneShortId(scene.sceneId);
// Two scenes sharing a short id make that tag ambiguous for both.
byShort.set(short, byShort.has(short) ? null : scene.sceneId);
}
const matched = new Set();
for (const [, short] of originalName.matchAll(FILE_TAG_RE)) {
const sceneId = byShort.get(short.toLowerCase());
if (sceneId) matched.add(sceneId);
}
return matched.size === 1 ? [...matched][0] : null;
}
/** The project-wide palette and camera rules (shared with the board and the video submit). */
export { visualDirection };
// `clause` is the scene's applied treatment direction (#8980) — the composition
// constraints for a frame or a motion prompt. Same order as the client's
// buildFramePrompt/buildShotPrompt.
// A motion prompt (`motion: true`) omits the mood-board look (the i2v model
// starts from the reference frame, which already carries it) and pins the
// frame's lighting for the length of the take.
function composePrompt(primary, fallback, project, clause, { motion = false } = {}) {
return [
primary?.trim() || fallback?.trim() || '',
project.concept?.style?.trim() || '',
musicVideoCreativeContext(project.concept, { moodBoard: !motion, look: musicVideoDirectorLook(project) }),
visualDirection(project.visualSpec),
clause?.trim() || '',
motion ? MOTION_CONTINUITY_CLAUSE : '',
].filter(Boolean).join(', ');
}
/**
* The authored frame prompt inside a still's rendered prompt: its first line,
* cut where the project-wide look (concept style, mood-board context, visual
* spec) was appended and before an end frame's keep-the-reference clause, so a
* still swapped onto another shot shows the prompt it was made from without
* the look being appended twice on the next render. Null for a refine edit
* (its text is an instruction, not a frame) or an empty prompt.
*/
export function authoredFramePrompt(project, prompt) {
const line = typeof prompt === 'string' ? prompt.split('\n')[0].trim() : '';
if (!line || line.startsWith('Edit the reference image:')) return null;
const look = [
project?.concept?.style?.trim(),
musicVideoCreativeContext(project?.concept, { look: musicVideoDirectorLook(project) }),
visualDirection(project?.visualSpec),
].filter(Boolean);
const cuts = [...look.map((piece) => line.indexOf(`, ${piece}`)), line.indexOf('. Keep the reference image\'s composition')].filter((at) => at > 0);
const authored = (cuts.length ? line.slice(0, Math.min(...cuts)) : line).trim();
return authored || null;
}
/** A scene's composed reference-frame prompt (also the server-owned production run's, #9066). */
export const sceneFramePrompt = (project, scene) => musicVideoFrameModelInput(project, scene).prompt;
/**
* A scene's composed shot (motion) prompt. A planned shot (#10589) carries its
* camera as the four-part Movement / Speed / Framing / End block, kept apart
* from the scene description so the i2v model reads it as its own instruction.
*/
export const sceneShotPrompt = (project, scene, options = {}) => [composePrompt(scene.prompt, scene.framePrompt, project, scene.direction?.motionClause, { motion: true }), shotCameraPrompt(scene.camera), shotActionPrompt(project, scene, options)].filter(Boolean).join('\n');
/** Build the export manifest for a project. */
export function buildHandoffManifest(project, { now = new Date().toISOString() } = {}) {
const spec = project.visualSpec || null;
const references = (spec?.references || []).map((ref) => ({
id: ref.id,
role: ref.role,
label: ref.label,
note: ref.note,
// Outside (mood board / Pinterest) images never condition generation.
condition: ref.condition === true && !isOutsideMusicVideoReference(ref),
use: ref.use || 'reference',
filename: ref.imageId,
url: `/data/images/${encodeURIComponent(ref.imageId)}`,
}));
const conditioning = references.filter((ref) => ref.condition).map((ref) => ref.filename);
return {
format: HANDOFF_FORMAT,
version: HANDOFF_VERSION,
exportedAt: now,
project: { id: project.id, name: project.name, version: project.version || 1 },
instructions: 'Generate each scene in your external tool, keep the scene file tag (for example S03-1a2b3c4d) in every downloaded filename, then import the files on the Music Video board. PortOS never contacts the external service; attach the reference files yourself.',
concept: { prompt: project.concept?.prompt || '', style: project.concept?.style || '', universeStyle: project.concept?.universeStyle || '', moodBoardStyle: project.concept?.moodBoardStyle || '', characterStyle: project.concept?.characterStyle || '', subjects: project.concept?.subjects || [] },
visualSpec: {
palette: spec?.palette || [],
typography: spec?.typography || '',
cameraRules: spec?.cameraRules || '',
references,
},
scenes: (project.scenes || []).map((scene, index) => ({
sceneId: scene.sceneId,
order: index,
fileTag: sceneFileTag(scene, index),
label: scene.sectionLabel || scene.label || `Scene ${index + 1}`,
startSec: scene.startSec ?? null,
endSec: scene.endSec ?? null,
lyricText: scene.lyricText || '',
visualIntent: scene.visualIntent || '',
framePrompt: sceneFramePrompt(project, scene),
shotPrompt: sceneShotPrompt(project, scene),
referenceFiles: conditioning,
selected: {
referenceImageId: scene.referenceImageId || null,
videoHistoryId: scene.videoHistoryId || null,
},
})),
};
}
/**
* Build the downloadable ZIP counterpart of `buildHandoffManifest` (#8978):
* the same JSON manifest (with a `missing` list appended) plus the visual
* spec's reference images and each scene's currently-selected reference
* frame — so the director doesn't have to save every reference out of the
* gallery by hand before attaching it in the external tool. A reference or
* frame this install can't resolve on disk (deleted out from under the
* record) is reported in `missing` rather than failing the whole download.
*
* Returns `{ manifest, zip }` — `manifest` is the JSON actually written into
* the archive (so a caller/test can inspect `missing` without re-parsing the
* zip), `zip` is the archive Buffer.
*/
export async function buildHandoffBundle(project) {
const manifest = buildHandoffManifest(project);
const files = [];
const missing = [];
const seen = new Set();
const addImage = async (filename, archivePath) => {
if (!filename || seen.has(archivePath)) return;
seen.add(archivePath);
const resolved = resolveGalleryImage(filename);
if (!resolved) { missing.push({ filename, path: archivePath }); return; }
try {
files.push({ name: archivePath, data: await readFile(resolved) });
} catch {
missing.push({ filename, path: archivePath });
}
};
for (const ref of manifest.visualSpec.references) {
await addImage(ref.filename, `references/${ref.filename}`);
}
for (const scene of manifest.scenes) {
const frame = scene.selected?.referenceImageId;
if (frame) await addImage(frame, `scenes/${scene.fileTag}-${frame}`);
}
const bundleManifest = { ...manifest, missing };
const zip = createZip([
{ name: 'manifest.json', data: JSON.stringify(bundleManifest, null, 2) },
...files,
]);
return { manifest: bundleManifest, zip };
}