Skip to content

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

12.5 KB
Raw Blame
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'],
});