Cli.razor

@page "/cli"
@inherits LocalizedComponentBase
<PageTitle>@(Fr ? "CLI & MSBuild — Settex" : "CLI & MSBuild — Settex")</PageTitle>

<h1>CLI &amp; MSBuild</h1>
<p class="lead">@(Fr ? "Compilez des fichiers .settex en ligne de commande, ou automatiquement dans un build." : "Compile .settex files from the command line, or automatically as part of a build.")</p>

<h2 id="cli">CLI</h2>
<p>@(Fr ? "Installez l'outil global :" : "Install the global tool:")</p>
<CodeBlock Lang="bash" Code="dotnet tool install --global Settex.Cli" />

<p>@(Fr ? "Compilez un fichier — la sortie va dans le répertoire courant par défaut, ou dans un dossier avec " : "Compile a file — output goes into the current directory by default, or into a directory with ")<code>-o</code> :</p>
<CodeBlock Lang="bash" Code="@CliUsage" />

<p>@(Fr ? "La CLI produit des diagnostics précis et cliquables avec fichier, ligne et colonne :" : "The CLI reports precise, clickable diagnostics with file, line and column:")</p>
<CodeBlock Lang="text" Code="@("appsettings.settex(12,5): error: Expected '=' after path")" />

<h2 id="msbuild">@(Fr ? "Intégration MSBuild" : "MSBuild integration")</h2>
<p>
    @(Fr
        ? "Ajoutez le paquet Settex.Build et chaque fichier *.settex du projet est compilé au build. Les diagnostics remontent comme erreurs/avertissements MSBuild (code SETTEX), donc une config invalide fait échouer le build."
        : "Add the Settex.Build package and every *.settex file in the project is compiled on build. Diagnostics surface as MSBuild errors/warnings (code SETTEX), so a broken config fails the build.")
</p>
<CodeBlock Lang="bash" Code="dotnet add package Settex.Build" />

<h3 id="customise">@(Fr ? "Personnaliser le build" : "Customising the build")</h3>
<CodeBlock Lang="xml" Code="@MsBuildConfig" />

<h2 id="output">@(Fr ? "Sortie & contrôle de version" : "Output & source control")</h2>
<p>
    @(Fr
        ? "Un projet type garde la source .settex sous contrôle de version et laisse le build régénérer le JSON :"
        : "A typical project keeps the .settex source under version control and lets the build regenerate the JSON:")
</p>
<CodeBlock Lang="text" Code="@Structure" />
<p>@(Fr ? "Ajoutez *.settex au contrôle de version et, soit ignorez le JSON généré, soit committez-le pour le déploiement." : "Add *.settex to source control and either ignore the generated JSON or commit it for deployment.")</p>

<h3 id="delta">@(Fr ? "Fichiers d'environnement : deltas" : "Environment files: deltas")</h3>
<p>
    @(Fr
        ? "Par défaut, chaque appsettings.{Env}.json ne contient que les valeurs qui diffèrent de la base — exactement ce que le layering de configuration .NET superpose par-dessus appsettings.json à l'exécution. Les diffs restent petits et lisibles. Passez "
        : "By default, each appsettings.{Env}.json contains only the values that differ from the base — exactly what .NET configuration layers on top of appsettings.json at runtime. Diffs stay small and readable. Pass ")<code>--merged</code>@(Fr ? " (ou " : " (or ")<code>SettexMergeEnvironments</code>@(Fr ? ") pour des fichiers d'environnement complets et auto-suffisants." : ") for full, self-contained environment files.")
</p>

<h3 id="coverage">@(Fr ? "Contrôle de couverture" : "Coverage check")</h3>
<p>
    @(Fr
        ? "Settex avertit quand une clé est définie pour certains environnements mais absente des autres (et de la base) — la dérive typique où l'on ajoute une clé en dev et où l'on oublie la prod. C'est un avertissement, pas une erreur ; désactivez-le avec "
        : "Settex warns when a key is set for some environments but missing from others (and from the base) — the classic drift where you add a key in dev and forget prod. It is a warning, not an error; turn it off with ")<code>--no-coverage-check</code>@(Fr ? " ou " : " or ")<code>SettexCheckCoverage=false</code>.
</p>
<CodeBlock Lang="text" Code="@("appsettings.settex: warning: Key 'DevOnly.Flag' is set in 'Development' but missing from 'Production', and is not in the base settings.")" />
<div class="callout callout-note">
    @(Fr
        ? "Volontairement non signalé : une clé définie dans tous les environnements mais absente de la base. Cette configuration est correcte telle quelle, et le « correctif » évident — inventer une valeur de base — est souvent pire pour ce qui doit être décidé par environnement (chaînes de connexion, endpoints, emplacements de secrets) : une valeur par défaut plausible mais fausse s'appliquerait silencieusement. Le risque différé (« on ajoute un environnement et on oublie la clé ») est déjà couvert : dès que cet environnement existe sans la clé, celle-ci n'est plus dans tous les environnements et l'avertissement se déclenche."
        : "Deliberately not flagged: a key set in every environment but absent from the base. That configuration is correct as it stands, and the obvious \"fix\" — inventing a base default — is often worse for values that must be decided per environment (connection strings, endpoints, secret placeholders): a plausible-looking wrong default would apply silently. The deferred risk (\"someone adds an environment and forgets the key\") is already covered: as soon as that environment exists without the key, the key is no longer in every environment and the warning fires.")
</div>

@code {
    private const string CliUsage = """
        # Compile a file (output next to it)
        settex build appsettings.settex

        # Specify an output directory
        settex build config.settex -o ./output

        # Write full merged config in each env file (default: only overrides)
        settex build appsettings.settex --merged

        # Skip the cross-environment coverage check
        settex build appsettings.settex --no-coverage-check

        # Help
        settex --help
        settex build --help
        """;

    private const string MsBuildConfig = """
        <PropertyGroup>
          <!-- Change output directory (default: project root) -->
          <SettexOutputDirectory>$(MSBuildProjectDirectory)\config</SettexOutputDirectory>

          <!-- Full merged env files instead of overrides-only (default: false) -->
          <SettexMergeEnvironments>false</SettexMergeEnvironments>

          <!-- Warn about keys set in some environments but not others (default: true) -->
          <SettexCheckCoverage>true</SettexCheckCoverage>

          <!-- Disable automatic compilation -->
          <EnableSettexCompilation>false</EnableSettexCompilation>
        </PropertyGroup>

        <!-- Or specify files explicitly -->
        <ItemGroup>
          <SettexFile Include="config\app.settex" />
          <SettexFile Include="config\services.settex" />
        </ItemGroup>
        """;

    private const string Structure = """
        MyProject/
        ├── appsettings.settex            # source (in version control)
        ├── appsettings.json              # generated (base)
        ├── appsettings.Development.json  # generated (dev overrides only)
        ├── appsettings.Production.json   # generated (prod overrides only)
        └── MyProject.csproj
        """;
}