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

21.1 KB
Raw Blame
/**
 * Shared, pure helpers for the Creative Commission config form (#2657).
 *
 * These are the editable projection of a commission record — used by BOTH the
 * index page's "New Commission" create drawer (client/src/pages/CreativeCommissions.jsx)
 * and the routed detail page's editable config (client/src/pages/CreativeCommissionDetail.jsx).
 * Kept side-effect-free so both surfaces map record ↔ form identically.
 */

import { describeRecurrence } from '../../utils/cronHelpers.js';
import { BOARD_FOLLOW_UNIVERSE, BOARD_NONE } from '../../lib/styleSourceChoice.js';

// The brief field caps are the server's own (server/lib/creativeBriefLimits.js),
// used here as the inputs' `maxLength`.
export {
  COMMISSION_BRIEF_TAG_MAX, COMMISSION_INTENT_MAX, COMMISSION_NAME_MAX, COMMISSION_STYLE_SPEC_MAX,
} from '../../../../server/lib/creativeBriefLimits.js';
// The generation-key spec (type/bounds/values/default) is the server's own too
// (server/lib/creativeCommissionSpec.js, #6816) — a zod-free leaf, like the brief
// caps above, so this form derives every bound/default/option value from it
// instead of hand-copying (the drift that left durationMode's default and the
// video/image backend enums disagreeing with the server for months).
import {
  GENERATION_KEY_DEFS, ABILITY_GENERATION_SPEC,
} from '../../../../server/lib/creativeCommissionSpec.js';
// The NODE-SAFE half of imageGenBackends.js (no lucide-react import) — this
// module is imported from a server-workspace parity test
// (creativeCommissionSpec.parity.test.js), which fails with ERR_MODULE_NOT_FOUND
// if anything here pulls in a browser-only package.
import { RENDER_TARGET_BACKEND_AUTO as RENDER_BACKEND_AUTO, modeLabel } from '../../lib/imageGenModes.js';

// Pause and Delete are real STOPS, not just "skip the next tick": the server also
// tears down the Creative Director projects the commission already spawned
// (server/services/creativeCommissions/projectControl.js). Both surfaces must say
// so — a user watching a retry loop has no other way to know it just ended — and
// both must say it the same way, which is why the strings live here.
export const COMMISSION_STOP_COPY = Object.freeze({
  pausedToast: 'Commission paused — stopping any generation still in flight',
  resumedToast: 'Schedule resumed',
  deletedToast: 'Commission deleted — stopping any generation still in flight',
  pauseTitle: 'Pause — stops the schedule and any generation still in flight',
  resumeTitle: 'Resume the schedule',
  deleteTitle: 'Delete commission — also stops any generation still in flight',
});

export const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];

export const inputCls = 'w-full bg-port-bg border border-port-border rounded px-3 py-2 text-sm text-gray-100 focus:outline-none focus:border-port-accent';
export const labelCls = 'block text-xs font-medium text-gray-400 mb-1';

// Creative-output types the commission can produce (#2769). Mirrors the server
// enum CREATIVE_COMMISSION_ABILITIES; `video` stays first (the default).
export const ABILITY_OPTIONS = [
  { id: 'video', label: 'Video' },
  { id: 'image', label: 'Image' },
  { id: 'music', label: 'Music' },
  { id: 'music-video', label: 'Music video' },
  { id: 'series', label: 'Series' },
];

// Re-exported so the commission form and the Settings Defaults tab (#3231)
// can never disagree on the "no pin" protocol value.
export { RENDER_BACKEND_AUTO };

// Presentation-only metadata for each generation key: the server spec
// (server/lib/creativeCommissionSpec.js, GENERATION_KEY_DEFS) owns every
// enumerable VALUE, bound, and default — this map adds only the display label
// and, for the two render-backend-pin keys, the conditional-model-picker
// wiring. `type: 'backend'` fields render as a mode picker plus a conditional
// model picker (see CommissionConfigForm's RenderBackendSection), mirroring
// the pipeline's VisualGenSettings UX; the generic field renderer in
// GenerationSection skips them. `modelKind` names which media-model catalog
// the conditional picker reads, and `modelModes` lists the modes that HAVE a
// model knob — the cloud CLIs pick their own model, so the picker only
// appears for local.
const FIELD_LABELS = {
  quality: 'Quality',
  aspectRatio: 'Aspect ratio',
  targetDurationSeconds: 'Duration (sec)',
  durationMode: 'Video length',
  imageCount: 'Image count',
  lengthSeconds: 'Length (sec)',
  episodeCount: 'Episodes',
  imageMode: 'Image backend',
  videoMode: 'Video backend',
};
const OPTION_LABELS = {
  quality: { draft: 'Draft', standard: 'Standard', high: 'High' },
  durationMode: { auto: 'Creative Director chooses', manual: 'Set a specific length' },
};
const BACKEND_FIELD_META = {
  imageMode: { modelKey: 'imageModelId', modelKind: 'image', modelModes: ['local'], modelLabel: 'Local image model' },
  videoMode: { modelKey: 'videoModelId', modelKind: 'video', modelModes: ['local'], modelLabel: 'Local video model' },
};

// A render-backend mode's display label. Every real backend reads from the
// shared `modeLabel` (client/src/lib/imageGenModes.js) so a backend added
// there (fal, reactor, agy, …) is labeled here automatically — the drift that
// left the video/image backend pickers behind generationModes.js for months.
const backendOptionLabel = (mode) => (mode === RENDER_BACKEND_AUTO ? 'Auto (install default)' : modeLabel(mode));

// Build one field descriptor from a generation key's spec descriptor
// (type/bounds/values) plus its presentation metadata above. `type: 'id'` keys
// (imageModelId/videoModelId) never build their own field — they're the
// model-id half of their backend field's `modelKey` — so callers only ever
// list an ability's non-id keys below.
function buildGenerationField(key) {
  const def = GENERATION_KEY_DEFS[key];
  const label = FIELD_LABELS[key] || key;
  if (def.type === 'int') return { key, label, type: 'number', min: def.min, max: def.max };
  const backend = BACKEND_FIELD_META[key];
  if (backend) {
    return {
      key, label, type: 'backend', options: def.values.map((v) => [v, backendOptionLabel(v)]), ...backend,
    };
  }
  return { key, label, type: 'select', options: def.values.map((v) => [v, OPTION_LABELS[key]?.[v] || v]) };
}

// Per-ability generation field descriptors, built from the server's
// per-key spec (server/lib/creativeCommissionSpec.js) so a new backend enum
// member or a bound change needs no edit here. The per-ability KEY LIST and
// its display ORDER stay hand-declared — `durationMode` before
// `targetDurationSeconds` so "how the length is chosen" reads before "the
// length itself" (GenerationSection hides the latter in auto mode) — and the
// required parity test (creativeCommissionSpec.parity.test.js) fails if this
// ever drops a key the server ability actually carries.
export const GENERATION_FIELDS_BY_ABILITY = {
  video: ['quality', 'aspectRatio', 'durationMode', 'targetDurationSeconds', 'videoMode'].map(buildGenerationField),
  image: ['quality', 'aspectRatio', 'imageCount', 'imageMode'].map(buildGenerationField),
  music: ['lengthSeconds'].map(buildGenerationField),
  'music-video': ['quality', 'aspectRatio', 'durationMode', 'targetDurationSeconds', 'videoMode', 'imageMode'].map(buildGenerationField),
  series: ['episodeCount'].map(buildGenerationField),
};

export const IMAGE_BACKEND_OPTIONS = GENERATION_FIELDS_BY_ABILITY.image.find((f) => f.key === 'imageMode').options;
export const VIDEO_BACKEND_OPTIONS = GENERATION_FIELDS_BY_ABILITY.video.find((f) => f.key === 'videoMode').options;

// Per-ability generation defaults for seeding a BRAND-NEW commission/form —
// each key's spec `default` (#4494's `durationMode: 'auto'` product choice,
// now declared once in GENERATION_KEY_DEFS instead of hand-copied here).
// Projecting a REAL fetched record's own gaps is a different reading — see
// generationToForm below, which prefers a key's `legacyAbsent` when the spec
// declares one.
export const GENERATION_DEFAULTS_BY_ABILITY = Object.fromEntries(
  Object.entries(ABILITY_GENERATION_SPEC).map(([ability, spec]) => [
    ability,
    Object.fromEntries(spec.keys.map((k) => [k, GENERATION_KEY_DEFS[k].default])),
  ]),
);

export const MUSIC_TASTE_DEFAULTS = Object.freeze({
  enabled: false,
  source: 'digital-twin',
  window: 'month',
  anchorCount: 3,
  explorationPercent: 20,
  musicEngineId: '',
  musicModelId: '',
});

// The render-backend descriptors for an ability, in field order. Drives the
// dedicated backend section; the generic field grid skips `type: 'backend'`.
export function backendFieldsForAbility(ability) {
  return (GENERATION_FIELDS_BY_ABILITY[abilityOr(ability)] || []).filter((f) => f.type === 'backend');
}

function abilityOr(ability) {
  return GENERATION_DEFAULTS_BY_ABILITY[ability] ? ability : 'video';
}

// Fill an ability's keys from `generation`, falling back to `defaults` for any
// key that is absent or null. Only the ability's own keys appear, so switching
// types never carries a stale key. The two exported projections below differ
// ONLY in which defaults they fall back to.
function fillGeneration(defaults, generation) {
  const out = {};
  for (const key of Object.keys(defaults)) {
    const v = generation?.[key];
    out[key] = v === undefined || v === null ? defaults[key] : v;
  }
  return out;
}

// Project a stored generation object into the form for a given ability, falling
// back to the LEGACY-AWARE default (ABILITY_GENERATION_SPEC's `defaults`, not
// GENERATION_DEFAULTS_BY_ABILITY) — a key absent from a REAL record prefers its
// spec `legacyAbsent` reading over the fresh-commission `default` (only
// `durationMode` differs today: an existing record with no key means 'manual',
// matching abilityAdapters.js).
export function generationToForm(ability, generation) {
  return fillGeneration(ABILITY_GENERATION_SPEC[abilityOr(ability)].defaults, generation);
}

// When the user switches output type, seed the new type's fields with the
// type's FRESH defaults (GENERATION_DEFAULTS_BY_ABILITY — the same seeds a blank
// form gets) but carry over any overlapping value the user already set (e.g.
// keep their quality/aspectRatio when going video → image). A key the switch
// introduces was never on this record at all, so `legacyAbsent` does not
// describe it: an image commission that becomes a video one never rendered a
// fixed-length video, and #4494's "Creative Director chooses" seed applies to
// it exactly as it does to a new commission.
export function mergeGenerationForAbility(ability, generation) {
  return fillGeneration(GENERATION_DEFAULTS_BY_ABILITY[abilityOr(ability)], generation);
}

// Build the API generation payload for the current ability: emit only that
// ability's keys, coercing number fields (form <input type=number> values are
// strings). Mirrors the server superRefine, which rejects off-type keys.
export function generationToPayload(ability, generation) {
  const a = abilityOr(ability);
  const fields = GENERATION_FIELDS_BY_ABILITY[a];
  const out = {};
  for (const field of fields) {
    const v = generation?.[field.key];
    if (field.type === 'backend') {
      // A backend descriptor owns TWO record keys. The model id only travels when
      // the pinned mode actually has a model knob — otherwise a stale id left over
      // from a previous local pin would ride along on a cloud pin and confuse the
      // stored record. Send `null` (not omit) so clearing a pin clears the id too:
      // the server merges `generation` shallowly, and an omitted key would preserve
      // the stale value (the absent-vs-empty rule).
      const mode = v || RENDER_BACKEND_AUTO;
      const model = generation?.[field.modelKey];
      out[field.key] = mode;
      out[field.modelKey] = field.modelModes.includes(mode) && model ? model : null;
      continue;
    }
    out[field.key] = field.type === 'number' ? Number(v) : v;
  }
  if (out.durationMode === 'auto') delete out.targetDurationSeconds;
  return out;
}

// The style-source picker's board choice, mapped onto the server's wire
// contract (services/creativeCommissions/styleSource.js): a null moodBoardId
// follows the universe's linked board, '' means no board, any other string
// names one.
export { BOARD_FOLLOW_UNIVERSE, BOARD_NONE };

function boardChoiceFromRecord(moodBoardId) {
  if (moodBoardId == null) return BOARD_FOLLOW_UNIVERSE;
  return moodBoardId === '' ? BOARD_NONE : moodBoardId;
}

function boardIdFromChoice(choice) {
  if (choice === BOARD_FOLLOW_UNIVERSE) return null;
  return choice === BOARD_NONE ? '' : choice;
}

// Human-readable cadence summary for the list card + detail header.
export function describeSchedule(schedule) {
  if (!schedule) return 'No schedule';
  const { kind, atLocalTime, weekday, weekdaysOnly, cron } = schedule;
  if (kind === 'CUSTOM') return `Custom · ${cron || '—'}`;
  if (kind === 'RECURRENCE') return describeRecurrence(schedule.recurrence) || 'Custom recurrence';
  if (kind === 'WEEKLY') return `Weekly · ${WEEKDAYS[weekday] ?? '—'} at ${atLocalTime || '—'}`;
  if (kind === 'DAILY') return `Daily${weekdaysOnly ? ' (weekdays)' : ''} at ${atLocalTime || '—'}`;
  return kind || 'No schedule';
}

// Compact "who processes this" summary. Unset → the install default assignment;
// set → the pinned provider (and model, when chosen).
export function describeAssignment(assignment) {
  const providerId = assignment?.providerId;
  if (!providerId) return 'Install default AI';
  return assignment.model ? `${providerId} · ${assignment.model}` : providerId;
}

// Map a stored record → editable form state (fills gaps so inputs stay controlled).
export function toForm(c) {
  return {
    name: c.name || '',
    enabled: c.enabled !== false,
    targetAbility: c.targetAbility || 'video',
    brief: {
      intent: c.brief?.intent || '',
      genre: c.brief?.genre || '',
      styleSpec: c.brief?.styleSpec || '',
    },
    // The universe / mood board whose style tags and reference images are the
    // art-direction base each run hands the Creative Director.
    styleSource: {
      universeId: c.brief?.constraints?.universeId || '',
      moodBoardChoice: boardChoiceFromRecord(c.brief?.constraints?.moodBoardId),
    },
    musicTaste: c.brief?.musicTaste ? {
      enabled: true,
      source: 'digital-twin',
      window: c.brief.musicTaste.window || MUSIC_TASTE_DEFAULTS.window,
      anchorCount: c.brief.musicTaste.anchorCount ?? MUSIC_TASTE_DEFAULTS.anchorCount,
      explorationPercent: c.brief.musicTaste.explorationPercent ?? MUSIC_TASTE_DEFAULTS.explorationPercent,
      musicEngineId: c.brief.musicTaste.musicEngineId || '',
      musicModelId: c.brief.musicTaste.musicModelId || '',
    } : { ...MUSIC_TASTE_DEFAULTS },
    schedule: {
      kind: c.schedule?.kind || 'DAILY',
      atLocalTime: c.schedule?.atLocalTime || '02:00',
      weekday: Number.isInteger(c.schedule?.weekday) ? c.schedule.weekday : 0,
      weekdaysOnly: c.schedule?.weekdaysOnly === true,
      cron: c.schedule?.cron || '',
      recurrence: c.schedule?.recurrence || null,
      timezone: c.schedule?.timezone || null,
    },
    // Per-ability generation (#2769): only the selected type's fields, filled
    // from the record or the type's defaults. NOT YET PERSISTED (no `id` —
    // `blankForm()`'s `toForm({})`, or a create-drawer harness that pre-seeds
    // just a brief before the user has touched generation at all) with no
    // `generation` opinion either seeds every key's fresh-commission default;
    // anything else — any record that HAS an id, or that already carries a
    // `generation` object of its own — projects through generationToForm,
    // which resolves an absent key to its spec `legacyAbsent` reading when
    // the key has one. durationMode's is 'manual', so an existing record
    // with no key still projects as a fixed length (matching
    // abilityAdapters.js) while a genuinely brand-new commission seeds 'auto'
    // (the #4494 product choice). Gating on `c.generation == null` alone
    // would treat a saved record whose generation object is missing/null the
    // same as a fresh one; requiring `!c.id` too keeps that record on the
    // legacy-aware path (ids are always minted server-side, never present on
    // an unsaved commission).
    generation: c.generation == null && !c.id
      ? { ...GENERATION_DEFAULTS_BY_ABILITY[abilityOr(c.targetAbility)] }
      : generationToForm(c.targetAbility, c.generation),
    // Which AI provider/model processes the commission's CD stages. Empty
    // providerId → the install's default AI Assignment.
    assignment: {
      providerId: c.assignment?.providerId || '',
      model: c.assignment?.model || '',
      effort: c.assignment?.effort || '',
    },
    // How many recent reactions steer the next run (0 disables conditioning).
    feedbackWindow: Number.isInteger(c.feedbackWindow) ? c.feedbackWindow : 5,
  };
}

// A blank form is just the editable projection of an empty record.
export const blankForm = () => toForm({});

// Build the API payload from form state, dropping fields the schedule kind doesn't use.
export function toPayload(form) {
  const s = { kind: form.schedule.kind };
  if (form.schedule.timezone) s.timezone = form.schedule.timezone;
  if (form.schedule.kind === 'CUSTOM') {
    s.cron = form.schedule.cron.trim();
  } else if (form.schedule.kind === 'RECURRENCE') {
    s.recurrence = form.schedule.recurrence;
  } else {
    s.atLocalTime = form.schedule.atLocalTime;
    if (form.schedule.kind === 'WEEKLY') s.weekday = Number(form.schedule.weekday);
    if (form.schedule.kind === 'DAILY') s.weekdaysOnly = !!form.schedule.weekdaysOnly;
  }
  return {
    name: form.name.trim(),
    enabled: !!form.enabled,
    targetAbility: form.targetAbility,
    brief: {
      intent: form.brief.intent.trim(),
      genre: form.brief.genre.trim() || null,
      styleSpec: form.brief.styleSpec,
      // Merged one level deep server-side, so a stored seriesId survives.
      constraints: {
        universeId: form.styleSource.universeId || null,
        moodBoardId: boardIdFromChoice(form.styleSource.moodBoardChoice),
      },
      musicTaste: form.targetAbility === 'music' && form.musicTaste.enabled ? {
        source: 'digital-twin',
        window: form.musicTaste.window,
        anchorCount: Number(form.musicTaste.anchorCount),
        explorationPercent: Number(form.musicTaste.explorationPercent),
        musicEngineId: form.musicTaste.musicEngineId || null,
        musicModelId: form.musicTaste.musicModelId || null,
      } : null,
    },
    schedule: s,
    // Emit only the selected type's generation keys (#2769), coercing numbers.
    generation: generationToPayload(form.targetAbility, form.generation),
    // Send the full pin every save; a provider-less choice clears the model too
    // (the server drops a dangling model, but keeping the payload clean avoids a
    // pointless round-trip through the sanitizer's normalization).
    assignment: {
      providerId: form.assignment.providerId || null,
      model: form.assignment.providerId ? (form.assignment.model || null) : null,
      ...(form.assignment.providerId && form.assignment.effort ? { effort: form.assignment.effort } : {}),
    },
    feedbackWindow: Number(form.feedbackWindow),
  };
}

// A patch helper for one/two-level form paths, shared by both editors.
export function patchFormState(prev, path, value) {
  const next = { ...prev };
  if (path.length === 1) next[path[0]] = value;
  else next[path[0]] = { ...prev[path[0]], [path[1]]: value };
  return next;
}

// Validate the form before save. Returns an error string, or null when valid.
// A cleared feedbackWindow is '', which Number() coerces to 0 — and 0 is the
// valid "disable conditioning" value, so a blank field would silently turn
// feedback off. Reject it instead of guessing intent.
export function validateForm(form) {
  if (!form.name.trim()) return 'Name is required';
  if (!form.brief.intent.trim()) return 'Brief intent is required';
  const fw = Number(form.feedbackWindow);
  if (form.feedbackWindow === '' || !Number.isInteger(fw) || fw < 0 || fw > 50) {
    return 'Feedback window must be a whole number from 0 to 50';
  }
  // Per-ability numeric fields (#2769): a cleared/out-of-range number would coerce
  // to NaN/0 in the payload and 400 at the server — reject it here with a clear
  // message rather than guessing intent.
  const fields = GENERATION_FIELDS_BY_ABILITY[abilityOr(form.targetAbility)] || [];
  for (const field of fields) {
    if (field.type !== 'number') continue;
    const raw = form.generation?.[field.key];
    const n = Number(raw);
    if (raw === '' || raw === null || raw === undefined || !Number.isInteger(n) || n < field.min || n > field.max) {
      return `${field.label} must be a whole number from ${field.min} to ${field.max}`;
    }
  }
  if (form.targetAbility === 'music' && form.musicTaste?.enabled) {
    const anchorCount = Number(form.musicTaste.anchorCount);
    if (form.musicTaste.anchorCount === '' || !Number.isInteger(anchorCount) || anchorCount < 1 || anchorCount > 5) {
      return 'Taste anchor count must be a whole number from 1 to 5';
    }
    const exploration = Number(form.musicTaste.explorationPercent);
    if (form.musicTaste.explorationPercent === '' || !Number.isInteger(exploration) || exploration < 0 || exploration > 100) {
      return 'Taste exploration must be a whole percentage from 0 to 100';
    }
  }
  return null;
}