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 { z } from 'zod';
import { GENERATION_METADATA_LIMITS } from './pngMetadata.js';
import { isValidKey, parseKey } from './mediaItemKey.js';
import { MAX_IMAGE_EDGE, MAX_IMAGE_PIXELS } from './imageLimits.js';
import { QUEUEABLE_IMAGE_MODES } from './generationModes.js';
// =============================================================================
// MOOD BOARD SCHEMAS (issue #911)
// =============================================================================
// A mood board collects visual + textual references that feed the Create suite.
// Boards are db-primary, local-only records; items live inline in the board's
// JSONB. validation.js re-exports everything here so deep imports keep working.
export const MOOD_BOARD_ITEM_TYPES = Object.freeze(['image', 'text', 'video']);
// A media-key references an indexed asset as `<kind>:<ref>` (e.g.
// `image:my-render.png`, `video:job-123`). Reuse the shared key validator from
// mediaItemKey.js (the same vocabulary mediaCollections / mediaAnnotations use)
// so a board can't pin a key the rest of PortOS would reject.
const mediaKeySchema = z.string().trim().refine(isValidKey, 'mediaKey must be a valid `<kind>:<ref>` media key');
// A `type:'video'` board item's mediaKey ref is the on-disk FILENAME
// (extension included), not a bare history id: playback resolves it as
// `/data/videos/<ref>` and the peer-sync asset manifest passes an extensioned
// ref through untouched, so `video:job-123` would 404 locally and mis-guess
// `.mp4` on the wire. parseKey already bounds the ref and rejects `:`; this
// adds the path-traversal guard (mirroring sanitizeAssetFilename) and the
// extension requirement. Shared with the item-update invariant in
// moodBoard/logic.js so a PATCH can't swap a video item onto a non-video or
// extension-less key.
export function isVideoItemMediaKey(key) {
const parsed = parseKey(key || '');
if (parsed?.kind !== 'video') return false;
const { ref } = parsed;
if (ref.includes('/') || ref.includes('\\')) return false;
if (ref === '.' || ref === '..') return false;
return /\.[a-z0-9]{2,6}$/i.test(ref);
}
// External/pinned image URL: http(s), a same-origin app path (e.g. a served
// `/data/images/...` URL), or a `data:image/<fmt>;base64,...` URI (which
// `localizeImageUrl` decodes and saves into `/data/images/` before the board
// row commits). Standard URLs stay bounded to 2048 chars. Data URLs are bounded
// by the decoded 12MB ceiling (`MAX_IMAGE_DATA_URL_BYTES`), measured after
// stripping whitespace: MIME wrapping is insignificant to the image, and a
// character cap that counted it would reject a max-size paste before the
// decoder's own limit. A protocol-relative `//host/...` is rejected so the
// leading-slash branch never resolves off-origin.
const MAX_HTTP_OR_APP_IMAGE_URL_LEN = 2048;
export const MAX_IMAGE_DATA_URL_BYTES = 12 * 1024 * 1024;
const MAX_IMAGE_DATA_URL_PAYLOAD_LEN = Math.ceil((MAX_IMAGE_DATA_URL_BYTES * 4) / 3);
const DATA_IMAGE_URL_RE = /^data:image\/(?:png|jpe?g|gif|webp);base64,([A-Za-z0-9+/=\s]+)$/i;
const IMAGE_URL_MESSAGE = 'imageUrl must be an http(s) URL, a base64 PNG, JPEG, GIF, or WebP data URL, or an absolute app path';
function imageUrlIssue(value) {
if (/^https?:\/\//.test(value) || (value.startsWith('/') && !value.startsWith('//'))) {
return value.length <= MAX_HTTP_OR_APP_IMAGE_URL_LEN ? null : 'imageUrl must be at most 2048 characters';
}
const match = DATA_IMAGE_URL_RE.exec(value);
if (!match) return IMAGE_URL_MESSAGE;
const payload = match[1].replace(/\s+/g, '');
if (payload.length > MAX_IMAGE_DATA_URL_PAYLOAD_LEN) return 'Image data URL exceeds the 12MB limit';
return null;
}
const imageUrlSchema = z.string().trim().min(1).superRefine((value, ctx) => {
const message = imageUrlIssue(value);
if (message) ctx.addIssue({ code: z.ZodIssueCode.custom, message });
});
const captionSchema = z.string().max(2000).nullable().optional();
const sourceSchema = z.string().max(2048).nullable().optional();
const promptSchema = z.string().trim().max(GENERATION_METADATA_LIMITS.prompt).nullable().optional();
// Board create. description optional (defaults to '' in the record builder).
export const moodBoardCreateSchema = z.object({
name: z.string().trim().min(1).max(200),
description: z.string().max(5000).optional(),
}).strict();
// Gallery filename for the board's canonical poster. Same traversal rule as
// the asset manifest (`sanitizeAssetFilename`): separators and `.` / `..`
// are rejected; an image extension is required so a video ref can't be
// stored as the still the poster slot renders.
const posterFilenameSchema = z.string().trim().min(1).max(255).refine(
(v) => !v.includes('/') && !v.includes('\\') && v !== '.' && v !== '..'
&& /\.(png|jpe?g|gif|webp)$/i.test(v),
'posterImageRef must be a gallery image filename',
);
// Composite board style — one ready-to-render prompt distilled from the
// per-item prompt-from-media analyses. Written by POST /compose-prompt and
// editable from the board page. `null` on the PATCH clears it. Additive on
// the wire (whole-record LWW); bounds match the per-item analysis caps.
export const moodBoardStyleSchema = z.object({
prompt: z.string().trim().min(1).max(8000),
negativePrompt: z.string().max(8000).nullable().optional(),
rationale: z.string().max(1200).nullable().optional(),
analyzedItemCount: z.number().int().min(0).max(500).optional(),
providerId: z.string().max(128).nullable().optional(),
model: z.string().max(256).nullable().optional(),
composedAt: z.string().datetime({ offset: true }).nullable().optional(),
}).strict();
// Board PATCH — only the editable board-level fields. items[] is managed via
// the dedicated item endpoints, never a bulk board PATCH. `style` /
// `posterImageRef` are the composite prompt and the canonical poster.
export const moodBoardUpdateSchema = z.object({
name: z.string().trim().min(1).max(200).optional(),
description: z.string().max(5000).optional(),
style: moodBoardStyleSchema.nullable().optional(),
posterImageRef: posterFilenameSchema.nullable().optional(),
collageImageRef: posterFilenameSchema.nullable().optional(),
}).strict();
// Add-item. An `image` item requires at least one of mediaKey / imageUrl; a
// `text` item requires non-empty text; a `video` item (#4188) requires a
// `video:<filename>` mediaKey — the ref is the on-disk filename (extension
// included) so playback (`/data/videos/<ref>`) and the peer-sync asset
// manifest both resolve without guessing, and `imageUrl` optionally carries
// the poster thumbnail. The cross-field rule is enforced with a superRefine
// so the failure is specific.
export const moodBoardItemCreateSchema = z.object({
type: z.enum(MOOD_BOARD_ITEM_TYPES),
mediaKey: mediaKeySchema.nullable().optional(),
imageUrl: imageUrlSchema.nullable().optional(),
text: z.string().trim().max(10000).nullable().optional(),
prompt: promptSchema,
caption: captionSchema,
source: sourceSchema,
}).strict().superRefine((val, ctx) => {
if (val.type === 'image') {
if (!val.mediaKey && !val.imageUrl) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: 'an image item requires mediaKey or imageUrl',
path: ['imageUrl'],
});
}
} else if (val.type === 'text') {
if (!val.text || !val.text.trim()) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: 'a text item requires non-empty text',
path: ['text'],
});
}
} else if (val.type === 'video') {
if (!isVideoItemMediaKey(val.mediaKey)) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: 'a video item requires a `video:<filename>` mediaKey (filename with extension)',
path: ['mediaKey'],
});
}
}
});
// Pinterest link body. The URL shape is validated lightly here (present, http(s),
// bounded); the Pinterest-host check + board-URL→feed-URL normalization happens
// in `normalizePinterestFeedUrl` (server/lib/pinterestFeed.js), which throws a
// specific 400 so the user sees *why* a non-Pinterest URL was rejected.
export const moodBoardPinterestLinkSchema = z.object({
url: z.string().trim().min(1).max(2048).refine(
(v) => /^https?:\/\//.test(v),
'url must be an http(s) Pinterest board URL',
),
}).strict();
// X.com (Twitter) post import body. The URL shape is validated lightly here
// (present, http(s), bounded); the x.com/twitter.com host check + post-URL
// normalization happens in `parseXPostUrl` (server/lib/xPostMedia.js), which
// throws a specific 400 so a non-X URL gets a clear reason.
export const moodBoardXPostImportSchema = z.object({
url: z.string().trim().min(1).max(2048).refine(
(v) => /^https?:\/\//.test(v),
'url must be an http(s) x.com/twitter.com post URL',
),
}).strict();
// Per-item prompt-from-media analysis (#4188 Phase 3) — written by the item
// PATCH after a user-triggered vision run on the item's media. Additive on the
// wire: the board federates whole-record LWW (sanitizeBoardForSync's `...raw`
// spread) and an older peer preserves the unknown key, so no `moodBoards`
// schema-gate bump — same precedent as the `pinterest` sub-object. Bounds
// mirror the analyzer's own caps (MAX_PROMPT_LEN / MAX_REASON_LEN in
// mediaPromptFromMedia.js). `null` on the PATCH clears a stored analysis.
export const moodBoardItemAnalysisSchema = z.object({
prompt: z.string().trim().min(1).max(8000),
negativePrompt: z.string().max(8000).nullable().optional(),
rationale: z.string().max(1200).nullable().optional(),
providerId: z.string().max(128).nullable().optional(),
model: z.string().max(256).nullable().optional(),
analyzedAt: z.string().datetime({ offset: true }).nullable().optional(),
}).strict();
// Item PATCH — caption/source on any item, plus the type-appropriate body
// field. No `type` switch (an item's kind is fixed at creation); every field
// optional so a partial edit validates. `analysis` applies to media items
// only (enforced in logic.js where the item's type is known).
export const moodBoardItemUpdateSchema = z.object({
caption: captionSchema,
source: sourceSchema,
text: z.string().trim().max(10000).nullable().optional(),
imageUrl: imageUrlSchema.nullable().optional(),
mediaKey: mediaKeySchema.nullable().optional(),
prompt: promptSchema,
analysis: moodBoardItemAnalysisSchema.nullable().optional(),
}).strict();
// Collage compilation + video frame extraction. `framesPerVideo` is how many
// evenly spaced frames each video pin contributes to the grid; the per-item
// extract endpoint always appends its frames to the board, so it only takes a
// count. Bounds mirror MAX_FRAMES_PER_VIDEO in moodBoard/collage.js.
export const moodBoardCollageSchema = z.object({
framesPerVideo: z.number().int().min(1).max(24).optional().default(3),
addFramesToBoard: z.boolean().optional().default(false),
cellSize: z.number().int().min(128).max(1024).optional().default(512),
}).strict();
// Either `count` evenly spaced frames, or the exact `times` (seconds) picked
// in the frame picker.
export const moodBoardExtractFramesSchema = z.object({
count: z.number().int().min(1).max(24).optional(),
times: z.array(z.number().finite().min(0).max(86400)).min(1).max(24).optional(),
}).strict().refine((v) => (v.count == null) !== (v.times == null), { message: 'Send either count or times' });
// Render a text note into an image (#10531). Both optional: an omitted backend
// renders on the install's default image backend.
export const moodBoardItemRenderSchema = z.object({
mode: z.string().trim().min(1).max(32).optional(),
model: z.string().trim().min(1).max(256).optional(),
width: z.number().int().min(64).max(MAX_IMAGE_EDGE).optional(),
height: z.number().int().min(64).max(MAX_IMAGE_EDGE).optional(),
}).strict().refine((v) => (v.width ?? 1024) * (v.height ?? 1024) <= MAX_IMAGE_PIXELS, {
message: 'Image dimensions exceed the total pixel limit', path: ['width'],
});
// A small, explicitly requested batch. Renderer overrides remain independent
// from the prompt-writing LLM; omitted renderer fields inherit saved settings.
export const moodBoardGenerateSchema = z.object({
requestId: z.string().uuid(),
providerId: z.string().trim().min(1).max(256),
model: z.string().trim().min(1).max(256).optional(),
effort: z.string().trim().max(64).optional(),
direction: z.string().trim().max(2000).default(''),
count: z.number().int().min(1).max(4).default(1),
render: moodBoardItemRenderSchema.default({ width: 1024, height: 576 }),
retry: z.boolean().default(false),
}).strict().refine((v) => !v.render.mode || QUEUEABLE_IMAGE_MODES.includes(v.render.mode), {
message: 'Choose a queueable image backend', path: ['render', 'mode'],
});