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

24.8 KB
Raw Blame
/**
 * Sprites Routes — REST surface for the Sprite Manager.
 *
 * Phase 1 (#2895): library list/get, source-tree importer, record patch.
 * Phase 2 (#2896, reordered turnaround-first in #2979): character create + the
 * reference workflow — generate turnaround/main/anchor candidates through the
 * shared image-gen queue, review, then lock (normalize + dynamic chroma-key
 * selection). Generation is strictly user-triggered per the AI-provider policy;
 * locked artifacts are versioned and protected from overwrite; deliberate
 * unlock actions reopen either one derived anchor or the full turnaround chain.
 */

import { Router } from 'express';
import { unlink } from 'fs/promises';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import {
  validateRequest,
  spriteImportRequestSchema,
  spriteRecordUpdateSchema,
  spriteCreateSchema,
  spriteReferenceGenerateSchema,
  spriteReferenceLockSchema,
  spriteReferenceUnlockSchema,
  spriteForkSchema,
  spriteTrackGenerateSchema,
  spriteTrackApproveSchema,
  spriteTrackReopenSchema,
  spriteTrackParamsSchema,
  spriteAnimationTrackCreateSchema,
  spriteAnimationTrackUpdateSchema,
  spriteWalkGenerateSchema,
  spriteWalkApproveSchema,
  spriteWalkReopenSchema,
  spriteWalkUnlockSchema,
  spriteWalkPostprocessSchema,
  spriteWalkTargetSchema,
  spriteWalkSourceFramesParamsSchema,
  spriteWalkTrimSchema,
  spritePublishBindingSchema,
  spriteAtlasCompileSchema,
  spriteAtlasPublishSchema,
  spriteAssetDeleteSchema,
  isPaginationRequested,
  paginateArray,
} from '../lib/validation.js';
import { z } from 'zod';
import { optionalUploadFields } from '../lib/multipart.js';
import {
  listRecords, getRecordWithAssets, createCharacter, deleteRecord,
} from '../services/sprites/records.js';
import { importFromSource } from '../services/sprites/importer.js';
import {
  getReferenceSet, startReferenceGeneration, lockReference, patchSpriteRecord,
  listReferenceSources, listSpriteThumbnails, forkSprite,
} from '../services/sprites/reference.js';
import { resolveSpriteAssetPrompt } from '../services/sprites/assetPrompt.js';
import { listAnimationProviders } from '../services/sprites/localAnimationRender.js';
import {
  WALK_TRACK,
  isAnimationTrack, kindSupportsTrack, tracksForKind,
  getAnimationTrack as getAnimationTrackRow,
} from '../services/sprites/animationTracks.js';
// #3152 — every registry question a request asks is answered against the
// EFFECTIVE table (compiled `walk` + the user-defined store), so a user's own
// track is routable, gated, and listed with no route edit.
import {
  getEffectiveAnimationTracks, getEffectiveAnimationTrackIds,
} from '../services/sprites/animationTrackStore.js';
import {
  getWalkState, startWalkGeneration, approveWalkDirection, rerunWalkPostprocess, unlockWalkSet,
  reopenWalkDirection, setWalkTarget, getWalkSourceFrames,
  unlockDirectionalAnchor, unlockMainReference, unlockTurnaroundReference,
} from '../services/sprites/walk.js';
import {
  getTrackState, startTrackGeneration, approveTrackRun, reopenTrackDirection,
} from '../services/sprites/animationTrackWorkflow.js';
// #3153 — CRUD over the user-defined store. Separate from the read-side store
// module so `validation.js`'s import graph stays free of the record scan the
// in-use refusal needs (see animationTrackCrud.js's header).
import {
  listAnimationTracks, createAnimationTrack, updateAnimationTrack, deleteAnimationTrack,
  animationTrackStoreOrigin,
} from '../services/sprites/animationTrackCrud.js';
import { saveLoopTrim } from '../services/sprites/walkTrims.js';
import { compileAtlas, getAtlasState } from '../services/sprites/atlas.js';
import { resolveWalkFrameCount } from '../services/sprites/atlasGrid.js';
import { setPublishBinding, publishAtlas } from '../services/sprites/publish.js';
import { deleteSpriteAsset } from '../services/sprites/assets.js';

const router = Router();

const MAX_REFERENCE_UPLOAD_BYTES = 20 * 1024 * 1024;
const ACCEPTED_REFERENCE_MIME = new Set(['image/png', 'image/jpeg', 'image/webp']);
const REFERENCE_MIME_TO_EXT = {
  'image/png': '.png',
  'image/jpeg': '.jpg',
  'image/webp': '.webp',
};

/**
 * Validate + resolve the `:trackId` path param to a registered track id (#3136).
 *
 * Two distinct rejections, deliberately not collapsed: a malformed id is a 400
 * from the shape schema, while a well-formed id that names no registered track is
 * a 404 that LISTS the tracks — because "there is no such animation type" is a
 * fact about the registry the user can act on, and a bare 400 would read as "your
 * request was malformed" for a perfectly-formed one.
 *
 * `walk` is refused here on purpose: it keeps its own `/:id/walk/*` routes with
 * reprocess, trims, per-direction reopen and set targets that the generic
 * workflow does not implement, so accepting it would 404-on-disk later (walk
 * writes `walk/<id>-walk-set-v1.json` through walk.js, not through this path)
 * instead of failing here with a message that explains where to go.
 */
function resolveTrackParam(params) {
  const { trackId } = validateRequest(spriteTrackParamsSchema, params);
  if (trackId === WALK_TRACK) {
    throw new ServerError(
      'The walk cycle has its own endpoints (/walk/generate, /walk/approve) — it carries reprocessing, trims, and set targets the generic track routes do not',
      { status: 400, code: 'WALK_NOT_GENERIC' },
    );
  }
  if (!isAnimationTrack(trackId, getEffectiveAnimationTracks())) {
    throw new ServerError(
      `Unknown animation track '${trackId}' — the registered tracks are: ${getEffectiveAnimationTrackIds().join(', ')}`,
      { status: 404, code: 'UNKNOWN_ANIMATION_TRACK' },
    );
  }
  return trackId;
}

/**
 * A directional track needs a facing; a non-directional one derives row 0 itself.
 *
 * The generic request schema marks `direction` optional because ONE shape serves
 * both, so this is where the requirement lands — asking the registry rather than
 * restating which tracks are directional. Without it a directional generate with
 * no `direction` would fall through to the service and 409 "lock the undefined
 * anchor", blaming the reference set for a missing request field.
 */
function requireDirectionForTrack(trackId, body) {
  if (!getAnimationTrackRow(trackId, getEffectiveAnimationTracks()).directional || body.direction) return;
  throw new ServerError(
    `The ${trackId} track is directional — name the facing to animate`,
    { status: 400, code: 'DIRECTION_REQUIRED' },
  );
}

const referenceUpload = optionalUploadFields(['referenceImage'], {
  limits: { fileSize: MAX_REFERENCE_UPLOAD_BYTES },
  // multer-style (req, file, cb) — streamMultipart requires the callback to
  // be invoked synchronously (see routes/imageGen.js for the sibling).
  fileFilter: (_req, file, cb) => cb(null, ACCEPTED_REFERENCE_MIME.has((file.mimetype || '').toLowerCase())),
});

// Backward-compatible by default: returns the full records array. When a client
// passes `limit`/`offset`, the response becomes the bounded
// `{ items, total, limit, offset }` envelope every paginated PortOS list shares.
router.get('/', asyncHandler(async (req, res) => {
  const records = await listRecords();
  if (!isPaginationRequested(req.query)) {
    return res.json(records);
  }
  res.json(paginateArray(records, req.query, { defaultLimit: 50, maxLimit: 500 }));
}));

// Characters with a locked main reference — the pool that can seed a new main
// (i2i) or be forked. MUST precede `/:id` so the literal path isn't captured as
// an id param.
router.get('/reference-sources', asyncHandler(async (_req, res) => {
  res.json(await listReferenceSources());
}));

// A representative thumbnail per record for the Library catalog — every kind,
// not just reference-workflow characters. MUST precede `/:id`.
router.get('/thumbnails', asyncHandler(async (_req, res) => {
  res.json(await listSpriteThumbnails());
}));

// Authoring the user-defined animation types (#3153) — a record-INDEPENDENT
// surface, so like `/reference-sources` and `/thumbnails` it MUST precede `/:id`
// or the literal path is captured as a record id. The DELETE likewise precedes
// `DELETE /:id`; it can't collide (two segments vs. one) but the block stays
// together so the ordering rule is visible in one place.
//
// No AI call on any of these: a track definition is data. Generating anything
// FROM it stays behind the user-triggered `/tracks/:trackId/generate`.
router.get('/animation-tracks', asyncHandler(async (_req, res) => {
  res.json({ ...listAnimationTracks(), origin: await animationTrackStoreOrigin() });
}));

router.post('/animation-tracks', asyncHandler(async (req, res) => {
  const input = validateRequest(spriteAnimationTrackCreateSchema, req.body);
  res.status(201).json(await createAnimationTrack(input));
}));

router.put('/animation-tracks/:trackId', asyncHandler(async (req, res) => {
  const { trackId } = validateRequest(spriteTrackParamsSchema, req.params);
  const patch = validateRequest(spriteAnimationTrackUpdateSchema, req.body);
  res.json(await updateAnimationTrack(trackId, patch));
}));

router.delete('/animation-tracks/:trackId', asyncHandler(async (req, res) => {
  const { trackId } = validateRequest(spriteTrackParamsSchema, req.params);
  res.json(await deleteAnimationTrack(trackId));
}));

// Which engines can render an animation clip on THIS install, and why one
// cannot (#4876). Must precede `GET /:id` for the same reason the block above
// does — a literal first segment would otherwise be captured as a record id.
//
// Read-only readiness: it probes an already-installed venv and the local HF
// cache, and starts no render, so it does not touch the user-triggered
// AI-provider gate. The client shows the reason beside a disabled option, which
// is what turns "why is Local greyed out?" into an answer in place rather than a
// 409 after a click.
router.get('/animation-providers', asyncHandler(async (_req, res) => {
  res.json({ providers: await listAnimationProviders() });
}));

// Create a character record — the entry point of the reference workflow.
// Id derivation and the kind live in the service (createCharacter).
router.post('/', asyncHandler(async (req, res) => {
  const input = validateRequest(spriteCreateSchema, req.body);
  res.status(201).json(await createCharacter(input));
}));

// Import approved production assets from a source tree. A direct user action
// (never boot-triggered) per the AI Provider / cold-start policy — though this
// endpoint itself makes no AI calls, only file copies.
router.post('/import', asyncHandler(async (req, res) => {
  const input = validateRequest(spriteImportRequestSchema, req.body);
  res.json(await importFromSource(input));
}));

router.get('/:id', asyncHandler(async (req, res) => {
  const detail = await getRecordWithAssets(req.params.id);
  if (!detail) throw new ServerError('Sprite record not found', { status: 404, code: 'NOT_FOUND' });
  // Two questions, not one (#3017). `reference`/`walk` are the gait-shaped
  // workflow, so they follow the WALK track's record kinds — the same thing
  // requireCharacter asks. `atlas` follows the track-presence gate that
  // compileAtlas/publishAtlas use, so a record kind unlocked by a future
  // non-directional track gets its compiled atlas back here too; spelling this
  // as `kind === 'character'` would have left the UI blank for exactly the
  // records the registry had just admitted.
  const { kind } = detail.record;
  const effectiveTracks = getEffectiveAnimationTracks();
  const kindTracks = tracksForKind(kind, effectiveTracks);
  const runsWalk = kindSupportsTrack(kind, WALK_TRACK, effectiveTracks);
  // Every non-walk track this record's kind may carry, resolved from the registry
  // (#3136) instead of one hand-written `runsScanner`/`runsAmbient` flag per
  // track. Each state carries its own `definition` (the registry row), so the
  // client renders a track's label, facing count and bounds from data rather than
  // mirroring them as component copy — which is what lets ONE workflow component
  // serve a track the client has never heard of.
  const genericTracks = kindTracks.filter((row) => row.id !== WALK_TRACK);
  const [reference, walk, atlas, ...trackStates] = await Promise.all([
    kindTracks.length ? getReferenceSet(req.params.id) : null,
    runsWalk ? getWalkState(req.params.id) : null,
    kindTracks.length ? getAtlasState(req.params.id) : null,
    ...genericTracks.map((row) => getTrackState(row.id, req.params.id)),
  ]);
  // Imported/pre-#3016 walk pointers may carry only their legacy column list.
  // Normalize that compatibility shape at the API boundary so every client
  // track reader can stay on the generic field/span contract.
  if (runsWalk && atlas?.current?.geometry) {
    atlas.current.geometry.walkFrameCount = resolveWalkFrameCount(atlas.current.geometry);
  }
  const tracks = Object.fromEntries(genericTracks.map((row, index) => [row.id, trackStates[index]]));
  // PublishWorkflow needs the COMPLETE applicable registry slice, including
  // walk (whose bespoke state does not carry `definition`). Keep it separate
  // from `tracks`, which remains the generic non-walk authoring-state map.
  res.json({
    ...detail, reference, walk, tracks, trackDefinitions: kindTracks, atlas,
  });
}));

// The generation prompt behind one on-disk asset (record-relative `path`) —
// reference candidate, locked main/anchor, or walk-animation render — so the
// client's preview modals can show + copy it. Returns `null` for an asset with
// no prompt provenance (imports, manifests). Two path segments, so it never
// collides with the single-segment `/:id` GET above.
router.get('/:id/asset-prompt', asyncHandler(async (req, res) => {
  const { path } = validateRequest(z.object({ path: z.string().min(1) }), req.query);
  res.json(await resolveSpriteAssetPrompt(req.params.id, path));
}));

// Queue one reference candidate render (main or a directional anchor).
// Accepts JSON, or multipart with an optional `referenceImage` file for the
// main target (an uploaded visual design reference → i2i).
router.post('/:id/reference/generate', referenceUpload, asyncHandler(async (req, res) => {
  // Capture + register the temp-file sweep BEFORE validation — a 400 thrown
  // by validateRequest would otherwise leak the already-finalized upload.
  // The service moves the file on success, so the unlink is a harmless
  // ENOENT there.
  const file = req.files?.referenceImage;
  const upload = file ? {
    tempPath: file.path,
    ext: REFERENCE_MIME_TO_EXT[(file.mimetype || '').toLowerCase()],
  } : null;
  if (upload) res.on('close', () => { unlink(upload.tempPath).catch(() => {}); });
  const body = validateRequest(spriteReferenceGenerateSchema, req.body ?? {});
  // A design upload seeds the identity root, which is always the turnaround
  // sheet (#2979, #2996) — the main and every anchor derive from that sheet, so
  // there is nowhere for a seed of their own to go.
  if (upload && body.target !== 'turnaround') {
    throw new ServerError('Reference image uploads seed the turnaround sheet — the main reference and directional anchors always derive from it', { status: 400, code: 'UPLOAD_TURNAROUND_ONLY' });
  }
  res.json(await startReferenceGeneration(req.params.id, body, upload));
}));

// Lock a reviewed candidate: normalize onto the canonical key-color square
// and freeze it in the reference-set manifest. 409 when already locked.
router.post('/:id/reference/lock', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteReferenceLockSchema, req.body);
  res.json(await lockReference(req.params.id, body));
}));

// Re-open one turnaround-derived directional anchor for correction. The old
// versioned PNG remains on disk, and any approved walk conditioned on it is
// reopened so stale animation cannot survive the reference revision.
router.post('/:id/reference/unlock', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteReferenceUnlockSchema, req.body);
  res.json(await unlockDirectionalAnchor(req.params.id, body));
}));

// Re-open the main (south) reference while keeping the turnaround and the
// other directional anchors locked. Its dependent walk/scanner approvals are
// invalidated so they cannot survive a changed source image.
router.post('/:id/reference/main/unlock', asyncHandler(async (req, res) => {
  res.json(await unlockMainReference(req.params.id));
}));

// Re-open the turnaround identity root for regeneration. This deliberately
// resets the main, all directional anchors, and every approved dependent walk;
// versioned files remain on disk as history.
router.post('/:id/reference/turnaround/unlock', asyncHandler(async (req, res) => {
  res.json(await unlockTurnaroundReference(req.params.id));
}));

// Fork `:id` into a new character seeded (image+text→image) from its locked
// main reference. Creates the record then queues the main render; returns the
// new record + jobId. User-triggered per the AI-provider policy.
router.post('/:id/fork', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteForkSchema, req.body);
  res.status(201).json(await forkSprite(req.params.id, body));
}));

// Phase 3 (#2897): queue one grok walk video for a locked directional
// anchor. User-triggered per the AI-provider policy; everything after the
// clip is deterministic local postprocessing.
router.post('/:id/walk/generate', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteWalkGenerateSchema, req.body);
  res.json(await startWalkGeneration(req.params.id, body));
}));

// Every non-walk animation track — the shipped `scanner`/`ambient` rows and any
// later user-defined one — generates and approves through ONE pair of routes
// (#3136). What used to be `/:id/scanner/generate` and `/:id/ambient/generate`
// (two hand-written pairs that would have become N pairs) is now
// `/:id/tracks/:trackId/generate`, with the track's bounds, facing count, source
// reference, and prompt all resolved from its registry row.
//
// Generation stays the only path that starts a Grok render, preserving the
// no-cold-bootstrap provider contract.
router.post('/:id/tracks/:trackId/generate', asyncHandler(async (req, res) => {
  const trackId = resolveTrackParam(req.params);
  const body = validateRequest(spriteTrackGenerateSchema(trackId), req.body ?? {});
  requireDirectionForTrack(trackId, body);
  res.json(await startTrackGeneration(trackId, req.params.id, body));
}));

router.post('/:id/tracks/:trackId/approve', asyncHandler(async (req, res) => {
  const trackId = resolveTrackParam(req.params);
  const body = validateRequest(spriteTrackApproveSchema, req.body);
  requireDirectionForTrack(trackId, body);
  res.json(await approveTrackRun(trackId, req.params.id, body));
}));

router.post('/:id/tracks/:trackId/reopen', asyncHandler(async (req, res) => {
  const trackId = resolveTrackParam(req.params);
  const body = validateRequest(spriteTrackReopenSchema, req.body ?? {});
  requireDirectionForTrack(trackId, body);
  res.json(await reopenTrackDirection(trackId, req.params.id, body));
}));

// Approve one direction's packaged candidate; the 8th approval freezes the
// finalized walk set (immutable — 409 on later generate/approve).
router.post('/:id/walk/approve', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteWalkApproveSchema, req.body);
  res.json(await approveWalkDirection(req.params.id, body));
}));

// Un-freeze a finalized walk set so it can be revised in place (#2933
// follow-up): removes the frozen walk-set file and re-opens every direction,
// preserving the rendered clips. 409s a source-pipeline import that has no clips
// to re-derive from, unless the body's `acknowledgeNoClips` overrides it.
router.post('/:id/walk/unlock', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteWalkUnlockSchema, req.body || {});
  res.json(await unlockWalkSet(req.params.id, body));
}));

// Re-open ONE approved direction (finer-grained than unlock) so it can be
// regenerated/reprocessed/re-approved — the user noticed one walk is too fast
// or wrong. Un-finalizes a frozen set but keeps other directions' approvals.
// A clipless source import accepts the same informed acknowledgement as unlock.
router.post('/:id/walk/reopen', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteWalkReopenSchema, req.body);
  res.json(await reopenWalkDirection(req.params.id, body));
}));

// Pin the walk track's cycle target for the whole set (#2985) — the deliberate
// set-level action that replaces the old per-render frame-count/fps sliders.
// 409s when the publish binding's runtime contract pins a different value.
router.put('/:id/walk/target', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteWalkTargetSchema, req.body);
  res.json(await setWalkTarget(req.params.id, body));
}));

// Re-run the deterministic postprocess for a run whose video already landed
// (crash recovery / determinism verification). No AI call involved.
router.post('/:id/walk/postprocess', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteWalkPostprocessSchema, req.body);
  res.json(await rerunWalkPostprocess(req.params.id, body));
}));

// Every frame the run's source video produced (#2980), the cycle window the
// packer selected out of them, and which became packed columns — the Loop
// Trimmer's window onto the raw intermediates `listSpriteAssets` excludes.
// Strictly read-only. Multi-segment, so it can't be captured by the `/:id` GET.
router.get('/:id/walk/runs/:runId/source-frames', asyncHandler(async (req, res) => {
  const { runId } = validateRequest(spriteWalkSourceFramesParamsSchema, req.params);
  res.json(await getWalkSourceFrames(req.params.id, runId));
}));

// Re-extract a run's raw frames from the clip already on disk, then return the
// same payload. Separate from the GET because the importer never copies `raw/`,
// so every imported run would otherwise spawn an ffmpeg decode (~96 PNGs) just
// from rendering the trimmer — this keeps the work behind an explicit click. No
// AI call; deterministic ffmpeg only.
//
// Deliberately NOT gated on an unfinalized set, unlike its neighbours: it writes
// only re-derivable intermediates into the run's own `raw/` directory and
// touches no packaged artifact, manifest or record — and inspecting a finalized
// direction's source frames is exactly how the user decides whether to unlock it
// at all. The immutability guards stay where they matter, on the ops that change
// what the atlas compiles.
router.post('/:id/walk/runs/:runId/source-frames/extract', asyncHandler(async (req, res) => {
  const { runId } = validateRequest(spriteWalkSourceFramesParamsSchema, req.params);
  res.json(await getWalkSourceFrames(req.params.id, runId, { extract: true }));
}));

// Non-destructive loop trim: re-pack enabled frames from a packed strip into
// a versioned trimmed strip + preview GIF. Never mutates the source atlas.
router.post('/:id/walk/trim', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteWalkTrimSchema, req.body);
  res.status(201).json(await saveLoopTrim(req.params.id, body));
}));

// Phase 4 (#2898): atlas compile + publish-to-managed-app. Compile is
// deterministic local work (no AI call); publish additionally requires a
// configured binding and is the only path that writes outside data/.
router.post('/:id/atlas/compile', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteAtlasCompileSchema, req.body ?? {});
  res.json(await compileAtlas(req.params.id, body));
}));

// Set (or clear, with binding: null) the publish binding. App existence and
// path anchoring are validated here so a bad binding fails at save time, not
// at publish time.
router.put('/:id/publish-binding', asyncHandler(async (req, res) => {
  const { binding } = validateRequest(z.object({ binding: spritePublishBindingSchema }), req.body);
  res.json(await setPublishBinding(req.params.id, binding));
}));

router.post('/:id/atlas/publish', asyncHandler(async (req, res) => {
  const body = validateRequest(spriteAtlasPublishSchema, req.body ?? {});
  res.json(await publishAtlas(req.params.id, body));
}));

// Chroma-key changes route through patchSpriteRecord, which re-checks the
// lock state inside the same per-record write tail as `/reference/lock`
// (409 CHROMA_KEY_LOCKED after the main freezes).
router.patch('/:id', asyncHandler(async (req, res) => {
  const patch = validateRequest(spriteRecordUpdateSchema, req.body);
  res.json(await patchSpriteRecord(req.params.id, patch));
}));

// Delete one on-disk asset — an old runtime atlas version (PNG + manifest
// removed together) or a superseded reference/candidate render — by its
// record-relative `path`. Refuses the live atlas + the state index files;
// confinement and the per-record write tail live in the service.
router.delete('/:id/assets', asyncHandler(async (req, res) => {
  const { path } = validateRequest(spriteAssetDeleteSchema, req.query);
  res.json(await deleteSpriteAsset(req.params.id, path));
}));

router.delete('/:id', asyncHandler(async (req, res) => {
  res.json(await deleteRecord(req.params.id));
}));

export default router;