Crafter.Review/interfaces/Crafter.Review-Prompt.cppm

// SPDX-License-Identifier: AGPL-3.0-only
// SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

export module Crafter.Review:Prompt;
import std;
import :Json;

// The system text and the layered prompt: the run layer, shared by every
// process of the run, then the lens layer, shared per lens, then the tail,
// this pass. Byte-identical prefixes are what the shared prompt cache keys
// on, so every literal here is fixed to the byte (the goldens hold them).
export namespace Crafter::Review::Prompt {
    constexpr std::string_view SepLens = "\n\n==================== LENS ====================\n\n";
    constexpr std::string_view SepTail = "\n\n==================== SCOPE OF THIS PASS ====================\n\n";
    constexpr std::string_view SepRun = "\n\n==================== THIS RUN ====================\n\n";

    extern const std::string_view GenericVocab;
    // WHOLE_TEXT['first-repo'] and WHOLE_TEXT['functional'].
    extern const std::string_view WholeFirstRepo;
    extern const std::string_view WholeFunctional;
    extern const std::string_view FunctionalBlockHint;
    extern const std::string_view ShotRules;
    // KIND_HINTS_REPO
    extern const std::string_view HintOutside;
    extern const std::string_view HintAbsent;
    // The block hints of the commit-truth lens (2026-10-31): a message unit,
    // and a unit of a documentation file.
    extern const std::string_view TextBlockHintRepo;
    extern const std::string_view DocBlockHintRepo;
    // SLOT_DUTIES: what a slot pass of a lens covers beyond the slot's
    // question; empty for every other lens and slot.
    std::string_view SlotDuty(std::string_view lensFile, std::string_view unitId);

    // _common-repo.md with the artifact kind filled in.
    std::string SystemText();
    // The lens's charter, read with universal newlines.
    std::string Charter(std::string_view lensFile);

    // INPUTS, the artifact with line numbers, the inventory. trees: as they
    // are spelled to the lens; contextPaths may be empty.
    std::string RunLayer(std::string_view artifactRel, std::string_view base, std::string_view date, std::span<const std::string> trees, std::string_view hash,
                         std::span<const std::string> lines, const Json& units, std::span<const std::string> contextPaths = {},
                         std::string_view repoName = "the repository");

    // APPLICATION UNDER TEST: what the processes of a lens with the browser
    // environment are told about the running application — from the
    // consumer's functional config, the login fixture the driver found and the
    // TOTP helper's exact command. slots: the stacks are the bring-up's
    // slots, one per pass, and this block, shared by every pass of the lens,
    // names none of them; the pass's own is in its user message (StackText).
    // A nullopt fixture or command prints as None.
    std::string AppBlock(const Json& functional, const std::optional<std::string>& loginFixture = std::nullopt,
                         const std::optional<std::string>& totpCommand = std::nullopt, bool slots = false);
    // STACK FOR THIS PASS: the slot a pass holds, in its user message, so
    // the system prompt every pass of the lens shares stays byte-identical.
    std::string StackText(const Json& stack, const std::optional<std::string>& totpCommand);
    // DATABASE UNDER TEST: the exact helper command (the URL stays in the
    // driver's broker, never here), what the driver checked before the gate
    // (dbUser: the role of the stacks' connections, nullopt when they differ;
    // bypass: whether that role bypasses row-level security, nullopt says
    // nothing), what one call is, how to act as an API caller, the limits,
    // the evidence, the owner's notes.
    std::string DbBlock(const Json& supabase, std::string_view sqlCommand, const std::optional<std::string>& dbUser, bool withApp = false,
                        const std::optional<std::string>& checked = std::nullopt, std::optional<bool> bypass = std::nullopt);
    // The charter, the application and database blocks when there are
    // any, the dispositions, the whole pass's summary.
    std::string LensLayer(std::string_view lensFile, std::string_view charterText, std::string_view dispositionsBlock, std::string_view app = {},
                          std::string_view wholeSummary = {}, std::string_view db = {});
    // The scope of one pass: a whole pass's units, a slot's question, or a
    // block's unit text.
    std::string Tail(const Json& job, const Json& units, std::span<const std::string> lines, std::string_view wholeSummary = {});
    std::string BudgetLine(const Json& job);
    // The appended system prompt of a pass: the common charter text, the run
    // layer and the lens layer, byte-identical for every pass of a lens in a
    // run.
    std::string SystemPrompt(std::string_view systemText, std::string_view run, std::string_view lens);
    // The stdin user message of a pass: only what differs between passes. A
    // null job adds no budget line.
    std::string UserPrompt(std::string_view tail, const Json& job = nullptr, std::string_view stack = {});
}