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

10.9 KB
Raw Blame
/**
 * Decks routes — playing-card / tarot deck designer (Create → Decks).
 *
 * CRUD on the deck + its cards, the stateless sample-design analysis
 * (vision → proposed style guide, persisted only through `/samples`), the
 * casting + prompt-writing pass, and single/batch card rendering through the
 * shared media queue.
 */

import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { validateRequest } from '../lib/validation.js';
import {
  deckAddSampleSchema,
  deckAnalyzeSampleSchema,
  deckCardUpdateSchema,
  deckCreateSchema,
  deckGeneratePromptsSchema,
  deckRenderSchema,
  deckUpdateSchema,
} from '../lib/deckValidation.js';
import { resolveGalleryImageOrThrow } from './universeBuilder/shared.js';
import { resolveLlmRoutePin } from '../lib/llmRoutePin.js';
import { attachClient as attachPromptProgressClient, beginPromptProgress, emitPromptProgress, finishPromptProgress } from '../services/deckPromptProgress.js';

// Services load on first request, not at route-module import: the deck graph
// reaches the DB, the prompt runner and the media queue, none of which a
// route-only consumer needs instantiated (server/AGENTS.md "Import scoping").
const decks = () => import('../services/decks.js');
const styleAnalysis = () => import('../services/deckStyleAnalysis.js');
const prompts = () => import('../services/deckPrompts.js');
const render = () => import('../services/deckRender.js');

const router = Router();

// Ids are UUIDs minted by the service; validating up front turns a malformed
// id into a 400 instead of a Postgres cast error surfacing as a 500.
const deckParams = z.object({ id: z.uuid() });
const cardParams = deckParams.extend({ cardId: z.uuid() });
const sampleParams = deckParams.extend({ sampleId: z.string().trim().min(1).max(200) });
const deckId = (req) => validateRequest(deckParams, req.params).id;
const cardIds = (req) => validateRequest(cardParams, req.params);

router.get('/', asyncHandler(async (_req, res) => {
  const { listDecks } = await decks();
  res.json(await listDecks());
}));

router.post('/', asyncHandler(async (req, res) => {
  const body = validateRequest(deckCreateSchema, req.body ?? {});
  const { createDeck } = await decks();
  res.status(201).json(await createDeck(body));
}));

router.get('/:id', asyncHandler(async (req, res) => {
  const { getDeck } = await decks();
  res.json(await getDeck(deckId(req)));
}));

router.patch('/:id', asyncHandler(async (req, res) => {
  const body = validateRequest(deckUpdateSchema, req.body ?? {});
  const { updateDeck } = await decks();
  res.json(await updateDeck(deckId(req), body));
}));

router.delete('/:id', asyncHandler(async (req, res) => {
  const { deleteDeck } = await decks();
  res.json(await deleteDeck(deckId(req)));
}));

router.patch('/:id/cards/:cardId', asyncHandler(async (req, res) => {
  const { id, cardId } = cardIds(req);
  const body = validateRequest(deckCardUpdateSchema, req.body ?? {});
  const { updateCard } = await decks();
  res.json(await updateCard(id, cardId, body));
}));

// Stateless review step: analyze a gallery image against the deck's current
// style guide and return a proposal + diff. Persistence happens through
// POST /:id/samples once the user picks "add" or "adopt + add".
router.post('/:id/analyze-sample', asyncHandler(async (req, res) => {
  const body = validateRequest(deckAnalyzeSampleSchema, req.body ?? {});
  const [{ getDeck }, { analyzeDeckSample }] = await Promise.all([decks(), styleAnalysis()]);
  const deck = await getDeck(deckId(req));
  const { imageFilename, imagePath } = resolveGalleryImageOrThrow(body.image);
  // Vision needs an image-capable API provider, which the deck's prompt pin
  // (a text job) need not be — so the picker in the modal is the only source.
  res.json(await analyzeDeckSample({
    deck, imagePath, imageFilename, title: body.title,
    providerId: body.providerId || undefined, model: body.model || undefined, effort: body.effort || undefined,
  }));
}));

router.post('/:id/samples', asyncHandler(async (req, res) => {
  const body = validateRequest(deckAddSampleSchema, req.body ?? {});
  const { addSample } = await decks();
  res.json(await addSample(deckId(req), body.sample, { adopt: body.adopt }));
}));

router.delete('/:id/samples/:sampleId', asyncHandler(async (req, res) => {
  const { id, sampleId } = validateRequest(sampleParams, req.params);
  const { removeSample } = await decks();
  res.json(await removeSample(id, sampleId));
}));

// Casting (universe-linked decks) + prompt writing in one user action. The
// casting pass runs only when a universe is linked, `cast` is on, and at least
// one targeted card is still uncast — so re-running to fill new prompts doesn't
// re-shuffle an assignment the user already accepted.
router.post('/:id/generate-prompts', asyncHandler(async (req, res) => {
  const body = validateRequest(deckGeneratePromptsSchema, req.body ?? {});
  const [{ getDeck, applyCardGenerations }, { castDeckFromUniverse, generateDeckCardPrompts, PROMPTS_PER_CALL }] = await Promise.all([decks(), prompts()]);
  const deck = await getDeck(deckId(req));
  // Per-call choice over the deck's stored pin; a provider switch drops the
  // pinned model/effort rather than carrying them across providers.
  const { providerId, model, effort } = resolveLlmRoutePin(deck.promptLlm, body);
  const llm = { providerId: providerId || undefined, model: model || undefined, effort: effort || undefined };
  const wanted = Array.isArray(body.cardIds) && body.cardIds.length ? new Set(body.cardIds) : null;
  let roster = deck.cards;
  const targetIds = new Set(roster.filter((c) => (!wanted || wanted.has(c.id)) && (body.overwrite || !c.prompt)).map((c) => c.id));
  if (!targetIds.size) {
    throw new ServerError('Every selected card already has a prompt — enable overwrite to rewrite them.', {
      status: 400, code: 'DECK_NO_PROMPT_TARGETS',
    });
  }

  // Live progress for this run (see services/deckPromptProgress.js).
  // The GET may arrive before or after this POST. Reserve the channel here so
  // every emitted frame is retained for a late subscriber; generation is still
  // advisory and never waits on an SSE client.
  const emit = (payload) => emitPromptProgress(deck.id, payload);
  const finish = (payload) => finishPromptProgress(deck.id, payload);

  let universe = null;
  let cast = null;
  if (!beginPromptProgress(deck.id)) {
    throw new ServerError('Prompt generation is already running for this deck.', {
      status: 409, code: 'DECK_PROMPT_GENERATION_IN_PROGRESS',
    });
  }
  try {
    emit({ type: 'phase', deckId: deck.id, phase: 'preparing', label: 'Preparing prompt generation…' });
    if (deck.universeId) {
      const { getUniverse } = await import('../services/universeBuilder.js');
      universe = await getUniverse(deck.universeId).catch(() => null);
      if (universe && body.cast && roster.some((c) => targetIds.has(c.id) && !c.canonRef)) {
        emit({ type: 'phase', deckId: deck.id, phase: 'casting', label: 'Casting the universe onto the cards…' });
        cast = await castDeckFromUniverse({ deck, cards: roster, universe, ...llm });
        // Only cards not yet cast take an assignment; a user-accepted link stays.
        const uncast = new Set(roster.filter((c) => !c.canonRef).map((c) => c.id));
        const applied = new Map(cast.assignments.filter((a) => uncast.has(a.cardId)).map((a) => [a.cardId, a.canonRef]));
        await applyCardGenerations(deck.id, [...applied].map(([cardId, canonRef]) => ({ cardId, canonRef })));
        roster = roster.map((c) => (applied.has(c.id) ? { ...c, canonRef: applied.get(c.id) } : c));
        emit({ type: 'phase', deckId: deck.id, phase: 'cast', label: 'Casting done — writing prompts…', assigned: cast.assignments.filter((a) => a.canonRef).length });
      }
    }
    const targets = roster.filter((c) => targetIds.has(c.id));
    const perCall = Number.isFinite(PROMPTS_PER_CALL) && PROMPTS_PER_CALL > 0 ? PROMPTS_PER_CALL : 16;
    const chunks = Math.max(1, Math.ceil(targets.length / perCall));
    emit({ type: 'start', deckId: deck.id, requested: targets.length, chunks, at: new Date().toISOString() });

    // Prompts persist chunk by chunk, so a chunk that fails mid-deck (a model
    // that returns bad JSON on its third call) leaves the earlier cards written.
    let appliedCount = 0;
    let chunkIndex = 0;
    const byId = new Map(targets.map((c) => [c.id, c]));
    const generated = await generateDeckCardPrompts({
      deck, roster, targets, universe, ...llm,
      onBatchStart: ({ chunk, chunks: batchCount }) => emit({
        type: 'batch-start', deckId: deck.id, chunk, chunks: batchCount,
        written: appliedCount, requested: targets.length,
      }),
      onActivity: ({ chunk, chunks: batchCount }) => emit({
        type: 'activity', deckId: deck.id, chunk, chunks: batchCount,
        written: appliedCount, requested: targets.length,
      }),
      onChunk: async (chunk, batch) => {
        chunkIndex = Number.isFinite(batch?.chunk) ? batch.chunk : chunkIndex + 1;
        const batchCount = Number.isFinite(batch?.chunks) ? batch.chunks : chunks;
        const cardsWritten = chunk.length
          ? await applyCardGenerations(deck.id, chunk)
          : 0;
        appliedCount += cardsWritten;
        emit({
          type: 'chunk', deckId: deck.id, chunk: chunkIndex, chunks: batchCount,
          written: appliedCount, requested: targets.length,
          cardsWritten,
          keys: chunk.map((e) => byId.get(e.cardId)?.key || null).filter(Boolean),
        });
      },
    });
    finish({
      type: 'complete', deckId: deck.id, written: appliedCount, requested: targets.length,
      completedAt: new Date().toISOString(),
    });
    res.json({
      deck: await getDeck(deck.id),
      written: appliedCount,
      requested: targets.length,
      cast: cast ? cast.assignments.filter((a) => a.canonRef).length : 0,
      llm: generated.llm,
    });
  } catch (error) {
    finish({ type: 'error', deckId: deck.id, error: (error?.message || String(error)).slice(0, 1000) });
    throw error;
  }
}));

// Live progress for the POST above. Attaching OPENS the channel, so the
// client can subscribe before (or concurrently with) the generate POST
// without racing it — and generation runs unchanged when nobody listens.
router.get('/:id/generate-prompts/progress', (req, res) => {
  attachPromptProgressClient(deckId(req), res);
});

router.post('/:id/render', asyncHandler(async (req, res) => {
  const body = validateRequest(deckRenderSchema, req.body ?? {});
  const { renderDeckCards } = await render();
  res.json(await renderDeckCards(deckId(req), body));
}));

router.post('/:id/cards/:cardId/render', asyncHandler(async (req, res) => {
  const { id, cardId } = cardIds(req);
  const body = validateRequest(deckRenderSchema.omit({ cardIds: true, onlyMissing: true }), req.body ?? {});
  const { renderDeckCards } = await render();
  res.json(await renderDeckCards(id, { ...body, cardIds: [cardId] }));
}));

export default router;