From ffb139b83092b93f4332dfae5409b83aafa8d22e Mon Sep 17 00:00:00 2001 From: Lewan24 Date: Tue, 16 Sep 2025 12:10:55 +0200 Subject: [PATCH 01/19] add file to automate building and punhing to docker hub repo. Modify docker-compose to use image from dockerhub --- DbBackupService/buildAndDeployDocker.bat | 3 +++ DbBackupService/docker-compose.yml | 31 +++++++++++++++--------- 2 files changed, 23 insertions(+), 11 deletions(-) create mode 100644 DbBackupService/buildAndDeployDocker.bat diff --git a/DbBackupService/buildAndDeployDocker.bat b/DbBackupService/buildAndDeployDocker.bat new file mode 100644 index 0000000..13b0ec6 --- /dev/null +++ b/DbBackupService/buildAndDeployDocker.bat @@ -0,0 +1,3 @@ +docker build -t lewan24/octobackup:latest -f ./Src/Bootstraper/Server/Server.Api/Dockerfile . + +docker push lewan24/octobackup:latest \ No newline at end of file diff --git a/DbBackupService/docker-compose.yml b/DbBackupService/docker-compose.yml index e2b1169..663bf82 100644 --- a/DbBackupService/docker-compose.yml +++ b/DbBackupService/docker-compose.yml @@ -1,25 +1,34 @@ services: - server.api: - image: server.api + octobackup: + # local testing + #image: server.api + image: lewan24/octobackup container_name: octobackup restart: always - build: - context: . - dockerfile: Src/Bootstraper/Server/Server.Api/Dockerfile + # local testing + #build: + #context: . + #dockerfile: Src/Bootstraper/Server/Server.Api/Dockerfile ports: - "10000:80" - "10443:443" environment: ASPNETCORE_ENVIRONMENT: Production ASPNETCORE_URLS: "https://+;http://+" - Kestrel__Certificates__Default__Path: "/app/Certificate/OctoBackupCert.pfx" # your cert, could be anything to only run if you use proxy - Kestrel__Certificates__Default__Password: "Password" # generated cert password + # your cert, could be anything to only run if you use proxy + Kestrel__Certificates__Default__Path: "/app/Certificate/OctoBackupCert.pfx" + # generated cert password + Kestrel__Certificates__Default__Password: "Password" # \/ change on production - CRYPTO_KEY: "C5Znh9Rwota8gSeeTLCMn4ag0OvD5vI9aj0me39/G0g=" # base64 crypto key used to encrypt data + # base64 crypto key used to encrypt data + CRYPTO_KEY: "C5Znh9Rwota8gSeeTLCMn4ag0OvD5vI9aj0me39/G0g=" volumes: - - ./certs/:/app/Certificate/:ro # certificate location - #- serviceDb:/db # local database with users, app data, settings etc. - #- backups:/backups # directory where all backups made are stored. You can bind it to external server + # certificate location + - ./certs/:/app/Certificate/:ro + # local database with users, app data, settings etc. + #- serviceDb:/db + # directory where all backups made are stored. You can bind it to external server + #- backups:/backups # uncomment to bind local db and backups directories #volumes: From 579a819da5ef4a5a04dc5bdd9a3a1b033133e9eb Mon Sep 17 00:00:00 2001 From: Lewan24 Date: Tue, 16 Sep 2025 12:41:26 +0200 Subject: [PATCH 02/19] Update script --- DbBackupService/buildAndDeployDocker.bat | 1 - 1 file changed, 1 deletion(-) diff --git a/DbBackupService/buildAndDeployDocker.bat b/DbBackupService/buildAndDeployDocker.bat index 13b0ec6..44d5dd6 100644 --- a/DbBackupService/buildAndDeployDocker.bat +++ b/DbBackupService/buildAndDeployDocker.bat @@ -1,3 +1,2 @@ docker build -t lewan24/octobackup:latest -f ./Src/Bootstraper/Server/Server.Api/Dockerfile . - docker push lewan24/octobackup:latest \ No newline at end of file From 5bd0bed591d96fad3cab7ed3ee2af6789a16b031 Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Fri, 10 Oct 2025 20:28:03 +0200 Subject: [PATCH 03/19] Update all nuget packages --- .../Bootstraper/Client/Client.UI/Client.UI.csproj | 12 ++++++------ .../Bootstraper/Server/Server.Api/Server.Api.csproj | 10 +++++----- .../Modules.Administration.Api.csproj | 4 ++-- .../Modules.Administration.Application.csproj | 8 ++++---- .../Modules.Administration.Shared.csproj | 2 +- .../Modules.Auth.Api/Modules.Auth.Api.csproj | 6 +++--- .../Modules.Auth.Application.csproj | 10 +++++----- .../Modules.Auth.Core/Modules.Auth.Core.csproj | 2 +- .../Modules.Auth.Infrastructure.csproj | 10 +++++----- .../Modules.Auth.Shared/Modules.Auth.Shared.csproj | 6 +++--- .../Modules.Backup.Api/Modules.Backup.Api.csproj | 2 +- .../Modules.Backup.Application.csproj | 8 ++++---- .../Modules.Backup.Core/Modules.Backup.Core.csproj | 4 ++-- .../Modules.Backup.Infrastructure.csproj | 10 +++++----- .../Modules.Crypto.Api/Modules.Crypto.Api.csproj | 2 +- .../Modules.Crypto.Application.csproj | 4 ++-- .../Shared/Modules.Shared/Modules.Shared.csproj | 2 +- 17 files changed, 51 insertions(+), 51 deletions(-) diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj index d69e034..dc43ea9 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj @@ -8,13 +8,13 @@ - - + + - - - - + + + + diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj index 47d9e58..d717a60 100644 --- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj +++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj @@ -11,16 +11,16 @@ - - - + + + all runtime; build; native; contentfiles; analyzers; buildtransitive - + - + diff --git a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj index 3076d4e..6b87ce1 100644 --- a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj +++ b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj @@ -7,8 +7,8 @@ - - + + diff --git a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj index 61d6c1b..2ea4e10 100644 --- a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj +++ b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj @@ -7,10 +7,10 @@ - - - - + + + + diff --git a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj index a18c998..23e7245 100644 --- a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj +++ b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj @@ -7,7 +7,7 @@ - + diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj index 2d55a5f..d39bca7 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj @@ -7,9 +7,9 @@ - - - + + + diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj index 9e9608e..19dc069 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj @@ -7,11 +7,11 @@ - - - - - + + + + + diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj index 16137a8..ff8066c 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj @@ -7,7 +7,7 @@ - + diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj index d7e62da..c2987fc 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj @@ -7,14 +7,14 @@ - - - + + + all runtime; build; native; contentfiles; analyzers; buildtransitive - - + + all runtime; build; native; contentfiles; analyzers; buildtransitive diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj index ad3439f..7a9ec3b 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj @@ -8,9 +8,9 @@ - - - + + + diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj index b4150cb..ff72da4 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj @@ -7,7 +7,7 @@ - + diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj index 97cc065..5a6ccb8 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj @@ -7,11 +7,11 @@ - - - + + + - + diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj index 914af75..88eacff 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj @@ -11,8 +11,8 @@ - - + + diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj index 01b3154..1c8e642 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj @@ -7,17 +7,17 @@ - - + + all runtime; build; native; contentfiles; analyzers; buildtransitive - - + + all runtime; build; native; contentfiles; analyzers; buildtransitive - + diff --git a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj index 34e04cd..487f897 100644 --- a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj +++ b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj @@ -7,7 +7,7 @@ - + diff --git a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj index c2de560..240f615 100644 --- a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj +++ b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj @@ -7,8 +7,8 @@ - - + + diff --git a/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj b/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj index b86eab4..289af4f 100644 --- a/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj +++ b/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj @@ -7,7 +7,7 @@ - + From db604a8c9f033514baa2565c936b6e6d028da5c9 Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Fri, 10 Oct 2025 20:53:16 +0200 Subject: [PATCH 04/19] Update dockerfile for better security image --- DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile b/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile index 9894e5b..a39765d 100644 --- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile +++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile @@ -1,5 +1,5 @@ # ============= BUILD STAGE ============= -FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build +FROM mcr.microsoft.com/dotnet/sdk:9.0-bookworm-slim AS build ARG BUILD_CONFIGURATION=Release WORKDIR /src @@ -18,7 +18,7 @@ RUN dotnet publish "Server.Api.csproj" \ # ============= RUNTIME STAGE ============= -FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS runtime +FROM mcr.microsoft.com/dotnet/aspnet:9.0-bookworm-slim AS runtime WORKDIR /app From 50dc548bbe16b4a1c60df15b6a57db6092e09294 Mon Sep 17 00:00:00 2001 From: artur Date: Mon, 13 Oct 2025 10:01:35 +0200 Subject: [PATCH 05/19] Fix ports range Fix performed backup localization Fix db localization --- .../Dialogs/Servers/CreateServerDialog.razor | 8 +- .../Dialogs/Servers/EditServerDialog.razor | 8 +- .../Services/DbBackupService.cs | 10 +- .../Entities/DbContext/DbServerConnection.cs | 2 +- .../Entities/DbContext/DbServerTunnel.cs | 6 +- .../BackupsDbContextModelSnapshot.cs | 10 +- ...1013075224_ChangeIntsToUShorts.Designer.cs | 291 ++++++++++++++++++ .../20251013075224_ChangeIntsToUShorts.cs | 22 ++ .../Dtos/ServerConnectionDto.cs | 4 +- .../Dtos/ServerTunnelDto.cs | 9 +- .../Shared/Modules.Shared/Common/DbCommon.cs | 6 +- 11 files changed, 347 insertions(+), 29 deletions(-) create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor index 86a1156..e95d3ad 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor @@ -29,7 +29,7 @@ For="@(() => _server.ServerHost)"/> - - - - - - - - error => logger.LogWarning(error) ); - if (!string.IsNullOrWhiteSpace(compressedFilename)) + if (!string.IsNullOrWhiteSpace(newDbBackup.FilePath)) logger.LogInformation("Successfully created and compressed backup: [{Database}], [{ZipFile}]", - db.GetDatabaseName(), compressedFilename); + db.GetDatabaseName(), newDbBackup.FilePath); return new Success(); } diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs index ac4c39b..f7babfa 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs @@ -8,7 +8,7 @@ public sealed record DbServerConnection public bool IsDisabled { get; set; } public string ConnectionName { get; set; } = "Example"; public required string ServerHost { get; set; } - public required short ServerPort { get; set; } + public required ushort ServerPort { get; set; } public required string DbName { get; set; } public DatabaseType DbType { get; set; } = DatabaseType.MySql; public required string DbUser { get; set; } diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs index 45912c1..2f0cff7 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs @@ -4,15 +4,15 @@ public sealed record DbServerTunnel { public Guid Id { get; init; } = Guid.CreateVersion7(); public required string ServerHost { get; set; } - public int SshPort { get; set; } = 22; + public ushort SshPort { get; set; } = 22; public required string Username { get; set; } public bool UsePasswordAuth { get; set; } = true; public string? Password { get; set; } public string? PrivateKeyContent { get; set; } public string? PrivateKeyPassphrase { get; set; } - public int LocalPort { get; set; } + public ushort LocalPort { get; set; } public required string RemoteHost { get; set; } - public int RemotePort { get; set; } + public ushort RemotePort { get; set; } public string? Description { get; set; } public bool IsActive { get; set; } } \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs index 8aa73a4..712d263 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs @@ -15,7 +15,7 @@ partial class BackupsDbContextModelSnapshot : ModelSnapshot protected override void BuildModel(ModelBuilder modelBuilder) { #pragma warning disable 612, 618 - modelBuilder.HasAnnotation("ProductVersion", "9.0.8"); + modelBuilder.HasAnnotation("ProductVersion", "9.0.9"); modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b => { @@ -125,7 +125,7 @@ protected override void BuildModel(ModelBuilder modelBuilder) .IsRequired() .HasColumnType("TEXT"); - b.Property("ServerPort") + b.Property("ServerPort") .HasColumnType("INTEGER"); b.Property("TunnelId") @@ -148,7 +148,7 @@ protected override void BuildModel(ModelBuilder modelBuilder) b.Property("IsActive") .HasColumnType("INTEGER"); - b.Property("LocalPort") + b.Property("LocalPort") .HasColumnType("INTEGER"); b.Property("Password") @@ -164,14 +164,14 @@ protected override void BuildModel(ModelBuilder modelBuilder) .IsRequired() .HasColumnType("TEXT"); - b.Property("RemotePort") + b.Property("RemotePort") .HasColumnType("INTEGER"); b.Property("ServerHost") .IsRequired() .HasColumnType("TEXT"); - b.Property("SshPort") + b.Property("SshPort") .HasColumnType("INTEGER"); b.Property("UsePasswordAuth") diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs new file mode 100644 index 0000000..7e41884 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs @@ -0,0 +1,291 @@ +// +using System; +using Microsoft.EntityFrameworkCore; +using Microsoft.EntityFrameworkCore.Infrastructure; +using Microsoft.EntityFrameworkCore.Migrations; +using Microsoft.EntityFrameworkCore.Storage.ValueConversion; +using Modules.Backup.Infrastructure.DbContexts; + +#nullable disable + +namespace Modules.Backup.Infrastructure.Migrations +{ + [DbContext(typeof(BackupsDbContext))] + [Migration("20251013075224_ChangeIntsToUShorts")] + partial class ChangeIntsToUShorts + { + /// + protected override void BuildTargetModel(ModelBuilder modelBuilder) + { +#pragma warning disable 612, 618 + modelBuilder.HasAnnotation("ProductVersion", "9.0.9"); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("AutomaticBackupTestConfigs"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ConfigurationJson") + .HasColumnType("TEXT"); + + b.Property("DbConnectionId") + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("NextBackupDate") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Schedules"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("BackupId") + .HasColumnType("TEXT"); + + b.Property("ErrorMessage") + .HasColumnType("TEXT"); + + b.Property("IsSuccess") + .HasColumnType("INTEGER"); + + b.Property("TestedOn") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("BackupsTests"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("AutoTestBackupsConfigId") + .HasColumnType("TEXT"); + + b.Property("BackupEncryptionKeyHas") + .HasColumnType("TEXT"); + + b.Property("ConnectionName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbPasswd") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbType") + .HasColumnType("INTEGER"); + + b.Property("DbUser") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("IsDisabled") + .HasColumnType("INTEGER"); + + b.Property("IsTunnelRequired") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerPort") + .HasColumnType("INTEGER"); + + b.Property("TunnelId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbConnections"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("Description") + .HasColumnType("TEXT"); + + b.Property("IsActive") + .HasColumnType("INTEGER"); + + b.Property("LocalPort") + .HasColumnType("INTEGER"); + + b.Property("Password") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyContent") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyPassphrase") + .HasColumnType("TEXT"); + + b.Property("RemoteHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("RemotePort") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("SshPort") + .HasColumnType("INTEGER"); + + b.Property("UsePasswordAuth") + .HasColumnType("INTEGER"); + + b.Property("Username") + .IsRequired() + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbServerTunnels"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("CreatedOn") + .HasColumnType("TEXT"); + + b.Property("FilePath") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerConnectionId") + .HasColumnType("TEXT"); + + b.Property("TestId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Backups"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("TimeInDaysToHoldBackups") + .HasColumnType("INTEGER"); + + b.HasKey("Id"); + + b.ToTable("Configurations"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersServers"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnChanges") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnErrors") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedBackups") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedTests") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnSuccessfulBackup") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnUpdates") + .HasColumnType("INTEGER"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersNotificationsSettings"); + }); +#pragma warning restore 612, 618 + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs new file mode 100644 index 0000000..a3d7494 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs @@ -0,0 +1,22 @@ +using Microsoft.EntityFrameworkCore.Migrations; + +#nullable disable + +namespace Modules.Backup.Infrastructure.Migrations +{ + /// + public partial class ChangeIntsToUShorts : Migration + { + /// + protected override void Up(MigrationBuilder migrationBuilder) + { + + } + + /// + protected override void Down(MigrationBuilder migrationBuilder) + { + + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs index 10a682d..c070a9e 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs @@ -8,7 +8,9 @@ public record ServerConnectionDto public Guid Id { get; init; } = Guid.CreateVersion7(); [Required] public string ConnectionName { get; set; } = "Example"; [Required] public required string ServerHost { get; set; } - [Required] public required short ServerPort { get; set; } + [Required] + [Range(0, ushort.MaxValue)] + public required ushort ServerPort { get; set; } [Required] public required string DbName { get; set; } [Required] public DatabaseType DbType { get; set; } = DatabaseType.MySql; [Required] public required string DbUser { get; set; } diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs index 19c2997..0445ff2 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs @@ -16,7 +16,8 @@ public record ServerTunnelDto /// Port serwera SSH (domyślnie 22, w twoim przykładzie 80) /// [Required] - public int SshPort { get; set; } = 22; + [Range(0, ushort.MaxValue)] + public ushort SshPort { get; set; } = 22; /// /// Użytkownik SSH (np. user) @@ -48,7 +49,8 @@ public record ServerTunnelDto /// Lokalny port, na którym wystawiony będzie tunel (np. 8543) /// [Required] - public int LocalPort { get; set; } + [Range(0, ushort.MaxValue)] + public ushort LocalPort { get; set; } /// /// Zdalny host, do którego tunel ma przekierowywać (np. pgsqldomain.com) @@ -60,7 +62,8 @@ public record ServerTunnelDto /// Zdalny port usługi (np. 5432 dla PostgreSQL, 3306 dla MySQL) /// [Required] - public int RemotePort { get; set; } + [Range(0, ushort.MaxValue)] + public ushort RemotePort { get; set; } /// /// Opis tunelu (opcjonalny, do UI) diff --git a/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs b/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs index 226cb54..82e1ea1 100644 --- a/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs +++ b/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs @@ -4,7 +4,7 @@ public static class DbCommon { private static readonly string DbFolder = GetDbDirectory(); - public static readonly string DbPath = Path.Join(DbFolder, "OctoBackup.db"); + public static readonly string DbPath = Path.Join(DbFolder, "Config", "OctoBackup.db"); private static string GetDbDirectory() => Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "OctoBackup"); @@ -13,5 +13,9 @@ public static void CreateDbDirectoryIfNotExists() { if (!Directory.Exists(DbFolder)) Directory.CreateDirectory(DbFolder); + + var configDir = Path.GetDirectoryName(DbPath) ?? DbFolder; + if (!Directory.Exists(configDir)) + Directory.CreateDirectory(configDir); } } \ No newline at end of file From d1258fe361cd77f187a6e55832edf1b146e8a9db Mon Sep 17 00:00:00 2001 From: artur Date: Mon, 13 Oct 2025 10:26:53 +0200 Subject: [PATCH 06/19] Fix downloading backups --- .../Modules.Backup.Application/Services/DbBackupService.cs | 6 +++++- DbBackupService/buildAndDeployDocker.bat | 0 2 files changed, 5 insertions(+), 1 deletion(-) mode change 100644 => 100755 DbBackupService/buildAndDeployDocker.bat diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs index e73e496..cbb8424 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs @@ -211,7 +211,11 @@ public async Task, string>> GetAllBackups(string? var fileName = server is not null ? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip" : $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"; - return (backup.FilePath, "application/zip", fileName); + + if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development") + return (backup.FilePath, "application/zip", fileName); + + return (Path.Combine("app", backup.FilePath), "application/zip", fileName); } private async Task> PerformBackup(List serversConnections) diff --git a/DbBackupService/buildAndDeployDocker.bat b/DbBackupService/buildAndDeployDocker.bat old mode 100644 new mode 100755 From 1a31c89aee98a2d53adf10e30a1302975e94aa5c Mon Sep 17 00:00:00 2001 From: artur Date: Mon, 13 Oct 2025 10:36:59 +0200 Subject: [PATCH 07/19] Fix downloading backup --- .../Modules.Backup.Application/Services/DbBackupService.cs | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs index cbb8424..97461dc 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs @@ -212,10 +212,7 @@ public async Task, string>> GetAllBackups(string? ? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip" : $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"; - if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development") - return (backup.FilePath, "application/zip", fileName); - - return (Path.Combine("app", backup.FilePath), "application/zip", fileName); + return (backup.FilePath, "application/zip", fileName); } private async Task> PerformBackup(List serversConnections) From 00421403f06e2eeb21dea6cad252b911eaf3ab3a Mon Sep 17 00:00:00 2001 From: artur Date: Mon, 13 Oct 2025 11:28:52 +0200 Subject: [PATCH 08/19] Fix Downloading final fix --- .../Modules.Backup.Application/Services/DbBackupService.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs index 97461dc..53b4def 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs @@ -212,7 +212,7 @@ public async Task, string>> GetAllBackups(string? ? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip" : $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"; - return (backup.FilePath, "application/zip", fileName); + return (Path.Combine(backup.FilePath), "application/zip", fileName); } private async Task> PerformBackup(List serversConnections) From acc7c574f7268ca010ceef5956337f50413297f4 Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Sat, 25 Oct 2025 23:14:48 +0200 Subject: [PATCH 09/19] Fix backup path for downloading. Implement ssl mode selecting while creating and editing server. Implement selecting ssl mode in servers connections. Add ssl boolean to server connection entity Add migration --- .../Dialogs/Servers/CreateServerDialog.razor | 9 +- .../Dialogs/Servers/EditServerDialog.razor | 9 +- .../Services/DbBackupService.cs | 9 +- .../Services/ServersService.cs | 3 + .../Static/ServerConnectionTester.cs | 8 +- .../Entities/DbContext/DbServerConnection.cs | 1 + .../20251025203420_AddSslToEntity.Designer.cs | 294 ++++++++++++++++++ .../20251025203420_AddSslToEntity.cs | 29 ++ .../BackupsDbContextModelSnapshot.cs | 3 + .../Dtos/ServerConnectionDto.cs | 1 + DbBackupService/docker-composetest.yml | 36 +++ 11 files changed, 393 insertions(+), 9 deletions(-) create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs create mode 100644 DbBackupService/docker-composetest.yml diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor index e95d3ad..283695c 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor @@ -70,11 +70,16 @@ For="@(() => _server.DbPasswd)"/> - - + + + + + @if (_server.IsTunnelRequired) { diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor index 693b629..8485ccd 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor @@ -70,11 +70,16 @@ For="@(() => Server.DbPasswd)"/> - - + + + + + @if (Server.IsTunnelRequired) { diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs index 53b4def..631a27a 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs @@ -211,8 +211,13 @@ public async Task, string>> GetAllBackups(string? var fileName = server is not null ? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip" : $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"; - - return (Path.Combine(backup.FilePath), "application/zip", fileName); + + var filePath = backup.FilePath; + if (!Path.IsPathRooted(filePath)) + filePath = Path.Combine(AppContext.BaseDirectory, filePath); + + logger.LogInformation("Downloading {BackupPath}...", filePath); + return (filePath, "application/zip", fileName); } private async Task> PerformBackup(List serversConnections) diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs index 962eb58..4d9d6c5 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs @@ -76,6 +76,7 @@ public async Task, string>> GetServers(string? i DbName = server.DbName, DbType = server.DbType, DbUser = server.DbUser, + SsL = server.SsL, IsTunnelRequired = server.IsTunnelRequired, AutoTestBackupsConfigId = server.AutoTestBackupsConfigId }; @@ -209,6 +210,7 @@ public async Task> CreateServer(ServerConnectionDto newSe DbType = newServer.DbType, DbUser = newServer.DbUser, DbPasswd = encryptedDbPasswd ?? throw new ArgumentException("Db password can't be null"), + SsL = newServer.SsL, IsTunnelRequired = newServer.IsTunnelRequired, IsDisabled = false }; @@ -345,6 +347,7 @@ public async Task> EditServer(ServerConnectionDto server) dbServer.DbName = server.DbName; dbServer.DbType = server.DbType; dbServer.DbUser = server.DbUser; + dbServer.SsL = server.SsL; if (!string.IsNullOrWhiteSpace(server.DbPasswd)) { diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs index 9ad1f3c..7a7b1f4 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs @@ -80,7 +80,8 @@ internal static class ServerConnectionTester Database = conn.DbName, UserID = conn.DbUser, Password = decryptedDbPasswd, - ConnectionTimeout = 5 + ConnectionTimeout = 5, + SslMode = conn.SsL ? MySqlSslMode.Required : MySqlSslMode.None, }.ToString()), DatabaseType.PostgreSql => new NpgsqlConnection( @@ -92,7 +93,8 @@ internal static class ServerConnectionTester Username = conn.DbUser, Password = decryptedDbPasswd, Timeout = 5, - CommandTimeout = 5 + CommandTimeout = 5, + SslMode = conn.SsL ? SslMode.Require : SslMode.Disable, }.ToString()), DatabaseType.SqlServer => new SqlConnection( @@ -103,7 +105,7 @@ internal static class ServerConnectionTester UserID = conn.DbUser, Password = decryptedDbPasswd, ConnectTimeout = 5, - TrustServerCertificate = true + TrustServerCertificate = conn.SsL }.ToString()), _ => throw new NotSupportedException($"Unsupported DB type: {conn.DbType}") diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs index f7babfa..a12c7a8 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs @@ -13,6 +13,7 @@ public sealed record DbServerConnection public DatabaseType DbType { get; set; } = DatabaseType.MySql; public required string DbUser { get; set; } public required string DbPasswd { get; set; } + public bool SsL { get; set; } = true; public bool IsTunnelRequired { get; set; } public Guid TunnelId { get; set; } public string? BackupEncryptionKeyHas { get; set; } diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs new file mode 100644 index 0000000..b81e3e1 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs @@ -0,0 +1,294 @@ +// +using System; +using Microsoft.EntityFrameworkCore; +using Microsoft.EntityFrameworkCore.Infrastructure; +using Microsoft.EntityFrameworkCore.Migrations; +using Microsoft.EntityFrameworkCore.Storage.ValueConversion; +using Modules.Backup.Infrastructure.DbContexts; + +#nullable disable + +namespace Modules.Backup.Infrastructure.DbContexts.Migrations +{ + [DbContext(typeof(BackupsDbContext))] + [Migration("20251025203420_AddSslToEntity")] + partial class AddSslToEntity + { + /// + protected override void BuildTargetModel(ModelBuilder modelBuilder) + { +#pragma warning disable 612, 618 + modelBuilder.HasAnnotation("ProductVersion", "9.0.9"); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("AutomaticBackupTestConfigs"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ConfigurationJson") + .HasColumnType("TEXT"); + + b.Property("DbConnectionId") + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("NextBackupDate") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Schedules"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("BackupId") + .HasColumnType("TEXT"); + + b.Property("ErrorMessage") + .HasColumnType("TEXT"); + + b.Property("IsSuccess") + .HasColumnType("INTEGER"); + + b.Property("TestedOn") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("BackupsTests"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("AutoTestBackupsConfigId") + .HasColumnType("TEXT"); + + b.Property("BackupEncryptionKeyHas") + .HasColumnType("TEXT"); + + b.Property("ConnectionName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbPasswd") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbType") + .HasColumnType("INTEGER"); + + b.Property("DbUser") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("IsDisabled") + .HasColumnType("INTEGER"); + + b.Property("IsTunnelRequired") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerPort") + .HasColumnType("INTEGER"); + + b.Property("SsL") + .HasColumnType("INTEGER"); + + b.Property("TunnelId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbConnections"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("Description") + .HasColumnType("TEXT"); + + b.Property("IsActive") + .HasColumnType("INTEGER"); + + b.Property("LocalPort") + .HasColumnType("INTEGER"); + + b.Property("Password") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyContent") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyPassphrase") + .HasColumnType("TEXT"); + + b.Property("RemoteHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("RemotePort") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("SshPort") + .HasColumnType("INTEGER"); + + b.Property("UsePasswordAuth") + .HasColumnType("INTEGER"); + + b.Property("Username") + .IsRequired() + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbServerTunnels"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("CreatedOn") + .HasColumnType("TEXT"); + + b.Property("FilePath") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerConnectionId") + .HasColumnType("TEXT"); + + b.Property("TestId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Backups"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("TimeInDaysToHoldBackups") + .HasColumnType("INTEGER"); + + b.HasKey("Id"); + + b.ToTable("Configurations"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersServers"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnChanges") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnErrors") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedBackups") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedTests") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnSuccessfulBackup") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnUpdates") + .HasColumnType("INTEGER"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersNotificationsSettings"); + }); +#pragma warning restore 612, 618 + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs new file mode 100644 index 0000000..d3204e1 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs @@ -0,0 +1,29 @@ +using Microsoft.EntityFrameworkCore.Migrations; + +#nullable disable + +namespace Modules.Backup.Infrastructure.DbContexts.Migrations +{ + /// + public partial class AddSslToEntity : Migration + { + /// + protected override void Up(MigrationBuilder migrationBuilder) + { + migrationBuilder.AddColumn( + name: "SsL", + table: "DbConnections", + type: "INTEGER", + nullable: false, + defaultValue: false); + } + + /// + protected override void Down(MigrationBuilder migrationBuilder) + { + migrationBuilder.DropColumn( + name: "SsL", + table: "DbConnections"); + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs index 712d263..9ccb2e7 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs @@ -128,6 +128,9 @@ protected override void BuildModel(ModelBuilder modelBuilder) b.Property("ServerPort") .HasColumnType("INTEGER"); + b.Property("SsL") + .HasColumnType("INTEGER"); + b.Property("TunnelId") .HasColumnType("TEXT"); diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs index c070a9e..cebe973 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs @@ -15,6 +15,7 @@ public record ServerConnectionDto [Required] public DatabaseType DbType { get; set; } = DatabaseType.MySql; [Required] public required string DbUser { get; set; } public string? DbPasswd { get; set; } + public bool SsL { get; set; } = true; public bool IsTunnelRequired { get; set; } public ServerTunnelDto? Tunnel { get; set; } diff --git a/DbBackupService/docker-composetest.yml b/DbBackupService/docker-composetest.yml new file mode 100644 index 0000000..030a236 --- /dev/null +++ b/DbBackupService/docker-composetest.yml @@ -0,0 +1,36 @@ +services: + octobackup: + # local testing + image: server.api + #image: lewan24/octobackup + container_name: octobackup + restart: always + # local testing + build: + context: . + dockerfile: Src/Bootstraper/Server/Server.Api/Dockerfile + ports: + - "10000:80" + - "10443:443" + environment: + ASPNETCORE_ENVIRONMENT: Production + ASPNETCORE_URLS: "https://+;http://+" + # your cert, could be anything to only run if you use proxy + Kestrel__Certificates__Default__Path: "/app/Certificate/OctoBackupCert.pfx" + # generated cert password + Kestrel__Certificates__Default__Password: "Password" + # \/ change on production + # base64 crypto key used to encrypt data + CRYPTO_KEY: "C5Znh9Rwota8gSeeTLCMn4ag0OvD5vI9aj0me39/G0g=" + volumes: + # certificate location + - ./certs/:/app/Certificate/:ro + # local database with users, app data, settings etc. + - serviceDb:/app/OctoBackup/Config + # directory where all backups made are stored. You can bind it to external server + #- backups:/app/OctoBackup/backups + +# uncomment to bind local db and backups directories +volumes: + serviceDb: + #backups: \ No newline at end of file From 3ddb684def9b8f30c8f49e6c499f8e2b1147c81e Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Sat, 25 Oct 2025 23:27:38 +0200 Subject: [PATCH 10/19] Update docker compose files --- DbBackupService/docker-compose.yml | 8 ++++---- .../{docker-composetest.yml => docker-composedev.yml} | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) rename DbBackupService/{docker-composetest.yml => docker-composedev.yml} (96%) diff --git a/DbBackupService/docker-compose.yml b/DbBackupService/docker-compose.yml index 663bf82..3e1defa 100644 --- a/DbBackupService/docker-compose.yml +++ b/DbBackupService/docker-compose.yml @@ -26,10 +26,10 @@ # certificate location - ./certs/:/app/Certificate/:ro # local database with users, app data, settings etc. - #- serviceDb:/db - # directory where all backups made are stored. You can bind it to external server - #- backups:/backups - + #- serviceDb:/app/OctoBackup/Config + # directory where all backups made are stored. You can bind it to external server + #- backups:/app/OctoBackup/Backups + # uncomment to bind local db and backups directories #volumes: #serviceDb: diff --git a/DbBackupService/docker-composetest.yml b/DbBackupService/docker-composedev.yml similarity index 96% rename from DbBackupService/docker-composetest.yml rename to DbBackupService/docker-composedev.yml index 030a236..7e1f4c1 100644 --- a/DbBackupService/docker-composetest.yml +++ b/DbBackupService/docker-composedev.yml @@ -28,7 +28,7 @@ # local database with users, app data, settings etc. - serviceDb:/app/OctoBackup/Config # directory where all backups made are stored. You can bind it to external server - #- backups:/app/OctoBackup/backups + #- backups:/app/OctoBackup/Backups # uncomment to bind local db and backups directories volumes: From 25118cd806c13c22ac4d2741ac2d53c7ef2b3ad1 Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Sun, 26 Oct 2025 11:28:24 +0100 Subject: [PATCH 11/19] Implement profile panel. Implement changing password and email Change dashboard design for user and admin --- .../Client/Client.UI/Client.UI.csproj | 4 - .../Client.UI/Data/Services/ProfileService.cs | 14 +++ .../AdministrationDashboard.razor | 24 ++-- .../Authorization/Account/ProfileIndex.razor | 113 ++++++++++++++++++ .../{Account => Common}/AuthorizeUser.razor | 1 + .../{Account => Common}/ConfirmPassword.razor | 0 .../{Account => Common}/Login.razor | 0 .../{Account => Common}/Register.razor | 0 .../Client/Client.UI/Pages/Dashboard.razor | 27 ++--- .../Bootstraper/Client/Client.UI/Program.cs | 1 + .../Endpoints/AuthEndpoints.cs | 4 + .../Operations/AuthOperations.cs | 8 ++ .../Interfaces/IAuthService.cs | 1 + .../Services/AuthService.cs | 36 +++++- .../ActionsRequests/ChangeEmailRequest.cs | 13 ++ 15 files changed, 203 insertions(+), 43 deletions(-) create mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs create mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/AuthorizeUser.razor (99%) rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/ConfirmPassword.razor (100%) rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/Login.razor (100%) rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/Register.razor (100%) create mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj index dc43ea9..23f6918 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj @@ -17,10 +17,6 @@ - - - - diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs new file mode 100644 index 0000000..c66b930 --- /dev/null +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs @@ -0,0 +1,14 @@ +using Modules.Auth.Shared.ActionsRequests; +using OneOf; +using OneOf.Types; + +namespace Client.UI.Data.Services; + +public sealed class ProfileService(TokenHttpClientService api) +{ + public async Task> ChangeEmail(ChangeEmailRequest request) + => await api.PostAsync("/api/auth/ChangeEmail", request); + + public async Task>? ChangePassword(ChangePasswordRequest request) + => await api.PostAsync("/api/auth/ChangePassword", request); +} \ No newline at end of file diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor index 47cac85..e36788a 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor @@ -5,55 +5,49 @@ Administration Dashboard - + Panel Administracyjny - + Użytkownicy 124 - - - Grupy uprawnień - 5 - - - + Serwery 18 - + Tunele 7 - + - Backupy + Wykonane Backupy 2 354 - + Średnio backupów w miesiącu 80 - + Ilość zrobionych testów 1743 - + Testy udane 96% diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor new file mode 100644 index 0000000..370b673 --- /dev/null +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor @@ -0,0 +1,113 @@ +@page "/account/profile" + +@using Client.UI.Data.Services +@using Modules.Auth.Shared.ActionsRequests + +@inject AuthStateProvider Auth +@inject ISnackbar SnackBar +@inject ProfileService Profile +@inject NavigationManager NavigationManager + + + + Your Profile + Welcome back, @_userEmail! + + + + + + + + + + Change Email + + + + + + + Update + + + + + + + + + + + + + Change Password + + + + + + + + Update + + + + + + + + +@code { + private string _userEmail = "Loading..."; + + private ChangeEmailRequest _changeEmailRequest = new(); + private ChangePasswordRequest _changePasswordRequest = new(); + + private bool _isChanging; + + protected override async Task OnInitializedAsync() + { + await Auth.AuthorizeUser(returnPageAfterValidPasswordAuthorization: "account-profile"); + + var authState = await Auth.GetAuthenticationStateAsync(); + _userEmail = authState.User.Identity?.Name ?? "Unknown user"; + } + + private async Task ChangeEmail() + { + _isChanging = true; + + var result = await Profile.ChangeEmail(_changeEmailRequest); + + result.Switch( + _ => + { + SnackBar.Add("Email updated successfully. Login again to confirm new email changes.", Severity.Success); + NavigationManager.NavigateTo("/", true); + }, + error => SnackBar.Add(error, Severity.Error) + ); + + _isChanging = false; + } + + private async Task ChangePassword() + { + _isChanging = true; + + var result = await Profile.ChangePassword(_changePasswordRequest)!; + + result.Switch( + _ => SnackBar.Add("Password updated successfully.", Severity.Success), + error => SnackBar.Add(error, Severity.Error) + ); + + _isChanging = false; + } +} diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/AuthorizeUser.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor similarity index 99% rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/AuthorizeUser.razor rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor index e5354e3..0b68a88 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/AuthorizeUser.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor @@ -1,4 +1,5 @@ @page "/authorizeuser" + @using Blazored.LocalStorage @using Client.UI.Data.Interfaces @using Client.UI.Data.Services diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ConfirmPassword.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/ConfirmPassword.razor similarity index 100% rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ConfirmPassword.razor rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/ConfirmPassword.razor diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Login.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Login.razor similarity index 100% rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Login.razor rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Login.razor diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Register.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Register.razor similarity index 100% rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Register.razor rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Register.razor diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor index 9e3f253..7555e0c 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor @@ -5,54 +5,41 @@ Dashboard - + My Dashboard - - Moje Role - Admin, User - - - - - Moje Grupy - Localhost, Domain, Test - - - - Obsługiwane Serwery 4 - + Moje Tunele 2 - + - Backupy + Wykonane Backupy 245 - + Średnio backupów w miesiącu 20 - + Ilość zrobionych testów 180 - + Testy udane 94% diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs b/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs index 47ea4d8..cb12d4a 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs @@ -31,6 +31,7 @@ builder.Services.AddScoped(); builder.Services.AddScoped(); builder.Services.AddScoped(); +builder.Services.AddScoped(); builder.Logging.AddFilter((category, level) => level >= LogLevel.Warning || diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs index cac678d..e33b82a 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs @@ -41,6 +41,10 @@ private static void MapAuthPosts(this RouteGroupBuilder api) api.MapPost("ChangePassword", AuthOperations.ChangePassword) .WithSummary("Change user's password") .AddEndpointFilter(); + + api.MapPost("ChangeEmail", AuthOperations.ChangeEmail) + .WithSummary("Change user's email address") + .AddEndpointFilter(); api.MapPost("CanLogIn", AuthOperations.CanLogIn) .WithSummary("Check if user can be logged in"); diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs index 16bb4c9..07e9b7c 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs @@ -30,6 +30,14 @@ public static Task ChangePassword( { return authService.ChangePassword(context, request); } + + public static Task ChangeEmail( + HttpContext context, + [FromBody] ChangeEmailRequest request, + [FromServices] IAuthService authService) + { + return authService.ChangeEmail(context, request); + } public static Task CanLogIn( HttpContext context, diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs index c3655b9..6c93cd4 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs @@ -8,6 +8,7 @@ public interface IAuthService { Task Login(HttpContext context, LoginRequest? request); Task ChangePassword(HttpContext context, ChangePasswordRequest request); + Task ChangeEmail(HttpContext context, ChangeEmailRequest request); Task CanLogIn(HttpContext context, LoginRequest? request); Task Register(HttpContext context, RegisterRequest request); Task Logout(HttpContext context); diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs index ad30811..1493a6f 100644 --- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs @@ -35,7 +35,7 @@ public async Task Login(HttpContext context, LoginRequest? request) var user = await userManager.FindByEmailAsync(request!.Email); if (user is null) - return Results.NotFound("Taki użytkownik nie istnieje."); + return Results.NotFound("This user does not exist."); await signInManager.SignInAsync(user, request.RememberMe); @@ -54,14 +54,42 @@ public async Task ChangePassword(HttpContext context, ChangePasswordReq if (!IsValidChangePasswordRequest(request, out var error)) return Results.BadRequest(error); - var user = await userManager.FindByEmailAsync(context.User.Identity?.Name!); + var user = await userManager.FindByNameAsync(context.User.Identity?.Name!); if (user is null) - return Results.BadRequest("Nie można znaleźć użytkownika"); + return Results.BadRequest("Can't find user."); var result = await userManager.ChangePasswordAsync(user, request.CurrentPassword, request.NewPassword); return result.Succeeded ? Results.Ok() - : Results.BadRequest("Błąd przy zmianie hasła, sprawdź dane i wymagania."); + : Results.BadRequest("Error while changing password. Check your password and try again."); + } + + public async Task ChangeEmail(HttpContext context, ChangeEmailRequest request) + { + logger.LogInformation("Changing email address for {UserName} to new one: [{NewEmail}]...", context.User.Identity?.Name, request.NewEmail); + + if (string.IsNullOrWhiteSpace(request.NewEmail) || string.IsNullOrWhiteSpace(request.ConfirmNewEmail)) + return Results.BadRequest("Cant process empty email address."); + + if (request.NewEmail != request.ConfirmNewEmail) + return Results.BadRequest("Emails do not match."); + + var user = await userManager.FindByNameAsync(context.User.Identity?.Name!); + if (user is null) + return Results.BadRequest("Can't find user."); + + var changeEmailToken = await userManager.GenerateChangeEmailTokenAsync(user, request.NewEmail); + var result = await userManager.ChangeEmailAsync(user, request.NewEmail, changeEmailToken); + + if (result.Succeeded) + { + await userManager.SetUserNameAsync(user, request.NewEmail); + await Logout(context); + } + + return result.Succeeded + ? Results.Ok() + : Results.BadRequest("Error while changing email address. Try again later."); } public async Task CanLogIn(HttpContext context, LoginRequest? request) diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs new file mode 100644 index 0000000..ac5c07c --- /dev/null +++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs @@ -0,0 +1,13 @@ +using System.ComponentModel.DataAnnotations; + +namespace Modules.Auth.Shared.ActionsRequests; + +public sealed class ChangeEmailRequest +{ + [Required] [MaxLength(60)] public string NewEmail { get; set; } = null!; + + [Required] + [MaxLength(60)] + [Compare(nameof(NewEmail))] + public string ConfirmNewEmail { get; set; } = null!; +} \ No newline at end of file From f30f5816630f0c695e6cafc1ced222a411574da2 Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Sun, 26 Oct 2025 12:35:40 +0100 Subject: [PATCH 12/19] Implement statistics for user and admin dashboards --- .../Data/Services/BackupsHttpClientService.cs | 9 ++ .../AdministrationDashboard.razor | 27 ++-- .../Client/Client.UI/Pages/Dashboard.razor | 25 +++- .../Modules.Backup.Api/Extensions.cs | 2 + .../Modules.Backup.Api/Statistics/StatsEO.cs | 53 ++++++++ .../Modules.Backup.Application/Extensions.cs | 4 +- .../Services/StatisticsService.cs | 122 ++++++++++++++++++ .../Dtos/AdminDashboardDto.cs | 12 ++ .../Dtos/UserDashboardDto.cs | 11 ++ 9 files changed, 248 insertions(+), 17 deletions(-) create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs index e093dfc..a7568bb 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs @@ -80,4 +80,13 @@ public async Task> EditAutoTestBackupConfig(AutoTestBacku { return await api.PostAsync("/api/servers/EditAutoTestConfig", config); } + + public async Task> GetMyDashboardAsync() + { + return await api.GetAsync("/api/statistics/MyDashboard"); + } + public async Task> GetAdminDashboardAsync() + { + return await api.GetAsync("/api/statistics/AdminDashboard"); + } } \ No newline at end of file diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor index e36788a..6315e52 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor @@ -1,7 +1,11 @@ @page "/administration/dashboard" + @using Client.UI.Data.Services +@using Modules.Backup.Shared.Dtos @inject AuthStateProvider Auth +@inject BackupsHttpClientService BackupService +@inject ISnackbar Snackbar Administration Dashboard @@ -13,54 +17,61 @@ Użytkownicy - 124 + @_dashboard.UsersCount Serwery - 18 + @_dashboard.ServersCount Tunele - 7 + @_dashboard.TunnelsCount Wykonane Backupy - 2 354 + @_dashboard.AllBackups Średnio backupów w miesiącu - 80 + @_dashboard.AvgBackupsPerMonth Ilość zrobionych testów - 1743 + @_dashboard.AllTests Testy udane - 96% + @_dashboard.TestsSuccessRate% @code{ - + private AdminDashboardDto _dashboard = new(); + protected override async Task OnInitializedAsync() { await Auth.AuthorizeUser(returnPageAfterValidPasswordAuthorization: "administration-dashboard"); + + var result = await BackupService.GetAdminDashboardAsync(); + result.Switch( + dashboard => _dashboard = dashboard, + error => Snackbar.Add(error, Severity.Error) + ); } } \ No newline at end of file diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor index 7555e0c..bd9c81e 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor @@ -1,7 +1,11 @@ @page "/dashboard" + @using Client.UI.Data.Services +@using Modules.Backup.Shared.Dtos @inject AuthStateProvider Auth +@inject BackupsHttpClientService BackupService +@inject ISnackbar Snackbar Dashboard @@ -12,47 +16,54 @@ Obsługiwane Serwery - 4 + @_dashboard.ServersCount Moje Tunele - 2 + @_dashboard.TunnelsCount Wykonane Backupy - 245 + @_dashboard.PerformedBackups Średnio backupów w miesiącu - 20 + @_dashboard.AvgBackupsPerMonth Ilość zrobionych testów - 180 + @_dashboard.PerformedTests Testy udane - 94% + @_dashboard.TestsSuccessRate% @code{ - + private UserDashboardDto _dashboard = new(); + protected override async Task OnInitializedAsync() { await Auth.AuthorizeUser(returnPageAfterValidPasswordAuthorization: "dashboard"); + + var result = await BackupService.GetMyDashboardAsync(); + result.Switch( + dashboard => _dashboard = dashboard, + error => Snackbar.Add(error, Severity.Error) + ); } } \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs index a20cd5f..8bebcf5 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs @@ -3,6 +3,7 @@ using Modules.Backup.Api.Backups; using Modules.Backup.Api.Schedules; using Modules.Backup.Api.Servers; +using Modules.Backup.Api.Statistics; using Modules.Backup.Application; using Modules.Backup.Infrastructure; @@ -23,6 +24,7 @@ public static WebApplication MapBackupModuleEndpoints(this WebApplication app) app.MapBackupEndpoints(); app.MapServersEndpoints(); app.MapSchedulesEndpoints(); + app.MapStatsEndpoints(); return app; } diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs new file mode 100644 index 0000000..8740abc --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs @@ -0,0 +1,53 @@ +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.Mvc; +using Modules.Backup.Application.Services; +using Modules.Shared.Attributes; + +namespace Modules.Backup.Api.Statistics; + +internal static class StatisticsEndpoints +{ + public static WebApplication MapStatsEndpoints(this WebApplication app) + { + var api = app.MapGroup("/api/statistics") + .RequireAuthorization() + .AddEndpointFilter(); + + api.MapGet("MyDashboard", StatisticsOperations.GetMyDashboard) + .WithSummary("Get user statistics for Dashboard"); + + api.MapGet("AdminDashboard", StatisticsOperations.GetAdminDashboard) + .WithSummary("Get Admin statistics for Dashboard") + .AddEndpointFilter(); + + return app; + } +} + +internal abstract record StatisticsOperations +{ + public static async Task GetMyDashboard( + HttpContext context, + [FromServices] StatisticsService service) + { + var result = await service.GetMyDashboard(context.User.Identity?.Name); + + return result.Match( + TypedResults.Ok, + TypedResults.BadRequest + ); + } + + public static async Task GetAdminDashboard( + HttpContext context, + [FromServices] StatisticsService service) + { + var result = await service.GetAdminDashboard(); + + return result.Match( + TypedResults.Ok, + TypedResults.BadRequest + ); + } +} \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs index bfef5d5..fbdd7e8 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs @@ -10,9 +10,9 @@ public static IServiceCollection AddApplicationLayer(this IServiceCollection ser { services.AddScoped(); services.AddScoped(); - services.AddScoped(); - + services.AddScoped(); + services.AddTransient(); return services; diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs new file mode 100644 index 0000000..f3cfbae --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs @@ -0,0 +1,122 @@ +using Microsoft.AspNetCore.Identity; +using Microsoft.EntityFrameworkCore; +using Modules.Auth.Core.Entities; +using Modules.Auth.Infrastructure.DbContexts; +using Modules.Backup.Core.Entities.DbContext; +using Modules.Backup.Infrastructure.DbContexts; +using Modules.Backup.Shared.Dtos; +using OneOf; + +namespace Modules.Backup.Application.Services; + +public sealed class StatisticsService(BackupsDbContext appDb, + AppIdentityDbContext identityDb, + UserManager userManager, + ServersService serversService) +{ + public async Task> GetMyDashboard(string? identityName) + { + if (string.IsNullOrEmpty(identityName)) + return "Can't access identity name"; + + var user = await userManager.FindByNameAsync(identityName); + if (user is null) + return "Can't find user"; + + var myServersListResult = await serversService.GetAvailableServersBasic(identityName); + var serversList = myServersListResult.IsT0 ? myServersListResult.AsT0 : new(); + + var tunnelsCount = 0; + var backupsCount = 0; + + var now = DateTime.UtcNow; + var sixMonthsAgo = now.AddMonths(-6); + List backupsLast6Months = new(); + + var totalTests = 0; + var successTests = 0; + + foreach (var server in serversList) + { + var dbServer = appDb.DbConnections.First(x => x.Id == server.Id); + + var tunnelId = dbServer?.TunnelId; + var doesTunnelExist = appDb.DbServerTunnels.FirstOrDefault(x => x.Id == tunnelId); + + if (doesTunnelExist is not null) + tunnelsCount++; + + var backups = appDb.Backups + .AsNoTracking() + .Where(x => x.ServerConnectionId == dbServer!.Id); + + backupsCount += backups.Count(); + backupsLast6Months.AddRange(backups + .Where(b => b.CreatedOn >= sixMonthsAgo && b.ServerConnectionId == dbServer!.Id)); + + foreach (var backup in backups) + { + if (backup.TestId is null) + continue; + + totalTests++; + + if (appDb.BackupsTests.First(x => x.Id == backup.TestId).IsSuccess) + successTests++; + } + } + + var avgBackupsPerMonth = backupsLast6Months + .GroupBy(b => new { b.CreatedOn.Year, b.CreatedOn.Month }) + .Select(g => g.Count()) + .DefaultIfEmpty(0) + .Average(); + + var testsSuccessRate = totalTests == 0 ? 0 : (100 * successTests / totalTests); + + var dashboard = new UserDashboardDto + { + ServersCount = serversList.Count, + TunnelsCount = tunnelsCount, + PerformedBackups = backupsCount, + AvgBackupsPerMonth = (int)avgBackupsPerMonth, + PerformedTests = totalTests, + TestsSuccessRate = testsSuccessRate + }; + + return dashboard; + } + + public async Task> GetAdminDashboard() + { + var now = DateTime.UtcNow; + var sixMonthsAgo = now.AddMonths(-6); + + var backupsLast6Months = await appDb.Backups + .Where(b => b.CreatedOn >= sixMonthsAgo) + .ToListAsync(); + + var avgBackupsPerMonth = backupsLast6Months + .GroupBy(b => new { b.CreatedOn.Year, b.CreatedOn.Month }) + .Select(g => g.Count()) + .DefaultIfEmpty(0) + .Average(); + + var totalTests = await appDb.BackupsTests.CountAsync(); + var successTests = await appDb.BackupsTests.CountAsync(x => x.IsSuccess); + var testsSuccessRate = totalTests == 0 ? 0 : (100 * successTests / totalTests); + + var dashboard = new AdminDashboardDto + { + UsersCount = await identityDb.Users.CountAsync(), + ServersCount = await appDb.DbConnections.CountAsync(), + TunnelsCount = await appDb.DbServerTunnels.CountAsync(), + AllBackups = await appDb.Backups.CountAsync(), + AvgBackupsPerMonth = (int)avgBackupsPerMonth, + AllTests = totalTests, + TestsSuccessRate = testsSuccessRate + }; + + return dashboard; + } +} \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs new file mode 100644 index 0000000..233418e --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs @@ -0,0 +1,12 @@ +namespace Modules.Backup.Shared.Dtos; + +public class AdminDashboardDto +{ + public int UsersCount { get; set; } + public int ServersCount { get; set; } + public int TunnelsCount { get; set; } + public int AllBackups { get; set; } + public int AvgBackupsPerMonth { get; set; } + public int AllTests { get; set; } + public int TestsSuccessRate { get; set; } +} \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs new file mode 100644 index 0000000..90a0dc8 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs @@ -0,0 +1,11 @@ +namespace Modules.Backup.Shared.Dtos; + +public class UserDashboardDto +{ + public int ServersCount { get; set; } + public int TunnelsCount { get; set; } + public int PerformedBackups { get; set; } + public int AvgBackupsPerMonth { get; set; } + public int PerformedTests { get; set; } + public int TestsSuccessRate { get; set; } +} \ No newline at end of file From 9a85d613708211b90431a939841f7465b65098ea Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Sun, 26 Oct 2025 13:03:18 +0100 Subject: [PATCH 13/19] Change deleting old backups entries to soft delete for future statistics --- .../Pages/BackupsModule/MyBackups.razor | 13 +- .../Services/DbBackupService.cs | 10 +- .../Entities/DbContext/PerformedBackup.cs | 1 + ...6120032_AddSoftDeleteToBackups.Designer.cs | 297 ++++++++++++++++++ .../20251026120032_AddSoftDeleteToBackups.cs | 29 ++ .../BackupsDbContextModelSnapshot.cs | 3 + .../Dtos/PerformedBackupDto.cs | 1 + 7 files changed, 347 insertions(+), 7 deletions(-) create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor index 81599a4..0477f98 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor @@ -81,9 +81,18 @@ - + - + @if (context.IsDisabled) + { + + + + } + else + { + + } diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs index 631a27a..1ce2f96 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs @@ -146,6 +146,7 @@ public async Task, string>> GetAllBackups(string? FilePath = x.FilePath, Name = x.Name, ServerConnectionId = x.ServerConnectionId, + IsDisabled = x.IsSoftDeleted, Test = dbContext.BackupsTests.AsNoTracking().Where(y => y.BackupId == x.Id).Select(y => new BackupTestDto { @@ -159,7 +160,7 @@ public async Task, string>> GetAllBackups(string? foreach (var server in dbServers) backups.AddRange(dbContext.Backups .AsNoTracking() - .Where(x => x.ServerConnectionId == server.Id) + .Where(x => x.ServerConnectionId == server.Id && !x.IsSoftDeleted) .Select(x => new PerformedBackupDto { Id = x.Id, @@ -275,11 +276,10 @@ await DeleteOldBackup.Delete(backupPath.DirectoryPath, serverConfig.TimeInDaysTo x.CreatedOn < cutoffDate); if (serverActualBackups.Any()) { - dbContext.Backups.RemoveRange(serverActualBackups); + foreach (var backup in serverActualBackups) + backup.IsSoftDeleted = true; + await dbContext.SaveChangesAsync(); - - logger.LogInformation("Successfully cleaned [{DeletedCount}] old backups entries", - serverActualBackups.Count()); } var serverConn = db.GetServerConnection(); diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs index 022dd8f..e70dae4 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs @@ -8,4 +8,5 @@ public sealed record PerformedBackup public Guid? TestId { get; set; } public Guid? ServerConnectionId { get; set; } public required string FilePath { get; set; } + public bool IsSoftDeleted { get; set; } = false; } \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs new file mode 100644 index 0000000..a4c62da --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs @@ -0,0 +1,297 @@ +// +using System; +using Microsoft.EntityFrameworkCore; +using Microsoft.EntityFrameworkCore.Infrastructure; +using Microsoft.EntityFrameworkCore.Migrations; +using Microsoft.EntityFrameworkCore.Storage.ValueConversion; +using Modules.Backup.Infrastructure.DbContexts; + +#nullable disable + +namespace Modules.Backup.Infrastructure.DbContexts.Migrations +{ + [DbContext(typeof(BackupsDbContext))] + [Migration("20251026120032_AddSoftDeleteToBackups")] + partial class AddSoftDeleteToBackups + { + /// + protected override void BuildTargetModel(ModelBuilder modelBuilder) + { +#pragma warning disable 612, 618 + modelBuilder.HasAnnotation("ProductVersion", "9.0.9"); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("AutomaticBackupTestConfigs"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ConfigurationJson") + .HasColumnType("TEXT"); + + b.Property("DbConnectionId") + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("NextBackupDate") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Schedules"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("BackupId") + .HasColumnType("TEXT"); + + b.Property("ErrorMessage") + .HasColumnType("TEXT"); + + b.Property("IsSuccess") + .HasColumnType("INTEGER"); + + b.Property("TestedOn") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("BackupsTests"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("AutoTestBackupsConfigId") + .HasColumnType("TEXT"); + + b.Property("BackupEncryptionKeyHas") + .HasColumnType("TEXT"); + + b.Property("ConnectionName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbPasswd") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbType") + .HasColumnType("INTEGER"); + + b.Property("DbUser") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("IsDisabled") + .HasColumnType("INTEGER"); + + b.Property("IsTunnelRequired") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerPort") + .HasColumnType("INTEGER"); + + b.Property("SsL") + .HasColumnType("INTEGER"); + + b.Property("TunnelId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbConnections"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("Description") + .HasColumnType("TEXT"); + + b.Property("IsActive") + .HasColumnType("INTEGER"); + + b.Property("LocalPort") + .HasColumnType("INTEGER"); + + b.Property("Password") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyContent") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyPassphrase") + .HasColumnType("TEXT"); + + b.Property("RemoteHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("RemotePort") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("SshPort") + .HasColumnType("INTEGER"); + + b.Property("UsePasswordAuth") + .HasColumnType("INTEGER"); + + b.Property("Username") + .IsRequired() + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbServerTunnels"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("CreatedOn") + .HasColumnType("TEXT"); + + b.Property("FilePath") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("IsSoftDeleted") + .HasColumnType("INTEGER"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerConnectionId") + .HasColumnType("TEXT"); + + b.Property("TestId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Backups"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("TimeInDaysToHoldBackups") + .HasColumnType("INTEGER"); + + b.HasKey("Id"); + + b.ToTable("Configurations"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersServers"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnChanges") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnErrors") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedBackups") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedTests") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnSuccessfulBackup") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnUpdates") + .HasColumnType("INTEGER"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersNotificationsSettings"); + }); +#pragma warning restore 612, 618 + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs new file mode 100644 index 0000000..1b42efe --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs @@ -0,0 +1,29 @@ +using Microsoft.EntityFrameworkCore.Migrations; + +#nullable disable + +namespace Modules.Backup.Infrastructure.DbContexts.Migrations +{ + /// + public partial class AddSoftDeleteToBackups : Migration + { + /// + protected override void Up(MigrationBuilder migrationBuilder) + { + migrationBuilder.AddColumn( + name: "IsSoftDeleted", + table: "Backups", + type: "INTEGER", + nullable: false, + defaultValue: false); + } + + /// + protected override void Down(MigrationBuilder migrationBuilder) + { + migrationBuilder.DropColumn( + name: "IsSoftDeleted", + table: "Backups"); + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs index 9ccb2e7..702584d 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs @@ -202,6 +202,9 @@ protected override void BuildModel(ModelBuilder modelBuilder) .IsRequired() .HasColumnType("TEXT"); + b.Property("IsSoftDeleted") + .HasColumnType("INTEGER"); + b.Property("Name") .IsRequired() .HasColumnType("TEXT"); diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs index d891a55..6192f35 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs @@ -8,4 +8,5 @@ public class PerformedBackupDto public BackupTestDto? Test { get; set; } public Guid? ServerConnectionId { get; set; } public string? FilePath { get; set; } + public bool IsDisabled { get; set; } = false; } \ No newline at end of file From d7e6dc50044c75808461113e50ae4d53281fdd93 Mon Sep 17 00:00:00 2001 From: artur Date: Thu, 30 Oct 2025 10:29:30 +0100 Subject: [PATCH 14/19] Fix error with depreceated mysqldump Implement mariadb-dump if mysqldump does not work Add ssl to dump --- .../Entities/Databases/MySqlDatabase.cs | 27 ++++++++++++++++--- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs index 7eee151..29c6f89 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs @@ -30,22 +30,23 @@ private async Task PerformBackupWithDump(string fullFilePath) var hostPort = GetHostAndPort(); var decryptedDbPassword = _cryptoService.Decrypt(_serverConnection.DbPasswd); - var args = + var baseArgs = $"-h {hostPort.Host} -P {hostPort.Port} -u {_serverConnection.DbUser} -p{decryptedDbPassword} {_serverConnection.DbName}"; + var mySqlSsl = GetServerConnection().SsL ? "--ssl-mode=PREFERRED" : "--ssl-mode=DISABLED"; var process = new Process { StartInfo = new ProcessStartInfo { FileName = "mysqldump", - Arguments = args, + Arguments = $"{mySqlSsl} {baseArgs}", RedirectStandardOutput = true, RedirectStandardError = true, UseShellExecute = false, CreateNoWindow = true } }; - + await using var fs = new FileStream(fullFilePath, FileMode.Create, FileAccess.Write); process.Start(); await process.StandardOutput.BaseStream.CopyToAsync(fs); @@ -53,7 +54,25 @@ private async Task PerformBackupWithDump(string fullFilePath) await process.WaitForExitAsync(); if (process.ExitCode != 0) - throw new Exception($"mysqldump failed: {error}"); + { + if (error.Contains("mariadb-dump", StringComparison.OrdinalIgnoreCase)) + { + process.Kill(); + var mariaSqlSsl = GetServerConnection().SsL ? "--ssl-verify-server-cert" : "--ssl=0"; + process.StartInfo.FileName = "mariadb-dump"; + process.StartInfo.Arguments = $"{mariaSqlSsl} {baseArgs}"; + + process.Start(); + await process.StandardOutput.BaseStream.CopyToAsync(fs); + error = await process.StandardError.ReadToEndAsync(); + await process.WaitForExitAsync(); + + if (process.ExitCode != 0) + throw new Exception($"mariadb-dump failed: {error}"); + } + else + throw new Exception($"mysqldump failed: {error}"); + } } private async Task PerformBackupWithLibrary(string fullFilePath) From a226a2fa602c54710efe6ca5fdfdbced540d4575 Mon Sep 17 00:00:00 2001 From: artur Date: Tue, 4 Nov 2025 10:41:32 +0100 Subject: [PATCH 15/19] Add msgboxes confirmations to delete buttons. Translate index page --- .../AdministrationUsersManagement.razor | 30 ++++-- .../Pages/BackupsModule/MySchedules.razor | 34 ++++--- .../Pages/BackupsModule/MyServers.razor | 52 ++++++---- .../Client/Client.UI/Pages/Index.razor | 97 +++++++++++-------- 4 files changed, 130 insertions(+), 83 deletions(-) diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor index 380c6e5..cfcd959 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor @@ -39,7 +39,7 @@ { + OnClick="@(() => ToggleBlock(context))" Disabled="@_isProcessing"> Block } @@ -47,7 +47,7 @@ { + OnClick="@(() => ToggleBlock(context))" Disabled="@_isProcessing"> Unblock } @@ -104,18 +104,28 @@ StateHasChanged(); } - private async Task ToggleBlock(string userId) + private async Task ToggleBlock(UserDto user) { - _isProcessing = true; + var blockadeString = user.IsBlocked ? "unblock" : "block"; + bool? msgBoxResult = await DialogService.ShowMessageBox( + "Warning", + $"Are you sure that you want to {blockadeString} this user?", + yesText:"Yes!", cancelText:"Cancel"); + + if (msgBoxResult is not null) + { + _isProcessing = true; - var result = await Service.ToggleUserBlockade(userId); + var result = await Service.ToggleUserBlockade(user.Id.ToString()); - result.Switch( - async void (_) => await FetchUsers(), - error => Snackbar.Add(error, Severity.Error) - ); + result.Switch( + async void (_) => await FetchUsers(), + error => Snackbar.Add(error, Severity.Error) + ); + + _isProcessing = false; + } - _isProcessing = false; } private async Task OpenEditUserDialog(UserDto user) diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor index a96751d..eba0591 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor @@ -123,20 +123,28 @@ private async Task DeleteSchedule(Guid id) { - _isProcessing = true; - - var result = await Service.DeleteScheduleAsync(id); - - result.Switch( - async void (_) => - { - Snackbar.Add("Successfully removed schedule.", Severity.Success); - await FetchSchedules(); - }, - error => Snackbar.Add(error, Severity.Error) - ); + bool? msgBoxResult = await DialogService.ShowMessageBox( + "Warning", + (MarkupString) "Are you sure that you want to permanently delete this schedule?

This can not be undone!", + yesText:"Permanently delete", cancelText:"Cancel"); + + if (msgBoxResult is not null) + { + _isProcessing = true; + + var result = await Service.DeleteScheduleAsync(id); - _isProcessing = false; + result.Switch( + async void (_) => + { + Snackbar.Add("Successfully removed schedule.", Severity.Success); + await FetchSchedules(); + }, + error => Snackbar.Add(error, Severity.Error) + ); + + _isProcessing = false; + } } private async Task OpenNewScheduleDialog() diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor index 993c69a..280950e 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor @@ -159,16 +159,24 @@ private async Task DisableServer(Guid id) { - _isProcessing = true; - - var result = await Service.ToggleServerDisabledStatus(id); - - result.Switch( - success => _ = FetchServers(), - error => Snackbar.Add(error, Severity.Error) - ); - - _isProcessing = false; + bool? msgBoxResult = await DialogService.ShowMessageBox( + "Warning", + (MarkupString) "Are you sure that you want to disable this server?

This can be undone after contacting to Administrator.", + yesText:"Disable", cancelText:"Cancel"); + + if(msgBoxResult is not null) + { + _isProcessing = true; + + var result = await Service.ToggleServerDisabledStatus(id); + + result.Switch( + success => _ = FetchServers(), + error => Snackbar.Add(error, Severity.Error) + ); + + _isProcessing = false; + } } private async Task OpenEditServerDialog(ServerConnectionDto server) @@ -213,16 +221,24 @@ private async Task DeleteServer(Guid serverId) { - _isProcessing = true; - - var result = await Service.CascadeDeleteServer(serverId); + bool? msgBoxResult = await DialogService.ShowMessageBox( + "Warning", + (MarkupString) "Are you sure that you want to delete this server?

This can not be undone!", + yesText:"Delete Permanently!", cancelText:"Cancel"); + + if (msgBoxResult is not null) + { + _isProcessing = true; + + var result = await Service.CascadeDeleteServer(serverId); - result.Switch( - success => _ = FetchServers(), - error => Snackbar.Add(error, Severity.Error) - ); + result.Switch( + success => _ = FetchServers(), + error => Snackbar.Add(error, Severity.Error) + ); - _isProcessing = false; + _isProcessing = false; + } } private async Task PerformServerBackup(Guid serverId) diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor index 73019e8..580a0e6 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor @@ -6,31 +6,25 @@ - Witaj w OctoBackup + Welcome in OctoBackup - Tutaj znajdziesz najnowsze informacje, aktualizacje i linki do dokumentacji systemu. + Here you will find the latest information, updates, and links to system documentation. - Dołącz do nas i korzystaj z możliwości - systemu! - + Join us and enjoy the benefits of the system! - Nie masz jeszcze konta? Dołącz do - nas! - - - Stwórz nowe konto i ciesz się możliwościa korzystania z OctoBackup! - + Don't have an account yet? Join us now! + Create a new account and enjoy using OctoBackup! - Zarejestruj się + Sign up @@ -39,15 +33,12 @@ - Posiadasz już konto w systemie? - - - Zaloguj się do swojego konta w OctoBackup! - + Do you already have an account in the system? + Log in to your OctoBackup account! - Zaloguj się + Log in @@ -57,17 +48,17 @@ - Nowości + What's New - Dodano obsługę wielu baz danych w jednym backupie. + An example of a new feature that improves system usability 2025-08-25 - Usprawniono autoryzację użytkowników i system powiadomień. + Another example of a new feature enabling advanced backup scheduling 2025-08-20 @@ -76,38 +67,60 @@ - Dokumentacja i zasoby + Documentation and resources - - - - API Documentation - - Pełna dokumentacja API do integracji z systemem OctoBackup. - - - - - Otwórz dokumentację - - - - + @if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Production") + { + + + + Documentation + + Complete documentation for the OctoBackup system. + + + + + Open documentation + + + + + } + else + { + + + + Documentation + + API documentation for the OctoBackup system. + + + + + Open API documentation + + + + + } - Wiki / Instrukcje + Wiki / Instructions - Szybki dostęp do poradników i instrukcji użytkowania. + Quick access to guides and user manuals. - - Otwórz Wiki + Open Wiki From 9ff30decee0b9d39a43748731ca19cdd4b782aeb Mon Sep 17 00:00:00 2001 From: artur Date: Tue, 4 Nov 2025 11:31:40 +0100 Subject: [PATCH 16/19] Add BackupsTests Module with test api and example method to api. Implement creating test container and retrieving its guid. --- DbBackupService/OctoBackup.sln | 10 ++++ .../Bootstraper/Server/Server.Api/Program.cs | 3 ++ .../Server/Server.Api/Server.Api.csproj | 1 + .../BackupsTestsEO.cs | 54 +++++++++++++++++++ .../Modules.BackupsTests.Api/Extensions.cs | 19 +++++++ .../Modules.BackupsTests.Api.csproj | 20 +++++++ 6 files changed, 107 insertions(+) create mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs create mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs create mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj diff --git a/DbBackupService/OctoBackup.sln b/DbBackupService/OctoBackup.sln index a96186c..34d4313 100644 --- a/DbBackupService/OctoBackup.sln +++ b/DbBackupService/OctoBackup.sln @@ -64,6 +64,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Modules.Crypto.Shared", "Sr EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Modules.Crypto.Api", "Src\Modules\CryptoModule\Modules.Crypto.Api\Modules.Crypto.Api.csproj", "{81471CFC-061C-48E4-ACCA-FBE583DCAC01}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "BackupsTests", "BackupsTests", "{7141A8CE-79EE-4C76-8AA6-E5D074650290}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Modules.BackupsTests.Api", "Src\Modules\BackupsTests\Modules.BackupsTests.Api\Modules.BackupsTests.Api.csproj", "{1DE044F9-AEBE-4384-8766-7B60BD829C01}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -146,6 +150,10 @@ Global {81471CFC-061C-48E4-ACCA-FBE583DCAC01}.Debug|Any CPU.Build.0 = Debug|Any CPU {81471CFC-061C-48E4-ACCA-FBE583DCAC01}.Release|Any CPU.ActiveCfg = Release|Any CPU {81471CFC-061C-48E4-ACCA-FBE583DCAC01}.Release|Any CPU.Build.0 = Release|Any CPU + {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Debug|Any CPU.Build.0 = Debug|Any CPU + {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Release|Any CPU.ActiveCfg = Release|Any CPU + {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -178,6 +186,8 @@ Global {32E6D088-AFE2-42A8-BE7F-7FC5348E356D} = {7EFE67DE-F557-4212-BF9E-57F7F1DAECA7} {8F76EA6E-8657-4581-9666-F484BE627D45} = {7EFE67DE-F557-4212-BF9E-57F7F1DAECA7} {81471CFC-061C-48E4-ACCA-FBE583DCAC01} = {7EFE67DE-F557-4212-BF9E-57F7F1DAECA7} + {7141A8CE-79EE-4C76-8AA6-E5D074650290} = {00FABD4C-5920-4940-A122-342F45F5B31A} + {1DE044F9-AEBE-4384-8766-7B60BD829C01} = {7141A8CE-79EE-4C76-8AA6-E5D074650290} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {05F3A4BF-6277-46FD-9537-F78E8FABE0DA} diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs b/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs index 4b6cbf9..c599572 100644 --- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs +++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs @@ -12,6 +12,7 @@ using Modules.Backup.Application.Workers; using Modules.Backup.Infrastructure.DbContexts; using Modules.Backup.Shared.Hubs; +using Modules.BackupsTests.Api; using Modules.Crypto.Api; using Modules.Shared.Common; using OpenTelemetry.Exporter; @@ -41,6 +42,7 @@ builder.Services.AddOpenApi(); builder.Services.AddBackupModule(); +builder.Services.AddBackupsTestsModule(); builder.Services.AddLogging(logging => { @@ -181,6 +183,7 @@ app.UseRouting(); app.MapBackupModuleEndpoints(); +app.MapBackupsTestsModuleEndpoints(); app.MapAuthModuleEndpoints(); app.MapAdministrationModuleEndpoints(); diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj index d717a60..d60cc8f 100644 --- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj +++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj @@ -27,6 +27,7 @@ +
diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs new file mode 100644 index 0000000..9e8fcea --- /dev/null +++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs @@ -0,0 +1,54 @@ +using System.Diagnostics; +using DotNet.Testcontainers.Builders; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Http; +using Microsoft.Extensions.Logging; +using Modules.Shared.Attributes; + +namespace Modules.BackupsTests.Api; + +internal static class BackupsTestsEndpoints +{ + public static WebApplication MapBackupsTestsEndpoints(this WebApplication app) + { + var api = app.MapGroup("/api/BackupsTests"); + // .RequireAuthorization() + // .AddEndpointFilter(); + + api.MapGet("RunTest", BackupsTestsOperations.RunTest) + .WithSummary("Run test dev container"); + + return app; + } +} + +internal abstract record BackupsTestsOperations +{ + public static async Task RunTest( + HttpContext context, + ILogger logger) + { + var container = new ContainerBuilder() + .WithImage("testcontainers/helloworld:1.3.0") + .WithPortBinding(8080, true) + // Wait until the HTTP endpoint of the container is available. + .WithWaitStrategy(Wait.ForUnixContainer().UntilHttpRequestIsSucceeded(r => r.ForPort(8080))) + .Build(); + + await container.StartAsync() + .ConfigureAwait(false); + + using var httpClient = new HttpClient(); + + // Construct the request URI by specifying the scheme, hostname, assigned random host port, and the endpoint "uuid". + var requestUri = new UriBuilder(Uri.UriSchemeHttp, container.Hostname, container.GetMappedPublicPort(8080), "uuid").Uri; + + // Send an HTTP GET request to the specified URI and retrieve the response as a string. + var guid = await httpClient.GetStringAsync(requestUri).ConfigureAwait(false); + + Debug.Assert(Guid.TryParse(guid, out _)); + logger.LogInformation("Success guid: {ContainerGuid}", guid); + + return TypedResults.Ok(guid); + } +} \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs new file mode 100644 index 0000000..1b81d65 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs @@ -0,0 +1,19 @@ +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; + +namespace Modules.BackupsTests.Api; + +public static class Extensions +{ + public static IServiceCollection AddBackupsTestsModule(this IServiceCollection services) + { + return services; + } + + public static WebApplication MapBackupsTestsModuleEndpoints(this WebApplication app) + { + app.MapBackupsTestsEndpoints(); + + return app; + } +} \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj new file mode 100644 index 0000000..ebb7576 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj @@ -0,0 +1,20 @@ + + + + net9.0 + enable + enable + + + + + + + + + + + + + + From 792fd8bb4805226fdd79459844525012124f78e1 Mon Sep 17 00:00:00 2001 From: artur Date: Wed, 5 Nov 2025 09:43:39 +0100 Subject: [PATCH 17/19] Change test status from bool to Enum Implement first preview of creating test mysql container and recovering test local sql file. --- .../Pages/BackupsModule/MyBackups.razor | 41 ++- .../Services/DbBackupService.cs | 4 +- .../Services/StatisticsService.cs | 5 +- .../Entities/DbContext/BackupTest.cs | 6 +- .../BackupsDbContextModelSnapshot.cs | 2 +- ...3810_ChangeEntityAddTestStatus.Designer.cs | 297 ++++++++++++++++++ ...0251105083810_ChangeEntityAddTestStatus.cs | 28 ++ .../Dtos/BackupTestDto.cs | 6 +- .../Dtos/PerformedBackupDto.cs | 4 +- .../Enums/ETestStatus.cs | 8 + .../BackupsTestsEO.cs | 96 +++++- .../Modules.BackupsTests.Api.csproj | 6 + 12 files changed, 465 insertions(+), 38 deletions(-) create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor index 0477f98..d90b85a 100644 --- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor +++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor @@ -8,6 +8,7 @@ @using Client.UI.Data.Services @using Microsoft.AspNetCore.SignalR.Client @using Modules.Backup.Shared.Dtos +@using Modules.Backup.Shared.Enums @using Modules.Backup.Shared.Hubs @implements IDisposable @@ -38,7 +39,7 @@ File Location - Test + Test Status @@ -63,15 +64,25 @@ @if (context.Test is not null) { - if (context.Test.IsSuccess) + switch (context.Test.Status) { - OK - } - else - { - - Error - + case ETestStatus.Success: + OK + break; + + case ETestStatus.Failure: + + Error + + break; + + case ETestStatus.Running: + Running + break; + + default: + Not implemented status + break; } } else @@ -101,16 +112,20 @@ Href="@(Nav.ToAbsoluteUri($"/api/backups/download?id={context.Id}").ToString())"/> - @switch (context.Test?.IsSuccess) + Disabled="@((context.Test?.Status == ETestStatus.Running) && context.Test is not null)"> + @switch (context.Test?.Status) { - case true: + case ETestStatus.Success: Successful Test break; - case false: + case ETestStatus.Failure: Retry Test break; + + case ETestStatus.Running: + Test currently running... + break; default: Perform Test diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs index 1ce2f96..9384d63 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs @@ -152,7 +152,7 @@ public async Task, string>> GetAllBackups(string? { Id = y.Id, ErrorMessage = y.ErrorMessage, - IsSuccess = y.IsSuccess, + Status = y.Status, TestedOn = y.TestedOn }).FirstOrDefault() }).ToList(); @@ -173,7 +173,7 @@ public async Task, string>> GetAllBackups(string? { Id = y.Id, ErrorMessage = y.ErrorMessage, - IsSuccess = y.IsSuccess, + Status = y.Status, TestedOn = y.TestedOn }).FirstOrDefault() })); diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs index f3cfbae..031f8df 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs @@ -5,6 +5,7 @@ using Modules.Backup.Core.Entities.DbContext; using Modules.Backup.Infrastructure.DbContexts; using Modules.Backup.Shared.Dtos; +using Modules.Backup.Shared.Enums; using OneOf; namespace Modules.Backup.Application.Services; @@ -61,7 +62,7 @@ public async Task> GetMyDashboard(string? identi totalTests++; - if (appDb.BackupsTests.First(x => x.Id == backup.TestId).IsSuccess) + if (appDb.BackupsTests.First(x => x.Id == backup.TestId).Status == ETestStatus.Success) successTests++; } } @@ -103,7 +104,7 @@ public async Task> GetAdminDashboard() .Average(); var totalTests = await appDb.BackupsTests.CountAsync(); - var successTests = await appDb.BackupsTests.CountAsync(x => x.IsSuccess); + var successTests = await appDb.BackupsTests.CountAsync(x => x.Status == ETestStatus.Success); var testsSuccessRate = totalTests == 0 ? 0 : (100 * successTests / totalTests); var dashboard = new AdminDashboardDto diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs index da830f6..c41fc90 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs @@ -1,10 +1,12 @@ -namespace Modules.Backup.Core.Entities.DbContext; +using Modules.Backup.Shared.Enums; + +namespace Modules.Backup.Core.Entities.DbContext; public sealed record BackupTest { public Guid Id { get; set; } public Guid BackupId { get; set; } public DateTime TestedOn { get; set; } - public bool IsSuccess { get; set; } + public ETestStatus Status { get; set; } = ETestStatus.Running; public string? ErrorMessage { get; set; } } \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs index 702584d..d7c64ad 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs @@ -73,7 +73,7 @@ protected override void BuildModel(ModelBuilder modelBuilder) b.Property("ErrorMessage") .HasColumnType("TEXT"); - b.Property("IsSuccess") + b.Property("Status") .HasColumnType("INTEGER"); b.Property("TestedOn") diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs new file mode 100644 index 0000000..a929a82 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs @@ -0,0 +1,297 @@ +// +using System; +using Microsoft.EntityFrameworkCore; +using Microsoft.EntityFrameworkCore.Infrastructure; +using Microsoft.EntityFrameworkCore.Migrations; +using Microsoft.EntityFrameworkCore.Storage.ValueConversion; +using Modules.Backup.Infrastructure.DbContexts; + +#nullable disable + +namespace Modules.Backup.Infrastructure.Migrations +{ + [DbContext(typeof(BackupsDbContext))] + [Migration("20251105083810_ChangeEntityAddTestStatus")] + partial class ChangeEntityAddTestStatus + { + /// + protected override void BuildTargetModel(ModelBuilder modelBuilder) + { +#pragma warning disable 612, 618 + modelBuilder.HasAnnotation("ProductVersion", "9.0.9"); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("AutomaticBackupTestConfigs"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ConfigurationJson") + .HasColumnType("TEXT"); + + b.Property("DbConnectionId") + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("NextBackupDate") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Schedules"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("BackupId") + .HasColumnType("TEXT"); + + b.Property("ErrorMessage") + .HasColumnType("TEXT"); + + b.Property("Status") + .HasColumnType("INTEGER"); + + b.Property("TestedOn") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("BackupsTests"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("AutoTestBackupsConfigId") + .HasColumnType("TEXT"); + + b.Property("BackupEncryptionKeyHas") + .HasColumnType("TEXT"); + + b.Property("ConnectionName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbName") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbPasswd") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("DbType") + .HasColumnType("INTEGER"); + + b.Property("DbUser") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("IsDisabled") + .HasColumnType("INTEGER"); + + b.Property("IsTunnelRequired") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerPort") + .HasColumnType("INTEGER"); + + b.Property("SsL") + .HasColumnType("INTEGER"); + + b.Property("TunnelId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbConnections"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("Description") + .HasColumnType("TEXT"); + + b.Property("IsActive") + .HasColumnType("INTEGER"); + + b.Property("LocalPort") + .HasColumnType("INTEGER"); + + b.Property("Password") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyContent") + .HasColumnType("TEXT"); + + b.Property("PrivateKeyPassphrase") + .HasColumnType("TEXT"); + + b.Property("RemoteHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("RemotePort") + .HasColumnType("INTEGER"); + + b.Property("ServerHost") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("SshPort") + .HasColumnType("INTEGER"); + + b.Property("UsePasswordAuth") + .HasColumnType("INTEGER"); + + b.Property("Username") + .IsRequired() + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("DbServerTunnels"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("CreatedOn") + .HasColumnType("TEXT"); + + b.Property("FilePath") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("IsSoftDeleted") + .HasColumnType("INTEGER"); + + b.Property("Name") + .IsRequired() + .HasColumnType("TEXT"); + + b.Property("ServerConnectionId") + .HasColumnType("TEXT"); + + b.Property("TestId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("Backups"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("TimeInDaysToHoldBackups") + .HasColumnType("INTEGER"); + + b.HasKey("Id"); + + b.ToTable("Configurations"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("ServerId") + .HasColumnType("TEXT"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersServers"); + }); + + modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b => + { + b.Property("Id") + .ValueGeneratedOnAdd() + .HasColumnType("TEXT"); + + b.Property("IsEnabled") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnChanges") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnErrors") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedBackups") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnFailedTests") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnSuccessfulBackup") + .HasColumnType("INTEGER"); + + b.Property("NotifyOnUpdates") + .HasColumnType("INTEGER"); + + b.Property("UserId") + .HasColumnType("TEXT"); + + b.HasKey("Id"); + + b.ToTable("UsersNotificationsSettings"); + }); +#pragma warning restore 612, 618 + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs new file mode 100644 index 0000000..82e09c0 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs @@ -0,0 +1,28 @@ +using Microsoft.EntityFrameworkCore.Migrations; + +#nullable disable + +namespace Modules.Backup.Infrastructure.Migrations +{ + /// + public partial class ChangeEntityAddTestStatus : Migration + { + /// + protected override void Up(MigrationBuilder migrationBuilder) + { + migrationBuilder.RenameColumn( + name: "IsSuccess", + table: "BackupsTests", + newName: "Status"); + } + + /// + protected override void Down(MigrationBuilder migrationBuilder) + { + migrationBuilder.RenameColumn( + name: "Status", + table: "BackupsTests", + newName: "IsSuccess"); + } + } +} diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs index 3b9f9c0..1bd9ca2 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs @@ -1,9 +1,11 @@ -namespace Modules.Backup.Shared.Dtos; +using Modules.Backup.Shared.Enums; + +namespace Modules.Backup.Shared.Dtos; public class BackupTestDto { public Guid Id { get; set; } = Guid.CreateVersion7(); public DateTime TestedOn { get; set; } - public bool IsSuccess { get; set; } + public ETestStatus Status { get; set; } public string? ErrorMessage { get; set; } } \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs index 6192f35..e7e4082 100644 --- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs @@ -1,4 +1,6 @@ -namespace Modules.Backup.Shared.Dtos; +using System.Data; + +namespace Modules.Backup.Shared.Dtos; public class PerformedBackupDto { diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs new file mode 100644 index 0000000..a507425 --- /dev/null +++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs @@ -0,0 +1,8 @@ +namespace Modules.Backup.Shared.Enums; + +public enum ETestStatus +{ + Running, + Success, + Failure +} \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs index 9e8fcea..51758be 100644 --- a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs +++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs @@ -4,6 +4,7 @@ using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Logging; using Modules.Shared.Attributes; +using MySqlConnector; namespace Modules.BackupsTests.Api; @@ -15,7 +16,7 @@ public static WebApplication MapBackupsTestsEndpoints(this WebApplication app) // .RequireAuthorization() // .AddEndpointFilter(); - api.MapGet("RunTest", BackupsTestsOperations.RunTest) + api.MapPost("RunTest", BackupsTestsOperations.RunTest) .WithSummary("Run test dev container"); return app; @@ -28,27 +29,92 @@ public static async Task RunTest( HttpContext context, ILogger logger) { + //TODO: Implement accepting id of backup, get it from db, check file path, file name, unzip file etc + // TODO: Implement additional status for backup test like running, failed, success etc + var backupFolder = "/home/artur/.local/share/OctoBackup/Backups/localhost_3306/app"; // lokalny folder z dump.sql + var dbName = "app"; + var password = "toor"; + + logger.LogInformation("Budowanie kontenera"); + // 1️⃣ Tworzymy kontener MySQL z mapowaniem folderu backupu var container = new ContainerBuilder() - .WithImage("testcontainers/helloworld:1.3.0") - .WithPortBinding(8080, true) - // Wait until the HTTP endpoint of the container is available. - .WithWaitStrategy(Wait.ForUnixContainer().UntilHttpRequestIsSucceeded(r => r.ForPort(8080))) + .WithImage("mysql:8.0") + .WithEnvironment("MYSQL_ROOT_PASSWORD", password) + .WithEnvironment("MYSQL_DATABASE", dbName) + .WithBindMount(backupFolder, "/backup") + .WithPortBinding(3306, true) + .WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged("ready for connections")) .Build(); - await container.StartAsync() - .ConfigureAwait(false); + logger.LogInformation("Startuje kontener"); + await container.StartAsync().ConfigureAwait(false); + + logger.LogInformation("Pobieram dane kontenera"); + var host = container.Hostname; + var port = container.GetMappedPublicPort(3306); + + logger.LogInformation("Hostname: {Host}, Port: {Port}", host, port); + + logger.LogInformation("Czekam na możliwość podlaczenia sie do bazy"); + // 2️⃣ Czekamy aż MySQL wystartuje + var connStr = $"Server={host};Port={port};User ID=root;Password={password};Database={dbName};SslMode=none;AllowPublicKeyRetrieval=True"; + await WaitForDatabaseAsync(connStr); + + logger.LogInformation("Przywracam backup"); + // 3️⃣ Przywrócenie backupu (załóżmy że dump.sql leży w /backup) + await container.ExecAsync(["bash", "-c", $"mysql -uroot -p{password} {dbName} < /backup/2025.11.05.08.04.sql"]); + + // 4️⃣ Sprawdzenie czy są tabele inne niż systemowe + await using var conn = new MySqlConnection(connStr); + await conn.OpenAsync(); - using var httpClient = new HttpClient(); + logger.LogInformation("Sprawdzam czy zostaly jakies tabele stworzone"); + var cmd = new MySqlCommand( + "SELECT TABLE_NAME FROM information_schema.tables WHERE table_schema = @db AND TABLE_NAME NOT LIKE 'sys_%';", + conn); + cmd.Parameters.AddWithValue("@db", dbName); - // Construct the request URI by specifying the scheme, hostname, assigned random host port, and the endpoint "uuid". - var requestUri = new UriBuilder(Uri.UriSchemeHttp, container.Hostname, container.GetMappedPublicPort(8080), "uuid").Uri; + var tables = new List(); + await using var reader = await cmd.ExecuteReaderAsync(); + while (await reader.ReadAsync()) + tables.Add(reader.GetString(0)); - // Send an HTTP GET request to the specified URI and retrieve the response as a string. - var guid = await httpClient.GetStringAsync(requestUri).ConfigureAwait(false); + logger.LogInformation("Znalezione tabele: {Tables}", string.Join(", ", tables)); - Debug.Assert(Guid.TryParse(guid, out _)); - logger.LogInformation("Success guid: {ContainerGuid}", guid); + logger.LogInformation("Stopuje i usuwam testowy kontener"); + await container.StopAsync(); + await container.DisposeAsync(); + + logger.LogInformation("Zwracam wynik"); + return TypedResults.Ok(new + { + Tables = tables, + Success = tables.Count > 0 + }); + } + + private static async Task WaitForDatabaseAsync(string connStr) + { + var timeout = TimeSpan.FromSeconds(30); + var sw = Stopwatch.StartNew(); + + Exception exception = new(); - return TypedResults.Ok(guid); + while (sw.Elapsed < timeout) + { + try + { + await using var conn = new MySqlConnection(connStr); + await conn.OpenAsync(); + return; + } + catch (Exception ex) + { + exception = ex; + await Task.Delay(1000); + } + } + + throw new Exception($"MySQL container did not start in time. Error: {exception.Message}", exception); } } \ No newline at end of file diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj index ebb7576..bbb034c 100644 --- a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj +++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj @@ -17,4 +17,10 @@ + + + ..\..\..\..\..\..\..\..\.nuget\packages\mysqlconnector\2.4.0\lib\net9.0\MySqlConnector.dll + + + From 6df1edb9f12e098a94fd547a8f931dae2b98c245 Mon Sep 17 00:00:00 2001 From: Artur Lewandowski Date: Thu, 22 Oct 2026 01:03:42 +0200 Subject: [PATCH 18/19] Refactor code. Change blazor wasm to react vite. Upgrade project to .net 10. Clean up. Implement OWASP Top 10. Fix found bugs while testing. Change UI design. --- .agents/skills/feature-arch/SKILL.md | 110 + .../bound-event-based-communication.md | 84 + .../references/bound-feature-isolation.md | 88 + .../bound-feature-scoped-routing.md | 76 + .../references/bound-feature-size.md | 74 + .../references/bound-interface-contracts.md | 83 + .../references/bound-minimize-shared-state.md | 73 + .../references/fcomp-colocate-styles.md | 88 + .../fcomp-composition-over-props.md | 100 + .../fcomp-container-presentational.md | 99 + .../references/fcomp-error-boundaries.md | 99 + .../fcomp-props-as-data-boundary.md | 88 + .../references/fcomp-single-responsibility.md | 99 + .../references/fquery-avoid-n-plus-one.md | 80 + .../fquery-colocate-with-feature.md | 70 + .../references/fquery-feature-scoped-keys.md | 72 + .../references/fquery-parallel-fetching.md | 71 + .../fquery-server-component-fetching.md | 88 + .../fquery-single-responsibility.md | 66 + .../references/fstate-context-sparingly.md | 73 + .../fstate-feature-scoped-stores.md | 79 + .../references/fstate-lift-minimally.md | 85 + .../references/fstate-reset-on-unmount.md | 89 + .../fstate-server-state-separation.md | 93 + .../references/import-avoid-barrel-files.md | 63 + .../references/import-no-cross-feature.md | 84 + .../references/import-path-aliases.md | 64 + .../references/import-public-api.md | 67 + .../references/import-type-only.md | 81 + .../references/import-unidirectional-flow.md | 82 + .../references/name-descriptive-exports.md | 65 + .../references/name-feature-naming.md | 60 + .../references/name-file-conventions.md | 79 + .../references/struct-app-layer.md | 73 + .../references/struct-feature-folders.md | 70 + .../struct-feature-self-contained.md | 62 + .../references/struct-flat-hierarchy.md | 58 + .../references/struct-optional-segments.md | 72 + .../references/struct-shared-layer.md | 68 + .../references/test-colocate-with-feature.md | 78 + .../references/test-feature-isolation.md | 88 + .../test-integration-at-app-layer.md | 87 + .../references/test-shared-utilities.md | 94 + .agents/skills/msw/SKILL.md | 121 + .../references/advanced-bypass-requests.md | 81 + .../msw/references/advanced-cookies-auth.md | 119 + .../references/advanced-dynamic-scenarios.md | 114 + .../msw/references/advanced-file-uploads.md | 109 + .../advanced-playwright-integration.md | 78 + .../msw/references/advanced-vitest-browser.md | 100 + .../references/advanced-websocket-mocking.md | 87 + .../msw/references/debug-common-issues.md | 79 + .../msw/references/debug-lifecycle-events.md | 88 + .../msw/references/debug-request-logging.md | 113 + .../references/debug-verify-interception.md | 95 + .../msw/references/graphql-batched-queries.md | 93 + .../msw/references/graphql-error-responses.md | 119 + .../references/graphql-operation-handlers.md | 101 + .../msw/references/graphql-schema-first.md | 76 + .../references/graphql-variables-access.md | 123 + .../msw/references/handler-absolute-urls.md | 70 + .../msw/references/handler-domain-grouping.md | 81 + .../references/handler-happy-path-first.md | 60 + .../handler-request-body-parsing.md | 76 + .../references/handler-resolver-argument.md | 86 + .../handler-reusability-environments.md | 80 + .../references/handler-shared-resolvers.md | 99 + .../references/handler-v2-response-syntax.md | 94 + .../msw/references/match-custom-predicate.md | 99 + .../msw/references/match-handler-order.md | 93 + .../msw/references/match-http-methods.md | 98 + .../msw/references/match-query-params.md | 89 + .../msw/references/match-url-patterns.md | 87 + .../msw/references/response-custom-headers.md | 125 + .../references/response-delay-realistic.md | 92 + .../references/response-error-simulation.md | 110 + .../response-http-response-helpers.md | 83 + .../references/response-one-time-handlers.md | 103 + .../msw/references/response-streaming.md | 114 + .../msw/references/setup-lifecycle-hooks.md | 57 + .../msw/references/setup-node-version.md | 72 + .../setup-server-node-entrypoint.md | 45 + .../msw/references/setup-typescript-config.md | 74 + .../references/setup-unhandled-requests.md | 70 + .../references/setup-worker-script-commit.md | 65 + .../msw/references/test-async-utilities.md | 81 + .../test-avoid-request-assertions.md | 87 + .../references/test-clear-request-cache.md | 85 + .../references/test-concurrent-boundary.md | 88 + .../msw/references/test-fake-timers-config.md | 91 + .../msw/references/test-jsdom-environment.md | 67 + .../msw/references/test-reset-handlers.md | 63 + .agents/skills/nextjs/SKILL.md | 115 + .../references/action-error-handling.md | 75 + .../references/action-optimistic-updates.md | 74 + .../references/action-pending-states.md | 68 + .../nextjs/references/action-revalidation.md | 78 + .../references/action-server-action-forms.md | 75 + .../nextjs/references/build-barrel-files.md | 50 + .../references/build-dynamic-imports.md | 62 + .../references/build-external-packages.md | 48 + .../build-optimize-package-imports.md | 42 + .../references/build-turbopack-config.md | 71 + .../nextjs/references/cache-fetch-options.md | 53 + .../nextjs/references/cache-react-cache.md | 58 + .../references/cache-revalidate-path.md | 62 + .../nextjs/references/cache-revalidate-tag.md | 65 + .../nextjs/references/cache-segment-config.md | 63 + .../references/cache-use-cache-directive.md | 57 + .../references/client-children-pattern.md | 75 + .../references/client-hydration-mismatch.md | 101 + .../references/client-third-party-scripts.md | 67 + .../references/client-use-client-boundary.md | 72 + .../references/meta-generate-metadata.md | 70 + .../references/meta-opengraph-images.md | 72 + .../skills/nextjs/references/meta-robots.md | 68 + .../skills/nextjs/references/meta-sitemap.md | 76 + .../references/route-instant-navigations.md | 97 + .../references/route-intercepting-routes.md | 76 + .../nextjs/references/route-not-found.md | 59 + .../references/route-parallel-routes.md | 79 + .../references/route-partial-prefetching.md | 87 + .../nextjs/references/route-prefetching.md | 71 + .../nextjs/references/route-proxy-ts.md | 62 + .../server-avoid-client-fetching.md | 71 + .../references/server-component-streaming.md | 70 + .../references/server-data-colocation.md | 63 + .../references/server-error-handling.md | 79 + .../references/server-parallel-fetching.md | 69 + .../references/server-preload-pattern.md | 68 + .../nextjs/references/stream-error-tsx.md | 67 + .../nextjs/references/stream-loading-tsx.md | 63 + .../references/stream-nested-suspense.md | 82 + .../references/stream-skeleton-matching.md | 72 + .../references/stream-suspense-boundaries.md | 62 + .agents/skills/nuqs/SKILL.md | 110 + .../references/advanced-custom-parsers.md | 70 + .../nuqs/references/advanced-eq-function.md | 94 + .../references/advanced-framework-adapters.md | 82 + .../nuqs/references/advanced-url-keys.md | 62 + .../nuqs/references/debug-common-errors.md | 53 + .../nuqs/references/debug-enable-logging.md | 51 + .../skills/nuqs/references/debug-testing.md | 55 + .../nuqs/references/history-back-sync.md | 51 + .../references/history-push-navigation.md | 76 + .../references/history-replace-ephemeral.md | 87 + .../references/history-scroll-behavior.md | 60 + .../nuqs/references/parser-array-format.md | 59 + .../nuqs/references/parser-date-format.md | 67 + .../nuqs/references/parser-enum-validation.md | 81 + .../nuqs/references/parser-hex-colors.md | 68 + .../nuqs/references/parser-index-offset.md | 72 + .../nuqs/references/parser-json-validation.md | 97 + .../references/parser-use-typed-parsers.md | 58 + .../nuqs/references/parser-with-default.md | 65 + .../nuqs/references/perf-avoid-rerender.md | 88 + .../nuqs/references/perf-clear-on-default.md | 55 + .../nuqs/references/perf-debounce-search.md | 82 + .../nuqs/references/perf-serialize-utility.md | 81 + .../nuqs/references/perf-throttle-updates.md | 66 + .../nuqs/references/server-next15-async.md | 80 + .../references/server-parse-before-get.md | 82 + .../references/server-search-params-cache.md | 78 + .../nuqs/references/server-shallow-false.md | 74 + .../nuqs/references/server-share-parsers.md | 74 + .../nuqs/references/server-use-transition.md | 96 + .../nuqs/references/setup-import-server.md | 72 + .../nuqs/references/setup-nextjs-version.md | 64 + .../nuqs/references/setup-nuqs-adapter.md | 77 + .../nuqs/references/setup-shared-parsers.md | 73 + .../nuqs/references/setup-use-client.md | 69 + .../nuqs/references/state-avoid-derived.md | 84 + .../nuqs/references/state-clear-with-null.md | 81 + .../references/state-controlled-inputs.md | 83 + .../references/state-functional-updates.md | 68 + .../references/state-options-inheritance.md | 78 + .../nuqs/references/state-setter-return.md | 78 + .../nuqs/references/state-use-query-states.md | 75 + .agents/skills/playwright/SKILL.md | 114 + .../references/arch-cleanup-state.md | 83 + .../playwright/references/arch-fixtures.md | 89 + .../references/arch-page-object-model.md | 80 + .../references/arch-parallel-execution.md | 75 + .../references/arch-test-isolation.md | 61 + .../references/arch-test-production.md | 74 + .../references/assert-aria-snapshots.md | 58 + .../playwright/references/auth-api-login.md | 99 + .../references/auth-multiple-roles.md | 111 + .../references/auth-parallel-workers.md | 101 + .../references/auth-session-storage.md | 106 + .../references/auth-storage-state.md | 97 + .../references/debug-ci-reporters.md | 81 + .../playwright/references/debug-inspector.md | 86 + .../references/debug-screenshots-videos.md | 85 + .../references/debug-trace-viewer.md | 79 + .../playwright/references/loc-avoid-xpath.md | 64 + .../references/loc-chained-locators.md | 87 + .../playwright/references/loc-data-testid.md | 80 + .../references/loc-frame-locator.md | 45 + .../references/loc-label-selectors.md | 78 + .../references/loc-placeholder-selector.md | 87 + .../references/loc-role-selectors.md | 74 + .../references/loc-text-selectors.md | 77 + .../references/mock-abort-requests.md | 107 + .../references/mock-api-responses.md | 91 + .../playwright/references/mock-har-files.md | 100 + .../references/mock-intercept-modify.md | 101 + .../references/mock-network-conditions.md | 98 + .../references/next-app-router-navigation.md | 87 + .../references/next-baseurl-config.md | 108 + .../references/next-server-actions.md | 90 + .../references/next-server-components.md | 92 + .../references/next-wait-hydration.md | 103 + .../references/perf-browser-selection.md | 99 + .../playwright/references/perf-headless-ci.md | 100 + .../playwright/references/perf-retries.md | 100 + .../references/perf-reuse-server.md | 87 + .../playwright/references/perf-sharding.md | 105 + .../references/wait-action-retries.md | 83 + .../references/wait-avoid-hard-waits.md | 90 + .../references/wait-custom-timeout.md | 98 + .../references/wait-network-idle.md | 65 + .../references/wait-soft-assertions.md | 78 + .../references/wait-web-first-assertions.md | 91 + .agents/skills/react-hook-form/SKILL.md | 119 + .../references/adv-devtools-performance.md | 69 + .../references/adv-formprovider-memo.md | 78 + .../references/adv-opaque-types.md | 52 + .../references/adv-testing-wrapper.md | 63 + .../array-complete-default-objects.md | 66 + .../array-separate-crud-operations.md | 76 + .../array-unique-fieldarray-per-name.md | 58 + .../references/array-use-field-id-as-key.md | 54 + .../array-virtualization-formprovider.md | 64 + .../ctrl-avoid-double-registration.md | 46 + .../references/ctrl-controller-field-props.md | 56 + .../ctrl-local-state-combination.md | 69 + ...ctrl-single-usecontroller-per-component.md | 66 + .../ctrl-usecontroller-isolation.md | 64 + .../formcfg-async-default-values.md | 69 + .../references/formcfg-default-values.md | 57 + .../references/formcfg-revalidate-mode.md | 52 + .../references/formcfg-should-unregister.md | 64 + .../formcfg-useeffect-dependency.md | 54 + .../references/formcfg-validation-mode.md | 55 + .../formstate-avoid-isvalid-with-onsubmit.md | 57 + .../formstate-destructure-formstate.md | 48 + ...ormstate-getfieldstate-for-single-field.md | 54 + .../formstate-subscribe-to-specific-fields.md | 54 + .../formstate-useformstate-isolation.md | 65 + .../integ-mui-controller-pattern.md | 59 + .../references/integ-shadcn-form-import.md | 64 + .../references/integ-shadcn-select-wiring.md | 64 + .../integ-typed-submit-server-action.md | 52 + .../references/integ-value-transform.md | 59 + .../references/sub-avoid-watch-in-render.md | 48 + .../references/sub-deep-subscription.md | 62 + .../sub-useformcontext-sparingly.md | 58 + .../references/sub-usewatch-default-value.md | 50 + .../references/sub-usewatch-over-watch.md | 58 + .../references/sub-usewatch-with-getvalues.md | 54 + .../references/sub-watch-specific-fields.md | 54 + .../references/valid-delay-error.md | 52 + .../valid-dynamic-schema-factory.md | 57 + .../valid-error-message-strategy.md | 82 + .../references/valid-form-level-validate.md | 47 + .../references/valid-inline-vs-resolver.md | 63 + .../references/valid-native-validation.md | 60 + .../references/valid-resolver-caching.md | 58 + .../references/valid-trigger-should-touch.md | 44 + .agents/skills/react/SKILL.md | 87 + .agents/skills/react/references/_sections.md | 46 + .../references/conc-automatic-batching.md | 64 + .../react/references/conc-concurrent-safe.md | 71 + .../references/conc-suspense-fallback.md | 66 + .../references/conc-use-deferred-value.md | 65 + .../react/references/conc-use-transition.md | 75 + .../react/references/conc-view-transitions.md | 81 + .../references/data-cache-deduplication.md | 60 + .../react/references/data-error-boundaries.md | 76 + .../references/data-parallel-fetching.md | 74 + .../references/data-suspense-data-fetching.md | 76 + .../skills/react/references/data-use-hook.md | 77 + .../references/effect-avoid-unnecessary.md | 69 + .../skills/react/references/effect-cleanup.md | 75 + .../references/effect-object-dependencies.md | 56 + .../references/effect-use-browser-only.md | 62 + .../references/effect-use-effect-event.md | 53 + .../effect-use-sync-external-store.md | 80 + .../skills/react/references/form-actions.md | 83 + .../react/references/form-use-action-state.md | 80 + .../react/references/form-use-form-status.md | 68 + .../react/references/form-use-optimistic.md | 77 + .../react/references/form-validation.md | 89 + .../react/references/memo-avoid-premature.md | 68 + .../skills/react/references/memo-compiler.md | 84 + .../react/references/memo-react-memo.md | 72 + .../react/references/memo-use-callback.md | 70 + .../skills/react/references/memo-use-memo.md | 53 + .../react/references/rcomp-composition.md | 75 + .../references/rcomp-controlled-components.md | 63 + .../react/references/rcomp-fragment-refs.md | 71 + .../react/references/rcomp-key-reset.md | 74 + .../react/references/rcomp-render-props.md | 69 + .../references/rsc-avoid-client-only-libs.md | 66 + .../references/rsc-composition-pattern.md | 90 + .../react/references/rsc-context-provider.md | 50 + .../references/rsc-data-fetching-server.md | 68 + .../references/rsc-serializable-props.md | 70 + .../references/rsc-server-client-boundary.md | 63 + .../skills/react/references/rsc-streaming.md | 64 + .../references/rstate-context-optimization.md | 68 + .../react/references/rstate-derived-values.md | 70 + .../references/rstate-functional-updates.md | 58 + .../references/rstate-lazy-initialization.md | 59 + .../react/references/rstate-use-reducer.md | 77 + .agents/skills/shadcn/SKILL.md | 110 + .../references/ally-ensure-color-contrast.md | 62 + .../ally-maintain-focus-management.md | 84 + .../ally-preserve-aria-attributes.md | 77 + .../ally-preserve-keyboard-navigation.md | 72 + .../references/ally-provide-sr-only-labels.md | 75 + .../references/arch-current-cli-registry.md | 61 + .../arch-extend-variants-with-cva.md | 67 + ...-forward-refs-for-composable-components.md | 83 + .../arch-isolate-component-variants.md | 82 + ...arch-preserve-radix-primitive-structure.md | 57 + .../references/arch-unified-radix-package.md | 44 + .../arch-use-asChild-for-custom-triggers.md | 49 + .../arch-use-cn-for-class-merging.md | 62 + .../comp-combine-command-with-popover.md | 106 + .../comp-compose-with-compound-components.md | 104 + .../comp-create-reusable-form-fields.md | 157 + .../references/comp-nest-dialogs-correctly.md | 108 + .../comp-use-drawer-for-mobile-modals.md | 128 + .../comp-use-slot-pattern-for-flexibility.md | 118 + .../data-empty-states-with-guidance.md | 95 + .../references/data-paginate-server-side.md | 108 + .../data-use-skeleton-loading-states.md | 104 + ...a-use-tanstack-table-for-complex-tables.md | 121 + .../references/data-virtualize-large-lists.md | 82 + .../form-handle-async-validation.md | 104 + .../form-reset-form-state-correctly.md | 92 + .../form-show-validation-errors-correctly.md | 58 + .../form-use-react-hook-form-integration.md | 106 + .../form-use-zod-for-schema-validation.md | 86 + ...rf-avoid-unnecessary-rerenders-in-forms.md | 88 + .../references/perf-debounce-search-inputs.md | 85 + .../perf-lazy-load-heavy-components.md | 90 + .../perf-memoize-expensive-renders.md | 90 + .../references/perf-optimize-icon-imports.md | 60 + .../state-colocate-state-with-components.md | 103 + .../state-lift-state-to-appropriate-level.md | 103 + ...e-prefer-uncontrolled-for-simple-inputs.md | 91 + .../state-use-controlled-dialog-state.md | 127 + .../style-avoid-important-overrides.md | 58 + .../style-consistent-spacing-scale.md | 67 + .../references/style-dark-mode-support.md | 83 + .../style-responsive-design-patterns.md | 75 + .../style-use-css-variables-for-theming.md | 56 + .../style-use-tailwind-theme-extend.md | 63 + .agents/skills/tailwind/SKILL.md | 109 + .../tailwind/references/anim-3d-transforms.md | 56 + .../references/anim-gpu-accelerated.md | 47 + .../references/anim-gradient-interpolation.md | 46 + .../references/anim-starting-style.md | 63 + .../tailwind/references/build-cli-package.md | 43 + .../references/build-content-detection.md | 44 + .../tailwind/references/build-css-import.md | 36 + .../tailwind/references/build-node-version.md | 44 + .../references/build-postcss-simplify.md | 40 + .../tailwind/references/build-vite-plugin.md | 39 + .../references/bundle-avoid-cdn-production.md | 56 + .../references/bundle-avoid-preprocessors.md | 53 + .../references/bundle-css-minification.md | 57 + .../bundle-remove-unused-plugins.md | 55 + .../references/bundle-split-critical-css.md | 62 + .../references/comp-avoid-apply-overuse.md | 58 + .../references/comp-container-customize.md | 59 + .../references/comp-reference-directive.md | 59 + .../tailwind/references/comp-smart-sorting.md | 50 + .../references/comp-utility-file-scope.md | 61 + .../references/gen-avoid-theme-bloat.md | 47 + .../references/gen-css-first-config.md | 54 + .../references/gen-css-variable-syntax.md | 43 + .../references/gen-dynamic-utilities.md | 51 + .../tailwind/references/gen-oklch-colors.md | 40 + .../references/gen-utility-directive.md | 52 + .../references/resp-container-queries.md | 55 + .../references/resp-custom-breakpoints.md | 54 + .../references/resp-hover-capability.md | 60 + .../references/resp-logical-properties.md | 51 + .../tailwind/references/resp-mobile-first.md | 48 + .../tailwind/references/theme-color-scheme.md | 55 + .../references/theme-dark-mode-class.md | 59 + .../references/theme-prefix-variables.md | 56 + .../references/theme-runtime-variables.md | 55 + .../references/theme-semantic-tokens.md | 65 + .../references/util-explicit-colors.md | 43 + .../references/util-gradient-via-none.md | 37 + .../references/util-important-modifier.md | 43 + .../references/util-opacity-modifier.md | 50 + .../references/util-renamed-utilities.md | 45 + .../references/util-variant-stacking.md | 41 + .agents/skills/tanstack-query/SKILL.md | 117 + .../references/cache-enabled-option.md | 76 + .../references/cache-global-defaults.md | 73 + .../cache-invalidation-precision.md | 78 + .../cache-placeholder-vs-initial.md | 69 + .../references/cache-refetch-triggers.md | 68 + .../references/cache-staletime-gctime.md | 71 + .../references/error-conditional-retry.md | 93 + .../references/error-display-patterns.md | 100 + .../references/error-global-handler.md | 91 + .../references/error-retry-config.md | 80 + .../references/error-throw-on-error.md | 96 + .../references/infinite-flatten-pages.md | 108 + .../references/infinite-loading-states.md | 96 + .../references/infinite-max-pages.md | 86 + .../references/infinite-refetch-behavior.md | 79 + .../references/mutation-avoid-parallel.md | 92 + .../references/mutation-cancel-queries.md | 72 + .../mutation-invalidate-onsettled.md | 66 + .../references/mutation-optimistic-updates.md | 81 + .../references/mutation-setquerydata.md | 67 + .../references/prefetch-avoid-waterfalls.md | 98 + .../references/prefetch-flatten-api.md | 70 + .../references/prefetch-in-queryfn.md | 97 + .../references/prefetch-infinite-query.md | 60 + .../references/prefetch-on-hover.md | 94 + .../references/prefetch-server-components.md | 88 + .../references/render-notify-props.md | 66 + .../references/render-select-derived.md | 86 + .../references/render-select-memoize.md | 75 + .../references/render-structural-sharing.md | 88 + .../references/render-tracked-props.md | 80 + .../suspense-boundaries-placement.md | 97 + .../references/suspense-error-boundaries.md | 100 + .../references/suspense-parallel-queries.md | 93 + .../references/suspense-use-suspense-hooks.md | 66 + .../references/tquery-always-arrays.md | 49 + .../references/tquery-colocate-keys.md | 66 + .../references/tquery-hierarchical-keys.md | 61 + .../references/tquery-key-factories.md | 58 + .../references/tquery-options-pattern.md | 78 + .../references/tquery-serializable-objects.md | 60 + .agents/skills/tdd/SKILL.md | 114 + .../tdd/references/assert-custom-matchers.md | 86 + .../tdd/references/assert-error-messages.md | 64 + .../assert-no-assertions-antipattern.md | 70 + .../tdd/references/assert-snapshot-testing.md | 71 + .../references/assert-specific-assertions.md | 71 + .../references/cycle-maintain-test-list.md | 68 + .../references/cycle-minimal-code-to-pass.md | 62 + .../references/cycle-refactor-after-green.md | 58 + .../tdd/references/cycle-small-increments.md | 69 + .../cycle-verify-test-fails-first.md | 64 + .../tdd/references/cycle-write-test-first.md | 63 + .../references/data-avoid-mystery-guests.md | 62 + .../tdd/references/data-builder-pattern.md | 99 + .../tdd/references/data-minimal-setup.md | 69 + .../tdd/references/data-unique-identifiers.md | 79 + .../tdd/references/data-use-factories.md | 87 + .../tdd/references/design-aaa-pattern.md | 68 + .../references/design-avoid-logic-in-tests.md | 74 + .../design-descriptive-test-names.md | 64 + .../design-one-assertion-per-test.md | 66 + ...design-test-behavior-not-implementation.md | 69 + .../tdd/references/design-test-edge-cases.md | 83 + .../references/isolate-deterministic-tests.md | 80 + .../isolate-mock-external-dependencies.md | 69 + .../tdd/references/isolate-no-shared-state.md | 73 + .../isolate-prefer-stubs-over-mocks.md | 72 + .../isolate-use-dependency-injection.md | 91 + .../tdd/references/org-file-structure.md | 76 + .../tdd/references/org-group-by-behavior.md | 68 + .../tdd/references/org-parameterized-tests.md | 79 + .../tdd/references/org-setup-teardown.md | 84 + .../tdd/references/org-test-utilities.md | 98 + .../references/perf-avoid-network-calls.md | 78 + .../skills/tdd/references/perf-avoid-sleep.md | 82 + .../tdd/references/perf-fast-unit-tests.md | 48 + .../tdd/references/perf-fix-flaky-tests.md | 83 + .../tdd/references/perf-parallelize-tests.md | 87 + .../tdd/references/strat-coverage-targets.md | 70 + .../references/strat-e2e-critical-paths.md | 78 + .../strat-integration-boundaries.md | 79 + .../tdd/references/strat-mutation-testing.md | 71 + .../tdd/references/strat-test-pyramid.md | 58 + .agents/skills/typescript/SKILL.md | 103 + .../references/advanced-branded-types.md | 83 + .../references/advanced-satisfies-operator.md | 94 + .../advanced-template-literal-types.md | 105 + .../references/async-avoid-loop-await.md | 78 + .../async-avoid-unnecessary-async.md | 61 + .../references/async-defer-await.md | 74 + .../references/async-explicit-return-types.md | 79 + .../references/async-parallel-promises.md | 63 + .../references/mem-avoid-closure-leaks.md | 88 + .../references/mem-avoid-global-state.md | 97 + .../references/mem-cleanup-event-listeners.md | 111 + .../typescript/references/mem-clear-timers.md | 106 + .../mem-use-weakmap-for-metadata.md | 84 + .../references/module-avoid-barrel-imports.md | 70 + .../module-avoid-circular-dependencies.md | 92 + .../module-control-types-inclusion.md | 92 + .../references/module-dynamic-imports.md | 78 + .../references/module-use-type-imports.md | 80 + .../runtime-avoid-object-spread-in-loops.md | 79 + .../runtime-cache-property-access.md | 85 + .../runtime-prefer-array-methods.md | 73 + .../runtime-use-for-of-for-iteration.md | 89 + .../references/runtime-use-set-for-lookups.md | 64 + .../references/runtime-use-string-methods.md | 79 + .../references/safety-assertion-functions.md | 92 + .../references/safety-const-assertions.md | 77 + .../references/safety-exhaustive-checks.md | 83 + .../safety-prefer-unknown-over-any.md | 76 + .../references/safety-strict-null-checks.md | 72 + .../references/safety-use-type-guards.md | 86 + .../references/tscfg-enable-incremental.md | 68 + .../references/tscfg-exclude-properly.md | 85 + .../references/tscfg-isolate-modules.md | 68 + .../references/tscfg-project-references.md | 97 + .../references/tscfg-skip-lib-check.md | 63 + .../references/tscfg-strict-function-types.md | 67 + .../references/tscfg-typescript-7.md | 75 + .../references/type-avoid-deep-generics.md | 81 + .../references/type-avoid-large-unions.md | 57 + .../references/type-explicit-return-types.md | 65 + .../type-extract-conditional-types.md | 57 + .../type-interfaces-over-intersections.md | 41 + .../references/type-limit-recursion-depth.md | 65 + .../references/type-simplify-mapped-types.md | 71 + .agents/skills/ui-design/SKILL.md | 102 + .../ui-design/references/access-alt-text.md | 63 + .../references/access-aria-labels.md | 57 + .../references/access-focus-indicators.md | 53 + .../references/access-heading-hierarchy.md | 48 + .../references/access-keyboard-navigation.md | 52 + .../references/access-semantic-html.md | 53 + .../references/access-target-size.md | 56 + .../references/anim-duration-easing.md | 77 + .../references/anim-gpu-properties.md | 75 + .../references/anim-reduced-motion.md | 82 + .../ui-design/references/anim-will-change.md | 78 + .../references/color-contrast-ratio.md | 67 + .../ui-design/references/color-dark-mode.md | 74 + .../references/color-not-only-indicator.md | 79 + .../references/color-semantic-palette.md | 64 + .../ui-design/references/cwv-critical-css.md | 55 + .../ui-design/references/cwv-improve-inp.md | 70 + .../references/cwv-lazy-load-offscreen.md | 60 + .../ui-design/references/cwv-minimize-cls.md | 66 + .../ui-design/references/cwv-optimize-lcp.md | 59 + .../references/cwv-responsive-images.md | 63 + .../ui-design/references/form-autocomplete.md | 62 + .../references/form-error-messages.md | 61 + .../references/form-inline-validation.md | 67 + .../ui-design/references/form-input-types.md | 63 + .../ui-design/references/form-labels-above.md | 74 + .../ui-design/references/layout-f-pattern.md | 65 + .../references/layout-grid-system.md | 67 + .../references/layout-proximity-grouping.md | 57 + .../ui-design/references/layout-single-cta.md | 64 + .../references/layout-visual-hierarchy.md | 69 + .../ui-design/references/layout-whitespace.md | 70 + .../references/resp-container-queries.md | 64 + .../references/resp-fluid-typography.md | 65 + .../ui-design/references/resp-mobile-first.md | 83 + .../references/resp-touch-targets.md | 67 + .../references/resp-viewport-meta.md | 57 + .../ui-design/references/typo-font-display.md | 61 + .../ui-design/references/typo-line-height.md | 66 + .../references/typo-preload-fonts.md | 62 + .../references/typo-readable-line-length.md | 58 + .../references/typo-system-font-stack.md | 57 + .../vercel-composition-patterns/SKILL.md | 74 + .../rules/architecture-avoid-boolean-props.md | 102 + .../rules/architecture-compound-components.md | 112 + .../patterns-children-over-render-props.md | 87 + .../rules/patterns-explicit-variants.md | 100 + .../rules/react19-no-forwardref.md | 42 + .../rules/state-context-interface.md | 191 + .../rules/state-decouple-implementation.md | 113 + .../rules/state-lift-state.md | 125 + .../vercel-react-best-practices/SKILL.md | 134 + .../rules/advanced-effect-event-deps.md | 56 + .../rules/advanced-event-handler-refs.md | 55 + .../rules/advanced-init-once.md | 42 + .../rules/advanced-use-latest.md | 39 + .../rules/async-api-routes.md | 38 + .../async-cheap-condition-before-await.md | 37 + .../rules/async-defer-await.md | 82 + .../rules/async-dependencies.md | 51 + .../rules/async-parallel.md | 28 + .../rules/async-suspense-boundaries.md | 99 + .../rules/bundle-analyzable-paths.md | 63 + .../rules/bundle-barrel-imports.md | 60 + .../rules/bundle-conditional.md | 31 + .../rules/bundle-defer-third-party.md | 49 + .../rules/bundle-dynamic-imports.md | 35 + .../rules/bundle-preload.md | 50 + .../rules/client-event-listeners.md | 74 + .../rules/client-localstorage-schema.md | 71 + .../rules/client-passive-event-listeners.md | 48 + .../rules/client-swr-dedup.md | 56 + .../rules/js-batch-dom-css.md | 107 + .../rules/js-cache-function-results.md | 80 + .../rules/js-cache-property-access.md | 28 + .../rules/js-cache-storage.md | 70 + .../rules/js-combine-iterations.md | 32 + .../rules/js-early-exit.md | 50 + .../rules/js-flatmap-filter.md | 60 + .../rules/js-hoist-regexp.md | 45 + .../rules/js-index-maps.md | 37 + .../rules/js-length-check-first.md | 49 + .../rules/js-min-max-loop.md | 82 + .../rules/js-request-idle-callback.md | 105 + .../rules/js-set-map-lookups.md | 24 + .../rules/js-tosorted-immutable.md | 57 + .../rules/rendering-activity.md | 26 + .../rules/rendering-animate-svg-wrapper.md | 47 + .../rules/rendering-conditional-render.md | 40 + .../rules/rendering-content-visibility.md | 38 + .../rules/rendering-hoist-jsx.md | 46 + .../rules/rendering-hydration-no-flicker.md | 82 + .../rendering-hydration-suppress-warning.md | 30 + .../rules/rendering-resource-hints.md | 85 + .../rules/rendering-script-defer-async.md | 68 + .../rules/rendering-svg-precision.md | 28 + .../rules/rendering-usetransition-loading.md | 79 + .../rules/rerender-defer-reads.md | 39 + .../rules/rerender-dependencies.md | 45 + .../rules/rerender-derived-state-no-effect.md | 40 + .../rules/rerender-derived-state.md | 29 + .../rules/rerender-functional-setstate.md | 74 + .../rules/rerender-lazy-state-init.md | 58 + .../rules/rerender-memo-with-default-value.md | 38 + .../rules/rerender-memo.md | 44 + .../rules/rerender-move-effect-to-event.md | 45 + .../rules/rerender-no-inline-components.md | 82 + .../rerender-simple-expression-in-memo.md | 35 + .../rules/rerender-split-combined-hooks.md | 64 + .../rules/rerender-transitions.md | 40 + .../rules/rerender-use-deferred-value.md | 59 + .../rerender-use-ref-transient-values.md | 73 + .../rules/server-after-nonblocking.md | 73 + .../rules/server-auth-actions.md | 96 + .../rules/server-cache-lru.md | 41 + .../rules/server-cache-react.md | 76 + .../rules/server-dedup-props.md | 65 + .../rules/server-hoist-static-io.md | 149 + .../rules/server-no-shared-module-state.md | 50 + .../rules/server-parallel-fetching.md | 83 + .../rules/server-parallel-nested-fetching.md | 34 + .../rules/server-serialization.md | 38 + .agents/skills/vitest/SKILL.md | 122 + .../vitest/references/assert-edge-cases.md | 83 + .../references/assert-expect-assertions.md | 95 + .../assert-one-assertion-concept.md | 94 + .../references/assert-specific-matchers.md | 83 + .../references/assert-toequal-vs-tobe.md | 91 + .../vitest/references/async-act-wrapper.md | 79 + .../references/async-await-assertions.md | 45 + .../references/async-concurrent-expect.md | 60 + .../vitest/references/async-error-handling.md | 72 + .../vitest/references/async-fake-timers.md | 82 + .../references/async-return-promises.md | 60 + .../references/async-waitfor-polling.md | 84 + .../references/env-browser-api-mocking.md | 96 + .../vitest/references/env-globals-config.md | 85 + .../references/env-per-file-override.md | 115 + .../vitest/references/env-setup-files.md | 94 + .../references/mock-avoid-overmocking.md | 98 + .../references/mock-clear-between-tests.md | 86 + .../mock-implementation-not-value.md | 81 + .../vitest/references/mock-msw-network.md | 96 + .../vitest/references/mock-spyon-vs-mock.md | 85 + .../vitest/references/mock-type-safety.md | 97 + .../references/mock-vi-mock-hoisting.md | 95 + .../vitest/references/org-describe-nesting.md | 85 + .../vitest/references/org-file-colocation.md | 93 + .../vitest/references/org-test-naming.md | 86 + .../vitest/references/org-test-skip-only.md | 75 + .../vitest/references/perf-bail-fast-fail.md | 84 + .../references/perf-bench-test-context.md | 59 + .../references/perf-disable-isolation.md | 91 + .../vitest/references/perf-happy-dom.md | 103 + .../vitest/references/perf-pool-selection.md | 78 + .../vitest/references/perf-run-mode-ci.md | 93 + .../skills/vitest/references/perf-sharding.md | 101 + .../references/setup-avoid-shared-state.md | 98 + .../references/setup-beforeall-expensive.md | 81 + .../references/setup-beforeeach-cleanup.md | 83 + .../vitest/references/setup-reset-modules.md | 91 + .../vitest/references/setup-restore-mocks.md | 88 + .../vitest/references/setup-test-factories.md | 104 + .../references/setup-vitest5-migration.md | 64 + .../vitest/references/snap-avoid-large.md | 76 + .../vitest/references/snap-describe-intent.md | 78 + .../references/snap-inline-over-file.md | 73 + .../vitest/references/snap-review-updates.md | 79 + .../references/snap-stable-serialization.md | 97 + .agents/skills/web-design-guidelines/SKILL.md | 39 + .agents/skills/zod/SKILL.md | 128 + .../zod/references/compose-intersection.md | 147 + .../zod/references/compose-lazy-recursive.md | 154 + .agents/skills/zod/references/compose-pipe.md | 113 + .../zod/references/compose-preprocess.md | 142 + .../zod/references/compose-shared-schemas.md | 138 + .../error-avoid-throwing-in-refine.md | 127 + .../zod/references/error-custom-messages.md | 113 + .agents/skills/zod/references/error-i18n.md | 141 + .../zod/references/error-path-for-nested.md | 133 + .../zod/references/error-use-flatten.md | 85 + .../references/object-discriminated-unions.md | 138 + .../object-extend-for-composition.md | 145 + .../references/object-optional-vs-nullable.md | 117 + .../references/object-partial-for-updates.md | 142 + .../skills/zod/references/object-pick-omit.md | 146 + .../zod/references/object-strict-vs-strip.md | 70 + .../parse-async-for-async-refinements.md | 118 + .../parse-avoid-double-validation.md | 129 + .../zod/references/parse-handle-all-issues.md | 125 + .../zod/references/parse-never-trust-json.md | 113 + .../zod/references/parse-use-safeparse.md | 102 + .../zod/references/parse-validate-early.md | 120 + .../parse-validate-for-boolean-checks.md | 64 + .agents/skills/zod/references/perf-arrays.md | 153 + .../references/perf-avoid-dynamic-creation.md | 97 + .../zod/references/perf-cache-schemas.md | 138 + .../zod/references/perf-compile-schemas.md | 76 + .../zod/references/perf-lazy-loading.md | 135 + .../skills/zod/references/perf-zod-mini.md | 110 + .../skills/zod/references/refine-add-path.md | 141 + .agents/skills/zod/references/refine-catch.md | 143 + .../skills/zod/references/refine-defaults.md | 131 + .../zod/references/refine-transform-coerce.md | 105 + .../skills/zod/references/refine-use-codec.md | 41 + .../zod/references/refine-vs-superrefine.md | 152 + .../references/schema-avoid-optional-abuse.md | 93 + .../schema-coercion-for-form-data.md | 88 + .../references/schema-string-validations.md | 114 + .../skills/zod/references/schema-use-enums.md | 115 + .../schema-use-primitives-correctly.md | 61 + .../references/schema-use-unknown-not-any.md | 88 + .../zod/references/type-branded-types.md | 102 + .../zod/references/type-enable-strict-mode.md | 130 + .../type-export-schemas-and-types.md | 116 + .../zod/references/type-input-vs-output.md | 116 + .../skills/zod/references/type-use-z-infer.md | 110 + .claude/skills/feature-arch/SKILL.md | 110 + .../bound-event-based-communication.md | 84 + .../references/bound-feature-isolation.md | 88 + .../bound-feature-scoped-routing.md | 76 + .../references/bound-feature-size.md | 74 + .../references/bound-interface-contracts.md | 83 + .../references/bound-minimize-shared-state.md | 73 + .../references/fcomp-colocate-styles.md | 88 + .../fcomp-composition-over-props.md | 100 + .../fcomp-container-presentational.md | 99 + .../references/fcomp-error-boundaries.md | 99 + .../fcomp-props-as-data-boundary.md | 88 + .../references/fcomp-single-responsibility.md | 99 + .../references/fquery-avoid-n-plus-one.md | 80 + .../fquery-colocate-with-feature.md | 70 + .../references/fquery-feature-scoped-keys.md | 72 + .../references/fquery-parallel-fetching.md | 71 + .../fquery-server-component-fetching.md | 88 + .../fquery-single-responsibility.md | 66 + .../references/fstate-context-sparingly.md | 73 + .../fstate-feature-scoped-stores.md | 79 + .../references/fstate-lift-minimally.md | 85 + .../references/fstate-reset-on-unmount.md | 89 + .../fstate-server-state-separation.md | 93 + .../references/import-avoid-barrel-files.md | 63 + .../references/import-no-cross-feature.md | 84 + .../references/import-path-aliases.md | 64 + .../references/import-public-api.md | 67 + .../references/import-type-only.md | 81 + .../references/import-unidirectional-flow.md | 82 + .../references/name-descriptive-exports.md | 65 + .../references/name-feature-naming.md | 60 + .../references/name-file-conventions.md | 79 + .../references/struct-app-layer.md | 73 + .../references/struct-feature-folders.md | 70 + .../struct-feature-self-contained.md | 62 + .../references/struct-flat-hierarchy.md | 58 + .../references/struct-optional-segments.md | 72 + .../references/struct-shared-layer.md | 68 + .../references/test-colocate-with-feature.md | 78 + .../references/test-feature-isolation.md | 88 + .../test-integration-at-app-layer.md | 87 + .../references/test-shared-utilities.md | 94 + .claude/skills/msw/SKILL.md | 121 + .../references/advanced-bypass-requests.md | 81 + .../msw/references/advanced-cookies-auth.md | 119 + .../references/advanced-dynamic-scenarios.md | 114 + .../msw/references/advanced-file-uploads.md | 109 + .../advanced-playwright-integration.md | 78 + .../msw/references/advanced-vitest-browser.md | 100 + .../references/advanced-websocket-mocking.md | 87 + .../msw/references/debug-common-issues.md | 79 + .../msw/references/debug-lifecycle-events.md | 88 + .../msw/references/debug-request-logging.md | 113 + .../references/debug-verify-interception.md | 95 + .../msw/references/graphql-batched-queries.md | 93 + .../msw/references/graphql-error-responses.md | 119 + .../references/graphql-operation-handlers.md | 101 + .../msw/references/graphql-schema-first.md | 76 + .../references/graphql-variables-access.md | 123 + .../msw/references/handler-absolute-urls.md | 70 + .../msw/references/handler-domain-grouping.md | 81 + .../references/handler-happy-path-first.md | 60 + .../handler-request-body-parsing.md | 76 + .../references/handler-resolver-argument.md | 86 + .../handler-reusability-environments.md | 80 + .../references/handler-shared-resolvers.md | 99 + .../references/handler-v2-response-syntax.md | 94 + .../msw/references/match-custom-predicate.md | 99 + .../msw/references/match-handler-order.md | 93 + .../msw/references/match-http-methods.md | 98 + .../msw/references/match-query-params.md | 89 + .../msw/references/match-url-patterns.md | 87 + .../msw/references/response-custom-headers.md | 125 + .../references/response-delay-realistic.md | 92 + .../references/response-error-simulation.md | 110 + .../response-http-response-helpers.md | 83 + .../references/response-one-time-handlers.md | 103 + .../msw/references/response-streaming.md | 114 + .../msw/references/setup-lifecycle-hooks.md | 57 + .../msw/references/setup-node-version.md | 72 + .../setup-server-node-entrypoint.md | 45 + .../msw/references/setup-typescript-config.md | 74 + .../references/setup-unhandled-requests.md | 70 + .../references/setup-worker-script-commit.md | 65 + .../msw/references/test-async-utilities.md | 81 + .../test-avoid-request-assertions.md | 87 + .../references/test-clear-request-cache.md | 85 + .../references/test-concurrent-boundary.md | 88 + .../msw/references/test-fake-timers-config.md | 91 + .../msw/references/test-jsdom-environment.md | 67 + .../msw/references/test-reset-handlers.md | 63 + .claude/skills/nextjs/SKILL.md | 115 + .../references/action-error-handling.md | 75 + .../references/action-optimistic-updates.md | 74 + .../references/action-pending-states.md | 68 + .../nextjs/references/action-revalidation.md | 78 + .../references/action-server-action-forms.md | 75 + .../nextjs/references/build-barrel-files.md | 50 + .../references/build-dynamic-imports.md | 62 + .../references/build-external-packages.md | 48 + .../build-optimize-package-imports.md | 42 + .../references/build-turbopack-config.md | 71 + .../nextjs/references/cache-fetch-options.md | 53 + .../nextjs/references/cache-react-cache.md | 58 + .../references/cache-revalidate-path.md | 62 + .../nextjs/references/cache-revalidate-tag.md | 65 + .../nextjs/references/cache-segment-config.md | 63 + .../references/cache-use-cache-directive.md | 57 + .../references/client-children-pattern.md | 75 + .../references/client-hydration-mismatch.md | 101 + .../references/client-third-party-scripts.md | 67 + .../references/client-use-client-boundary.md | 72 + .../references/meta-generate-metadata.md | 70 + .../references/meta-opengraph-images.md | 72 + .../skills/nextjs/references/meta-robots.md | 68 + .../skills/nextjs/references/meta-sitemap.md | 76 + .../references/route-instant-navigations.md | 97 + .../references/route-intercepting-routes.md | 76 + .../nextjs/references/route-not-found.md | 59 + .../references/route-parallel-routes.md | 79 + .../references/route-partial-prefetching.md | 87 + .../nextjs/references/route-prefetching.md | 71 + .../nextjs/references/route-proxy-ts.md | 62 + .../server-avoid-client-fetching.md | 71 + .../references/server-component-streaming.md | 70 + .../references/server-data-colocation.md | 63 + .../references/server-error-handling.md | 79 + .../references/server-parallel-fetching.md | 69 + .../references/server-preload-pattern.md | 68 + .../nextjs/references/stream-error-tsx.md | 67 + .../nextjs/references/stream-loading-tsx.md | 63 + .../references/stream-nested-suspense.md | 82 + .../references/stream-skeleton-matching.md | 72 + .../references/stream-suspense-boundaries.md | 62 + .claude/skills/nuqs/SKILL.md | 110 + .../references/advanced-custom-parsers.md | 70 + .../nuqs/references/advanced-eq-function.md | 94 + .../references/advanced-framework-adapters.md | 82 + .../nuqs/references/advanced-url-keys.md | 62 + .../nuqs/references/debug-common-errors.md | 53 + .../nuqs/references/debug-enable-logging.md | 51 + .../skills/nuqs/references/debug-testing.md | 55 + .../nuqs/references/history-back-sync.md | 51 + .../references/history-push-navigation.md | 76 + .../references/history-replace-ephemeral.md | 87 + .../references/history-scroll-behavior.md | 60 + .../nuqs/references/parser-array-format.md | 59 + .../nuqs/references/parser-date-format.md | 67 + .../nuqs/references/parser-enum-validation.md | 81 + .../nuqs/references/parser-hex-colors.md | 68 + .../nuqs/references/parser-index-offset.md | 72 + .../nuqs/references/parser-json-validation.md | 97 + .../references/parser-use-typed-parsers.md | 58 + .../nuqs/references/parser-with-default.md | 65 + .../nuqs/references/perf-avoid-rerender.md | 88 + .../nuqs/references/perf-clear-on-default.md | 55 + .../nuqs/references/perf-debounce-search.md | 82 + .../nuqs/references/perf-serialize-utility.md | 81 + .../nuqs/references/perf-throttle-updates.md | 66 + .../nuqs/references/server-next15-async.md | 80 + .../references/server-parse-before-get.md | 82 + .../references/server-search-params-cache.md | 78 + .../nuqs/references/server-shallow-false.md | 74 + .../nuqs/references/server-share-parsers.md | 74 + .../nuqs/references/server-use-transition.md | 96 + .../nuqs/references/setup-import-server.md | 72 + .../nuqs/references/setup-nextjs-version.md | 64 + .../nuqs/references/setup-nuqs-adapter.md | 77 + .../nuqs/references/setup-shared-parsers.md | 73 + .../nuqs/references/setup-use-client.md | 69 + .../nuqs/references/state-avoid-derived.md | 84 + .../nuqs/references/state-clear-with-null.md | 81 + .../references/state-controlled-inputs.md | 83 + .../references/state-functional-updates.md | 68 + .../references/state-options-inheritance.md | 78 + .../nuqs/references/state-setter-return.md | 78 + .../nuqs/references/state-use-query-states.md | 75 + .claude/skills/playwright/SKILL.md | 114 + .../references/arch-cleanup-state.md | 83 + .../playwright/references/arch-fixtures.md | 89 + .../references/arch-page-object-model.md | 80 + .../references/arch-parallel-execution.md | 75 + .../references/arch-test-isolation.md | 61 + .../references/arch-test-production.md | 74 + .../references/assert-aria-snapshots.md | 58 + .../playwright/references/auth-api-login.md | 99 + .../references/auth-multiple-roles.md | 111 + .../references/auth-parallel-workers.md | 101 + .../references/auth-session-storage.md | 106 + .../references/auth-storage-state.md | 97 + .../references/debug-ci-reporters.md | 81 + .../playwright/references/debug-inspector.md | 86 + .../references/debug-screenshots-videos.md | 85 + .../references/debug-trace-viewer.md | 79 + .../playwright/references/loc-avoid-xpath.md | 64 + .../references/loc-chained-locators.md | 87 + .../playwright/references/loc-data-testid.md | 80 + .../references/loc-frame-locator.md | 45 + .../references/loc-label-selectors.md | 78 + .../references/loc-placeholder-selector.md | 87 + .../references/loc-role-selectors.md | 74 + .../references/loc-text-selectors.md | 77 + .../references/mock-abort-requests.md | 107 + .../references/mock-api-responses.md | 91 + .../playwright/references/mock-har-files.md | 100 + .../references/mock-intercept-modify.md | 101 + .../references/mock-network-conditions.md | 98 + .../references/next-app-router-navigation.md | 87 + .../references/next-baseurl-config.md | 108 + .../references/next-server-actions.md | 90 + .../references/next-server-components.md | 92 + .../references/next-wait-hydration.md | 103 + .../references/perf-browser-selection.md | 99 + .../playwright/references/perf-headless-ci.md | 100 + .../playwright/references/perf-retries.md | 100 + .../references/perf-reuse-server.md | 87 + .../playwright/references/perf-sharding.md | 105 + .../references/wait-action-retries.md | 83 + .../references/wait-avoid-hard-waits.md | 90 + .../references/wait-custom-timeout.md | 98 + .../references/wait-network-idle.md | 65 + .../references/wait-soft-assertions.md | 78 + .../references/wait-web-first-assertions.md | 91 + .claude/skills/react-hook-form/SKILL.md | 119 + .../references/adv-devtools-performance.md | 69 + .../references/adv-formprovider-memo.md | 78 + .../references/adv-opaque-types.md | 52 + .../references/adv-testing-wrapper.md | 63 + .../array-complete-default-objects.md | 66 + .../array-separate-crud-operations.md | 76 + .../array-unique-fieldarray-per-name.md | 58 + .../references/array-use-field-id-as-key.md | 54 + .../array-virtualization-formprovider.md | 64 + .../ctrl-avoid-double-registration.md | 46 + .../references/ctrl-controller-field-props.md | 56 + .../ctrl-local-state-combination.md | 69 + ...ctrl-single-usecontroller-per-component.md | 66 + .../ctrl-usecontroller-isolation.md | 64 + .../formcfg-async-default-values.md | 69 + .../references/formcfg-default-values.md | 57 + .../references/formcfg-revalidate-mode.md | 52 + .../references/formcfg-should-unregister.md | 64 + .../formcfg-useeffect-dependency.md | 54 + .../references/formcfg-validation-mode.md | 55 + .../formstate-avoid-isvalid-with-onsubmit.md | 57 + .../formstate-destructure-formstate.md | 48 + ...ormstate-getfieldstate-for-single-field.md | 54 + .../formstate-subscribe-to-specific-fields.md | 54 + .../formstate-useformstate-isolation.md | 65 + .../integ-mui-controller-pattern.md | 59 + .../references/integ-shadcn-form-import.md | 64 + .../references/integ-shadcn-select-wiring.md | 64 + .../integ-typed-submit-server-action.md | 52 + .../references/integ-value-transform.md | 59 + .../references/sub-avoid-watch-in-render.md | 48 + .../references/sub-deep-subscription.md | 62 + .../sub-useformcontext-sparingly.md | 58 + .../references/sub-usewatch-default-value.md | 50 + .../references/sub-usewatch-over-watch.md | 58 + .../references/sub-usewatch-with-getvalues.md | 54 + .../references/sub-watch-specific-fields.md | 54 + .../references/valid-delay-error.md | 52 + .../valid-dynamic-schema-factory.md | 57 + .../valid-error-message-strategy.md | 82 + .../references/valid-form-level-validate.md | 47 + .../references/valid-inline-vs-resolver.md | 63 + .../references/valid-native-validation.md | 60 + .../references/valid-resolver-caching.md | 58 + .../references/valid-trigger-should-touch.md | 44 + .claude/skills/react/SKILL.md | 87 + .claude/skills/react/references/_sections.md | 46 + .../references/conc-automatic-batching.md | 64 + .../react/references/conc-concurrent-safe.md | 71 + .../references/conc-suspense-fallback.md | 66 + .../references/conc-use-deferred-value.md | 65 + .../react/references/conc-use-transition.md | 75 + .../react/references/conc-view-transitions.md | 81 + .../references/data-cache-deduplication.md | 60 + .../react/references/data-error-boundaries.md | 76 + .../references/data-parallel-fetching.md | 74 + .../references/data-suspense-data-fetching.md | 76 + .../skills/react/references/data-use-hook.md | 77 + .../references/effect-avoid-unnecessary.md | 69 + .../skills/react/references/effect-cleanup.md | 75 + .../references/effect-object-dependencies.md | 56 + .../references/effect-use-browser-only.md | 62 + .../references/effect-use-effect-event.md | 53 + .../effect-use-sync-external-store.md | 80 + .../skills/react/references/form-actions.md | 83 + .../react/references/form-use-action-state.md | 80 + .../react/references/form-use-form-status.md | 68 + .../react/references/form-use-optimistic.md | 77 + .../react/references/form-validation.md | 89 + .../react/references/memo-avoid-premature.md | 68 + .../skills/react/references/memo-compiler.md | 84 + .../react/references/memo-react-memo.md | 72 + .../react/references/memo-use-callback.md | 70 + .../skills/react/references/memo-use-memo.md | 53 + .../react/references/rcomp-composition.md | 75 + .../references/rcomp-controlled-components.md | 63 + .../react/references/rcomp-fragment-refs.md | 71 + .../react/references/rcomp-key-reset.md | 74 + .../react/references/rcomp-render-props.md | 69 + .../references/rsc-avoid-client-only-libs.md | 66 + .../references/rsc-composition-pattern.md | 90 + .../react/references/rsc-context-provider.md | 50 + .../references/rsc-data-fetching-server.md | 68 + .../references/rsc-serializable-props.md | 70 + .../references/rsc-server-client-boundary.md | 63 + .../skills/react/references/rsc-streaming.md | 64 + .../references/rstate-context-optimization.md | 68 + .../react/references/rstate-derived-values.md | 70 + .../references/rstate-functional-updates.md | 58 + .../references/rstate-lazy-initialization.md | 59 + .../react/references/rstate-use-reducer.md | 77 + .claude/skills/shadcn/SKILL.md | 110 + .../references/ally-ensure-color-contrast.md | 62 + .../ally-maintain-focus-management.md | 84 + .../ally-preserve-aria-attributes.md | 77 + .../ally-preserve-keyboard-navigation.md | 72 + .../references/ally-provide-sr-only-labels.md | 75 + .../references/arch-current-cli-registry.md | 61 + .../arch-extend-variants-with-cva.md | 67 + ...-forward-refs-for-composable-components.md | 83 + .../arch-isolate-component-variants.md | 82 + ...arch-preserve-radix-primitive-structure.md | 57 + .../references/arch-unified-radix-package.md | 44 + .../arch-use-asChild-for-custom-triggers.md | 49 + .../arch-use-cn-for-class-merging.md | 62 + .../comp-combine-command-with-popover.md | 106 + .../comp-compose-with-compound-components.md | 104 + .../comp-create-reusable-form-fields.md | 157 + .../references/comp-nest-dialogs-correctly.md | 108 + .../comp-use-drawer-for-mobile-modals.md | 128 + .../comp-use-slot-pattern-for-flexibility.md | 118 + .../data-empty-states-with-guidance.md | 95 + .../references/data-paginate-server-side.md | 108 + .../data-use-skeleton-loading-states.md | 104 + ...a-use-tanstack-table-for-complex-tables.md | 121 + .../references/data-virtualize-large-lists.md | 82 + .../form-handle-async-validation.md | 104 + .../form-reset-form-state-correctly.md | 92 + .../form-show-validation-errors-correctly.md | 58 + .../form-use-react-hook-form-integration.md | 106 + .../form-use-zod-for-schema-validation.md | 86 + ...rf-avoid-unnecessary-rerenders-in-forms.md | 88 + .../references/perf-debounce-search-inputs.md | 85 + .../perf-lazy-load-heavy-components.md | 90 + .../perf-memoize-expensive-renders.md | 90 + .../references/perf-optimize-icon-imports.md | 60 + .../state-colocate-state-with-components.md | 103 + .../state-lift-state-to-appropriate-level.md | 103 + ...e-prefer-uncontrolled-for-simple-inputs.md | 91 + .../state-use-controlled-dialog-state.md | 127 + .../style-avoid-important-overrides.md | 58 + .../style-consistent-spacing-scale.md | 67 + .../references/style-dark-mode-support.md | 83 + .../style-responsive-design-patterns.md | 75 + .../style-use-css-variables-for-theming.md | 56 + .../style-use-tailwind-theme-extend.md | 63 + .claude/skills/tailwind/SKILL.md | 109 + .../tailwind/references/anim-3d-transforms.md | 56 + .../references/anim-gpu-accelerated.md | 47 + .../references/anim-gradient-interpolation.md | 46 + .../references/anim-starting-style.md | 63 + .../tailwind/references/build-cli-package.md | 43 + .../references/build-content-detection.md | 44 + .../tailwind/references/build-css-import.md | 36 + .../tailwind/references/build-node-version.md | 44 + .../references/build-postcss-simplify.md | 40 + .../tailwind/references/build-vite-plugin.md | 39 + .../references/bundle-avoid-cdn-production.md | 56 + .../references/bundle-avoid-preprocessors.md | 53 + .../references/bundle-css-minification.md | 57 + .../bundle-remove-unused-plugins.md | 55 + .../references/bundle-split-critical-css.md | 62 + .../references/comp-avoid-apply-overuse.md | 58 + .../references/comp-container-customize.md | 59 + .../references/comp-reference-directive.md | 59 + .../tailwind/references/comp-smart-sorting.md | 50 + .../references/comp-utility-file-scope.md | 61 + .../references/gen-avoid-theme-bloat.md | 47 + .../references/gen-css-first-config.md | 54 + .../references/gen-css-variable-syntax.md | 43 + .../references/gen-dynamic-utilities.md | 51 + .../tailwind/references/gen-oklch-colors.md | 40 + .../references/gen-utility-directive.md | 52 + .../references/resp-container-queries.md | 55 + .../references/resp-custom-breakpoints.md | 54 + .../references/resp-hover-capability.md | 60 + .../references/resp-logical-properties.md | 51 + .../tailwind/references/resp-mobile-first.md | 48 + .../tailwind/references/theme-color-scheme.md | 55 + .../references/theme-dark-mode-class.md | 59 + .../references/theme-prefix-variables.md | 56 + .../references/theme-runtime-variables.md | 55 + .../references/theme-semantic-tokens.md | 65 + .../references/util-explicit-colors.md | 43 + .../references/util-gradient-via-none.md | 37 + .../references/util-important-modifier.md | 43 + .../references/util-opacity-modifier.md | 50 + .../references/util-renamed-utilities.md | 45 + .../references/util-variant-stacking.md | 41 + .claude/skills/tanstack-query/SKILL.md | 117 + .../references/cache-enabled-option.md | 76 + .../references/cache-global-defaults.md | 73 + .../cache-invalidation-precision.md | 78 + .../cache-placeholder-vs-initial.md | 69 + .../references/cache-refetch-triggers.md | 68 + .../references/cache-staletime-gctime.md | 71 + .../references/error-conditional-retry.md | 93 + .../references/error-display-patterns.md | 100 + .../references/error-global-handler.md | 91 + .../references/error-retry-config.md | 80 + .../references/error-throw-on-error.md | 96 + .../references/infinite-flatten-pages.md | 108 + .../references/infinite-loading-states.md | 96 + .../references/infinite-max-pages.md | 86 + .../references/infinite-refetch-behavior.md | 79 + .../references/mutation-avoid-parallel.md | 92 + .../references/mutation-cancel-queries.md | 72 + .../mutation-invalidate-onsettled.md | 66 + .../references/mutation-optimistic-updates.md | 81 + .../references/mutation-setquerydata.md | 67 + .../references/prefetch-avoid-waterfalls.md | 98 + .../references/prefetch-flatten-api.md | 70 + .../references/prefetch-in-queryfn.md | 97 + .../references/prefetch-infinite-query.md | 60 + .../references/prefetch-on-hover.md | 94 + .../references/prefetch-server-components.md | 88 + .../references/render-notify-props.md | 66 + .../references/render-select-derived.md | 86 + .../references/render-select-memoize.md | 75 + .../references/render-structural-sharing.md | 88 + .../references/render-tracked-props.md | 80 + .../suspense-boundaries-placement.md | 97 + .../references/suspense-error-boundaries.md | 100 + .../references/suspense-parallel-queries.md | 93 + .../references/suspense-use-suspense-hooks.md | 66 + .../references/tquery-always-arrays.md | 49 + .../references/tquery-colocate-keys.md | 66 + .../references/tquery-hierarchical-keys.md | 61 + .../references/tquery-key-factories.md | 58 + .../references/tquery-options-pattern.md | 78 + .../references/tquery-serializable-objects.md | 60 + .claude/skills/tdd/SKILL.md | 114 + .../tdd/references/assert-custom-matchers.md | 86 + .../tdd/references/assert-error-messages.md | 64 + .../assert-no-assertions-antipattern.md | 70 + .../tdd/references/assert-snapshot-testing.md | 71 + .../references/assert-specific-assertions.md | 71 + .../references/cycle-maintain-test-list.md | 68 + .../references/cycle-minimal-code-to-pass.md | 62 + .../references/cycle-refactor-after-green.md | 58 + .../tdd/references/cycle-small-increments.md | 69 + .../cycle-verify-test-fails-first.md | 64 + .../tdd/references/cycle-write-test-first.md | 63 + .../references/data-avoid-mystery-guests.md | 62 + .../tdd/references/data-builder-pattern.md | 99 + .../tdd/references/data-minimal-setup.md | 69 + .../tdd/references/data-unique-identifiers.md | 79 + .../tdd/references/data-use-factories.md | 87 + .../tdd/references/design-aaa-pattern.md | 68 + .../references/design-avoid-logic-in-tests.md | 74 + .../design-descriptive-test-names.md | 64 + .../design-one-assertion-per-test.md | 66 + ...design-test-behavior-not-implementation.md | 69 + .../tdd/references/design-test-edge-cases.md | 83 + .../references/isolate-deterministic-tests.md | 80 + .../isolate-mock-external-dependencies.md | 69 + .../tdd/references/isolate-no-shared-state.md | 73 + .../isolate-prefer-stubs-over-mocks.md | 72 + .../isolate-use-dependency-injection.md | 91 + .../tdd/references/org-file-structure.md | 76 + .../tdd/references/org-group-by-behavior.md | 68 + .../tdd/references/org-parameterized-tests.md | 79 + .../tdd/references/org-setup-teardown.md | 84 + .../tdd/references/org-test-utilities.md | 98 + .../references/perf-avoid-network-calls.md | 78 + .../skills/tdd/references/perf-avoid-sleep.md | 82 + .../tdd/references/perf-fast-unit-tests.md | 48 + .../tdd/references/perf-fix-flaky-tests.md | 83 + .../tdd/references/perf-parallelize-tests.md | 87 + .../tdd/references/strat-coverage-targets.md | 70 + .../references/strat-e2e-critical-paths.md | 78 + .../strat-integration-boundaries.md | 79 + .../tdd/references/strat-mutation-testing.md | 71 + .../tdd/references/strat-test-pyramid.md | 58 + .claude/skills/typescript/SKILL.md | 103 + .../references/advanced-branded-types.md | 83 + .../references/advanced-satisfies-operator.md | 94 + .../advanced-template-literal-types.md | 105 + .../references/async-avoid-loop-await.md | 78 + .../async-avoid-unnecessary-async.md | 61 + .../references/async-defer-await.md | 74 + .../references/async-explicit-return-types.md | 79 + .../references/async-parallel-promises.md | 63 + .../references/mem-avoid-closure-leaks.md | 88 + .../references/mem-avoid-global-state.md | 97 + .../references/mem-cleanup-event-listeners.md | 111 + .../typescript/references/mem-clear-timers.md | 106 + .../mem-use-weakmap-for-metadata.md | 84 + .../references/module-avoid-barrel-imports.md | 70 + .../module-avoid-circular-dependencies.md | 92 + .../module-control-types-inclusion.md | 92 + .../references/module-dynamic-imports.md | 78 + .../references/module-use-type-imports.md | 80 + .../runtime-avoid-object-spread-in-loops.md | 79 + .../runtime-cache-property-access.md | 85 + .../runtime-prefer-array-methods.md | 73 + .../runtime-use-for-of-for-iteration.md | 89 + .../references/runtime-use-set-for-lookups.md | 64 + .../references/runtime-use-string-methods.md | 79 + .../references/safety-assertion-functions.md | 92 + .../references/safety-const-assertions.md | 77 + .../references/safety-exhaustive-checks.md | 83 + .../safety-prefer-unknown-over-any.md | 76 + .../references/safety-strict-null-checks.md | 72 + .../references/safety-use-type-guards.md | 86 + .../references/tscfg-enable-incremental.md | 68 + .../references/tscfg-exclude-properly.md | 85 + .../references/tscfg-isolate-modules.md | 68 + .../references/tscfg-project-references.md | 97 + .../references/tscfg-skip-lib-check.md | 63 + .../references/tscfg-strict-function-types.md | 67 + .../references/tscfg-typescript-7.md | 75 + .../references/type-avoid-deep-generics.md | 81 + .../references/type-avoid-large-unions.md | 57 + .../references/type-explicit-return-types.md | 65 + .../type-extract-conditional-types.md | 57 + .../type-interfaces-over-intersections.md | 41 + .../references/type-limit-recursion-depth.md | 65 + .../references/type-simplify-mapped-types.md | 71 + .claude/skills/ui-design/SKILL.md | 102 + .../ui-design/references/access-alt-text.md | 63 + .../references/access-aria-labels.md | 57 + .../references/access-focus-indicators.md | 53 + .../references/access-heading-hierarchy.md | 48 + .../references/access-keyboard-navigation.md | 52 + .../references/access-semantic-html.md | 53 + .../references/access-target-size.md | 56 + .../references/anim-duration-easing.md | 77 + .../references/anim-gpu-properties.md | 75 + .../references/anim-reduced-motion.md | 82 + .../ui-design/references/anim-will-change.md | 78 + .../references/color-contrast-ratio.md | 67 + .../ui-design/references/color-dark-mode.md | 74 + .../references/color-not-only-indicator.md | 79 + .../references/color-semantic-palette.md | 64 + .../ui-design/references/cwv-critical-css.md | 55 + .../ui-design/references/cwv-improve-inp.md | 70 + .../references/cwv-lazy-load-offscreen.md | 60 + .../ui-design/references/cwv-minimize-cls.md | 66 + .../ui-design/references/cwv-optimize-lcp.md | 59 + .../references/cwv-responsive-images.md | 63 + .../ui-design/references/form-autocomplete.md | 62 + .../references/form-error-messages.md | 61 + .../references/form-inline-validation.md | 67 + .../ui-design/references/form-input-types.md | 63 + .../ui-design/references/form-labels-above.md | 74 + .../ui-design/references/layout-f-pattern.md | 65 + .../references/layout-grid-system.md | 67 + .../references/layout-proximity-grouping.md | 57 + .../ui-design/references/layout-single-cta.md | 64 + .../references/layout-visual-hierarchy.md | 69 + .../ui-design/references/layout-whitespace.md | 70 + .../references/resp-container-queries.md | 64 + .../references/resp-fluid-typography.md | 65 + .../ui-design/references/resp-mobile-first.md | 83 + .../references/resp-touch-targets.md | 67 + .../references/resp-viewport-meta.md | 57 + .../ui-design/references/typo-font-display.md | 61 + .../ui-design/references/typo-line-height.md | 66 + .../references/typo-preload-fonts.md | 62 + .../references/typo-readable-line-length.md | 58 + .../references/typo-system-font-stack.md | 57 + .../vercel-composition-patterns/SKILL.md | 74 + .../rules/architecture-avoid-boolean-props.md | 102 + .../rules/architecture-compound-components.md | 112 + .../patterns-children-over-render-props.md | 87 + .../rules/patterns-explicit-variants.md | 100 + .../rules/react19-no-forwardref.md | 42 + .../rules/state-context-interface.md | 191 + .../rules/state-decouple-implementation.md | 113 + .../rules/state-lift-state.md | 125 + .../vercel-react-best-practices/SKILL.md | 134 + .../rules/advanced-effect-event-deps.md | 56 + .../rules/advanced-event-handler-refs.md | 55 + .../rules/advanced-init-once.md | 42 + .../rules/advanced-use-latest.md | 39 + .../rules/async-api-routes.md | 38 + .../async-cheap-condition-before-await.md | 37 + .../rules/async-defer-await.md | 82 + .../rules/async-dependencies.md | 51 + .../rules/async-parallel.md | 28 + .../rules/async-suspense-boundaries.md | 99 + .../rules/bundle-analyzable-paths.md | 63 + .../rules/bundle-barrel-imports.md | 60 + .../rules/bundle-conditional.md | 31 + .../rules/bundle-defer-third-party.md | 49 + .../rules/bundle-dynamic-imports.md | 35 + .../rules/bundle-preload.md | 50 + .../rules/client-event-listeners.md | 74 + .../rules/client-localstorage-schema.md | 71 + .../rules/client-passive-event-listeners.md | 48 + .../rules/client-swr-dedup.md | 56 + .../rules/js-batch-dom-css.md | 107 + .../rules/js-cache-function-results.md | 80 + .../rules/js-cache-property-access.md | 28 + .../rules/js-cache-storage.md | 70 + .../rules/js-combine-iterations.md | 32 + .../rules/js-early-exit.md | 50 + .../rules/js-flatmap-filter.md | 60 + .../rules/js-hoist-regexp.md | 45 + .../rules/js-index-maps.md | 37 + .../rules/js-length-check-first.md | 49 + .../rules/js-min-max-loop.md | 82 + .../rules/js-request-idle-callback.md | 105 + .../rules/js-set-map-lookups.md | 24 + .../rules/js-tosorted-immutable.md | 57 + .../rules/rendering-activity.md | 26 + .../rules/rendering-animate-svg-wrapper.md | 47 + .../rules/rendering-conditional-render.md | 40 + .../rules/rendering-content-visibility.md | 38 + .../rules/rendering-hoist-jsx.md | 46 + .../rules/rendering-hydration-no-flicker.md | 82 + .../rendering-hydration-suppress-warning.md | 30 + .../rules/rendering-resource-hints.md | 85 + .../rules/rendering-script-defer-async.md | 68 + .../rules/rendering-svg-precision.md | 28 + .../rules/rendering-usetransition-loading.md | 79 + .../rules/rerender-defer-reads.md | 39 + .../rules/rerender-dependencies.md | 45 + .../rules/rerender-derived-state-no-effect.md | 40 + .../rules/rerender-derived-state.md | 29 + .../rules/rerender-functional-setstate.md | 74 + .../rules/rerender-lazy-state-init.md | 58 + .../rules/rerender-memo-with-default-value.md | 38 + .../rules/rerender-memo.md | 44 + .../rules/rerender-move-effect-to-event.md | 45 + .../rules/rerender-no-inline-components.md | 82 + .../rerender-simple-expression-in-memo.md | 35 + .../rules/rerender-split-combined-hooks.md | 64 + .../rules/rerender-transitions.md | 40 + .../rules/rerender-use-deferred-value.md | 59 + .../rerender-use-ref-transient-values.md | 73 + .../rules/server-after-nonblocking.md | 73 + .../rules/server-auth-actions.md | 96 + .../rules/server-cache-lru.md | 41 + .../rules/server-cache-react.md | 76 + .../rules/server-dedup-props.md | 65 + .../rules/server-hoist-static-io.md | 149 + .../rules/server-no-shared-module-state.md | 50 + .../rules/server-parallel-fetching.md | 83 + .../rules/server-parallel-nested-fetching.md | 34 + .../rules/server-serialization.md | 38 + .claude/skills/vitest/SKILL.md | 122 + .../vitest/references/assert-edge-cases.md | 83 + .../references/assert-expect-assertions.md | 95 + .../assert-one-assertion-concept.md | 94 + .../references/assert-specific-matchers.md | 83 + .../references/assert-toequal-vs-tobe.md | 91 + .../vitest/references/async-act-wrapper.md | 79 + .../references/async-await-assertions.md | 45 + .../references/async-concurrent-expect.md | 60 + .../vitest/references/async-error-handling.md | 72 + .../vitest/references/async-fake-timers.md | 82 + .../references/async-return-promises.md | 60 + .../references/async-waitfor-polling.md | 84 + .../references/env-browser-api-mocking.md | 96 + .../vitest/references/env-globals-config.md | 85 + .../references/env-per-file-override.md | 115 + .../vitest/references/env-setup-files.md | 94 + .../references/mock-avoid-overmocking.md | 98 + .../references/mock-clear-between-tests.md | 86 + .../mock-implementation-not-value.md | 81 + .../vitest/references/mock-msw-network.md | 96 + .../vitest/references/mock-spyon-vs-mock.md | 85 + .../vitest/references/mock-type-safety.md | 97 + .../references/mock-vi-mock-hoisting.md | 95 + .../vitest/references/org-describe-nesting.md | 85 + .../vitest/references/org-file-colocation.md | 93 + .../vitest/references/org-test-naming.md | 86 + .../vitest/references/org-test-skip-only.md | 75 + .../vitest/references/perf-bail-fast-fail.md | 84 + .../references/perf-bench-test-context.md | 59 + .../references/perf-disable-isolation.md | 91 + .../vitest/references/perf-happy-dom.md | 103 + .../vitest/references/perf-pool-selection.md | 78 + .../vitest/references/perf-run-mode-ci.md | 93 + .../skills/vitest/references/perf-sharding.md | 101 + .../references/setup-avoid-shared-state.md | 98 + .../references/setup-beforeall-expensive.md | 81 + .../references/setup-beforeeach-cleanup.md | 83 + .../vitest/references/setup-reset-modules.md | 91 + .../vitest/references/setup-restore-mocks.md | 88 + .../vitest/references/setup-test-factories.md | 104 + .../references/setup-vitest5-migration.md | 64 + .../vitest/references/snap-avoid-large.md | 76 + .../vitest/references/snap-describe-intent.md | 78 + .../references/snap-inline-over-file.md | 73 + .../vitest/references/snap-review-updates.md | 79 + .../references/snap-stable-serialization.md | 97 + .claude/skills/web-design-guidelines/SKILL.md | 39 + .claude/skills/zod/SKILL.md | 128 + .../zod/references/compose-intersection.md | 147 + .../zod/references/compose-lazy-recursive.md | 154 + .claude/skills/zod/references/compose-pipe.md | 113 + .../zod/references/compose-preprocess.md | 142 + .../zod/references/compose-shared-schemas.md | 138 + .../error-avoid-throwing-in-refine.md | 127 + .../zod/references/error-custom-messages.md | 113 + .claude/skills/zod/references/error-i18n.md | 141 + .../zod/references/error-path-for-nested.md | 133 + .../zod/references/error-use-flatten.md | 85 + .../references/object-discriminated-unions.md | 138 + .../object-extend-for-composition.md | 145 + .../references/object-optional-vs-nullable.md | 117 + .../references/object-partial-for-updates.md | 142 + .../skills/zod/references/object-pick-omit.md | 146 + .../zod/references/object-strict-vs-strip.md | 70 + .../parse-async-for-async-refinements.md | 118 + .../parse-avoid-double-validation.md | 129 + .../zod/references/parse-handle-all-issues.md | 125 + .../zod/references/parse-never-trust-json.md | 113 + .../zod/references/parse-use-safeparse.md | 102 + .../zod/references/parse-validate-early.md | 120 + .../parse-validate-for-boolean-checks.md | 64 + .claude/skills/zod/references/perf-arrays.md | 153 + .../references/perf-avoid-dynamic-creation.md | 97 + .../zod/references/perf-cache-schemas.md | 138 + .../zod/references/perf-compile-schemas.md | 76 + .../zod/references/perf-lazy-loading.md | 135 + .../skills/zod/references/perf-zod-mini.md | 110 + .../skills/zod/references/refine-add-path.md | 141 + .claude/skills/zod/references/refine-catch.md | 143 + .../skills/zod/references/refine-defaults.md | 131 + .../zod/references/refine-transform-coerce.md | 105 + .../skills/zod/references/refine-use-codec.md | 41 + .../zod/references/refine-vs-superrefine.md | 152 + .../references/schema-avoid-optional-abuse.md | 93 + .../schema-coercion-for-form-data.md | 88 + .../references/schema-string-validations.md | 114 + .../skills/zod/references/schema-use-enums.md | 115 + .../schema-use-primitives-correctly.md | 61 + .../references/schema-use-unknown-not-any.md | 88 + .../zod/references/type-branded-types.md | 102 + .../zod/references/type-enable-strict-mode.md | 130 + .../type-export-schemas-and-types.md | 116 + .../zod/references/type-input-vs-output.md | 116 + .../skills/zod/references/type-use-z-infer.md | 110 + .config/dotnet-tools.json | 13 + .dockerignore | 20 + .env.example | 26 + .github/SECURITY.md | 3 + .github/workflows/dotnet.yml | 46 +- .gitignore | 19 +- AGENTS.md | 28 + Backend/Directory.Build.props | 12 + Backend/Dockerfile | 21 + Backend/docker/mysql-init.sh | 9 + .../Endpoints/AdministrationEndpoints.cs | 11 +- .../Modules.Administration.Api/Extensions.cs | 4 +- .../Modules.Administration.Api.csproj | 13 + .../Operations/AdministrationOperations.cs | 9 +- .../Extensions.cs | 4 +- .../Modules.Administration.Application.csproj | 15 + .../Services/AdminModuleApi.cs | 4 +- .../Services/AdminService.cs | 113 + .../Interfaces/IAdminModuleApi.cs | 4 +- .../Modules.Administration.Shared.csproj | 9 + .../Endpoints/AuthEndpoints.cs | 35 +- .../AuthModule/Modules.Auth.Api/Extensions.cs | 4 +- .../Modules.Auth.Api/Modules.Auth.Api.csproj | 15 + .../Operations/AuthOperations.cs | 36 +- .../Modules.Auth.Application/Extensions.cs | 6 +- .../Interfaces/IAuthService.cs | 8 +- .../Modules.Auth.Application.csproj | 14 + .../Services/AuthService.cs | 168 +- .../Modules.Auth.Core/Entities/AppUser.cs | 4 +- .../Entities/AuthSettings.cs | 2 +- .../Modules.Auth.Core/Entities/TokenModel.cs | 2 +- .../Modules.Auth.Core.csproj | 10 + .../DbContexts/AppIdentityDbContext.cs | 4 +- .../DbContexts/AppIdentityDbContextFactory.cs | 4 +- .../20250825091711_Initial.Designer.cs | 0 .../Migrations/20250825091711_Initial.cs | 0 ...50902202604_AddIsBlockedColumn.Designer.cs | 0 .../20250902202604_AddIsBlockedColumn.cs | 0 ...021180313_UpgradeNet10Identity.Designer.cs | 307 ++ .../20261021180313_UpgradeNet10Identity.cs | 22 + .../AppIdentityDbContextModelSnapshot.cs | 2 +- .../Modules.Auth.Infrastructure/Extensions.cs | 6 +- .../Modules.Auth.Infrastructure.csproj | 31 + .../ActionsRequests/ChangeEmailRequest.cs | 15 + .../ActionsRequests/ChangePasswordRequest.cs | 15 + .../ActionsRequests/EditUserRequest.cs | 8 +- .../ActionsRequests/LoginRequest.cs | 6 +- .../ActionsRequests/RegisterRequest.cs | 2 +- .../Modules.Auth.Shared/Dtos/UserDto.cs | 2 +- .../Entities/CurrentUser.cs | 2 +- .../Modules.Auth.Shared.csproj | 10 + .../Static/Entities/AppRoles.cs | 2 +- .../Backups/BackupQueueEndpoints.cs | 29 + .../Modules.Backup.Api/Backups/BackupsEo.cs | 38 +- .../Modules.Backup.Api/Extensions.cs | 5 +- .../Modules.Backup.Api.csproj | 11 + .../Schedules/SchedulesEo.cs | 7 +- .../Security/ResourceAccessFilter.cs | 50 + .../Modules.Backup.Api/Servers/ServersEo.cs | 24 +- .../Modules.Backup.Api/Statistics/StatsEO.cs | 7 +- .../Modules.Backup.Application/Extensions.cs | 11 +- .../Interfaces/IBackupExecutor.cs | 10 + .../Interfaces/IDbBackupService.cs | 4 +- .../Interfaces/IEmailProviderService.cs | 4 +- .../Modules.Backup.Application.csproj | 22 + .../Services/BackupExecutor.cs | 66 + .../Services/BackupQueueCoordinator.cs | 10 + .../Services/BackupQueueProcessor.cs | 179 + .../Services/BackupQueueService.cs | 210 + .../Services/BackupTarget.cs | 22 + .../Services/DbBackupService.cs | 156 + .../Services/EmailProviderService.cs | 4 +- .../Services/NotifyService.cs | 34 + .../Services/SchedulesService.cs | 14 +- .../Services/ServersService.cs | 108 +- .../Services/StatisticsService.cs | 28 +- .../Static/ServerConnectionTester.cs | 25 +- .../Workers/BackupWorker.cs | 50 + .../Entities/Databases/DatabaseBase.cs | 23 +- .../Entities/Databases/MySqlDatabase.cs | 17 + .../Entities/Databases/PostgreSqlDatabase.cs | 15 + .../Entities/Databases/SqlServerDatabase.cs | 23 + .../DbContext/AutomaticBackupTestConfig.cs | 4 +- .../Entities/DbContext/BackupRequest.cs | 30 + .../Entities/DbContext/BackupSchedule.cs | 4 +- .../Entities/DbContext/BackupTest.cs | 4 +- .../Entities/DbContext/DbServerConnection.cs | 4 +- .../Entities/DbContext/DbServerTunnel.cs | 4 +- .../Entities/DbContext/PerformedBackup.cs | 4 +- .../DbContext/ServerBackupsConfiguration.cs | 14 +- .../Entities/DbContext/ServersUsers.cs | 4 +- .../DbContext/UserNotificationsSettings.cs | 4 +- .../Models/AppEmailConfigurationModel.cs | 4 +- .../Models/ApplicationConfigurationModel.cs | 2 +- .../Entities/Models/BackupDayTime.cs | 4 +- .../Entities/Models/EWeekDay.cs | 4 +- .../Models/EmailProviderConfigurationModel.cs | 4 +- .../Entities/Models/MailModel.cs | 3 + .../EmptyListOfConfigurationsException.cs | 2 +- .../Interfaces/IDatabase.cs | 4 +- .../Modules.Backup.Core.csproj | 25 + .../StaticClasses/CompressBackupFile.cs | 4 +- .../StaticClasses/DeleteOldBackup.cs | 2 +- .../StaticClasses/DumpFailureException.cs | 43 + .../StaticClasses/DumpProcess.cs | 80 + .../StaticClasses/MySqlDumpClient.cs | 67 + .../StaticClasses/PrepareEmailMessageBody.cs | 4 +- .../StaticClasses/SafeBackupPath.cs | 29 + .../StaticClasses/SshHostKeys.cs | 22 + .../StaticClasses/SshTunnelHelper.cs | 14 +- .../Configuration/LoggerPrepareSetup.cs | 2 +- .../PrepareApplicationSettings.cs | 2 +- .../DbContexts/BackupsDbContext.cs | 17 +- .../20250903215501_Initial.Designer.cs | 0 .../Migrations/20250903215501_Initial.cs | 0 ...0904111233_AddPKToServersUsers.Designer.cs | 0 .../20250904111233_AddPKToServersUsers.cs | 0 ...09144138_UpdateSchedulesEntity.Designer.cs | 0 .../20250909144138_UpdateSchedulesEntity.cs | 0 ...AddPEMPassphraseToTunnelEntity.Designer.cs | 0 ...10104700_AddPEMPassphraseToTunnelEntity.cs | 0 ...911091310_UpdateBackupsColumns.Designer.cs | 0 .../20250911091310_UpdateBackupsColumns.cs | 0 ...50911125405_UpdateBackupEntity.Designer.cs | 0 .../20250911125405_UpdateBackupEntity.cs | 0 ...2706_ModifyNullsInBackupEntity.Designer.cs | 0 ...0250911172706_ModifyNullsInBackupEntity.cs | 0 .../20251025203420_AddSslToEntity.Designer.cs | 0 .../20251025203420_AddSslToEntity.cs | 0 ...6120032_AddSoftDeleteToBackups.Designer.cs | 0 .../20251026120032_AddSoftDeleteToBackups.cs | 0 ...03734_AddPersistentBackupQueue.Designer.cs | 376 ++ ...20261021203734_AddPersistentBackupQueue.cs | 76 + .../BackupsDbContextModelSnapshot.cs | 81 +- .../Extensions.cs | 4 +- ...225_UpdateAutoTestConfigEntity.Designer.cs | 0 ...251010094225_UpdateAutoTestConfigEntity.cs | 0 ...1013075224_ChangeIntsToUShorts.Designer.cs | 0 .../20251013075224_ChangeIntsToUShorts.cs | 0 ...3810_ChangeEntityAddTestStatus.Designer.cs | 0 ...0251105083810_ChangeEntityAddTestStatus.cs | 0 .../Modules.Backup.Infrastructure.csproj | 30 + .../Dtos/AdminDashboardDto.cs | 4 +- .../Dtos/AutoTestBackupConfigDto.cs | 2 +- .../Dtos/BackupRequestDto.cs | 10 + .../Dtos/BackupScheduleConfiguration.cs | 4 +- .../Dtos/BackupTestDto.cs | 4 +- .../Dtos/BackupsScheduleDto.cs | 4 +- .../Dtos/PerformedBackupDto.cs | 4 +- .../Dtos/ServerConnectionDto.cs | 7 +- .../Dtos/ServerNameIdDto.cs | 3 + .../Dtos/ServerTunnelDto.cs | 4 +- .../Dtos/ServersUsersListDto.cs | 4 +- .../Dtos/UserDashboardDto.cs | 4 +- .../Enums/DatabaseType.cs | 4 +- .../Enums/ETestStatus.cs | 2 +- .../Helpers/BackupScheduleHelper.cs | 11 +- .../Modules.Backup.Shared/Hubs/BackupHub.cs | 10 + .../Modules.Backup.Shared.csproj | 10 + .../Requests/ModifyServerAccessRequest.cs | 4 +- .../Modules.Crypto.Api/Extension.cs | 4 +- .../Modules.Crypto.Api.csproj | 12 + .../Modules.Crypto.Application/Extensions.cs | 4 +- .../Modules.Crypto.Application.csproj | 12 + .../Services/CryptoService.cs | 38 +- .../Interfaces/ICryptoService.cs | 4 +- .../Modules.Crypto.Shared.csproj | 7 + .../AdminTokenAuthorizationFilter.cs | 13 + .../Attributes/RequestValidationFilter.cs | 19 + .../Common/ApiBaseController.cs | 4 +- .../Shared/Modules.Shared/Common/DbCommon.cs | 29 + .../Modules.Shared/Modules.Shared.csproj | 17 + .../Settings/ApplicationSettings.cs | 49 + .../ApplicationSettingsEndpoints.cs | 35 + .../Configuration/DevelopmentSettings.cs | 91 + .../Configuration/FileApplicationSettings.cs | 86 + Backend/src/Server.Api/Program.cs | 167 + .../Server.Api/Properties/launchSettings.json | 1 + .../Security/ApiExceptionHandler.cs | 15 + .../src/Server.Api/Security/BootstrapAdmin.cs | 23 + Backend/src/Server.Api/Server.Api.csproj | 21 + .../Server.Api/appsettings.Development.json | 25 + Backend/src/Server.Api/appsettings.json | 44 + .../DumpToolFixture/DumpToolFixture.csproj | 8 + Backend/tests/DumpToolFixture/Program.cs | 26 + .../MySqlDumpSmoke/MySqlDumpSmoke.csproj | 11 + Backend/tests/MySqlDumpSmoke/Program.cs | 49 + .../ApplicationSettingsTests.cs | 181 + .../OctoBackup.Tests/BackupQueueTests.cs | 320 ++ .../DevelopmentSettingsTests.cs | 77 + .../OctoBackup.Tests/DumpProcessTests.cs | 100 + .../OctoBackup.Tests/OctoBackup.Tests.csproj | 17 + .../tests/OctoBackup.Tests/SecurityTests.cs | 119 + DbBackupService/.dockerignore | 25 - DbBackupService/OctoBackup.sln | 195 - DbBackupService/Src/.dockerignore | 30 - .../Bootstraper/Client/Client.UI/App.razor | 45 - .../Client/Client.UI/Client.UI.csproj | 26 - .../HttpTokenAuthHeaderHandler.cs | 18 - .../Data/Interfaces/IAuthHttpClientService.cs | 61 - .../Services/AdministrationHttpService.cs | 52 - .../AuthHttpClientHttpClientService.cs | 194 - .../Data/Services/AuthStateProvider.cs | 161 - .../Data/Services/BackupsHttpClientService.cs | 92 - .../Client.UI/Data/Services/ProfileService.cs | 14 - .../Data/Services/TokenHttpClientService.cs | 87 - .../Client/Client.UI/Layout/AuthLayout.razor | 27 - .../Client.UI/Layout/AuthorizedNavMenu.razor | 55 - .../Client/Client.UI/Layout/DefaultLayout.cs | 40 - .../Client/Client.UI/Layout/MainLayout.razor | 150 - .../Layout/NotAuthorizedNavMenu.razor | 17 - .../AdministrationDashboard.razor | 77 - .../AdministrationServersUsers.razor | 121 - .../AdministrationUsersManagement.razor | 164 - .../AddUserToServerDialog.razor | 64 - .../ManageUsersInServerDialog.razor | 98 - .../UsersManagement/CreateNewUserDialog.razor | 101 - .../UsersManagement/EditUserDialog.razor | 128 - .../Authorization/Account/ProfileIndex.razor | 113 - .../Authorization/Common/AuthorizeUser.razor | 33 - .../Common/ConfirmPassword.razor | 107 - .../Pages/Authorization/Common/Login.razor | 121 - .../Pages/Authorization/Common/Register.razor | 119 - .../Schedule/BackupScheduleDialog.razor | 195 - .../Dialogs/Servers/CreateServerDialog.razor | 257 -- ...ditServerAutoTestConfigurationDialog.razor | 90 - .../Dialogs/Servers/EditServerDialog.razor | 258 -- .../Dialogs/Servers/TestServerDialog.razor | 76 - .../Pages/BackupsModule/MyBackups.razor | 192 - .../Pages/BackupsModule/MySchedules.razor | 208 - .../Pages/BackupsModule/MyServers.razor | 267 -- .../AuthorizingUserInfoComponent.razor | 25 - .../Client/Client.UI/Pages/Dashboard.razor | 69 - .../Client/Client.UI/Pages/Index.razor | 139 - .../Bootstraper/Client/Client.UI/Program.cs | 40 - .../Client.UI/Properties/launchSettings.json | 15 - .../Bootstraper/Client/Client.UI/Routes.razor | 16 - .../Client/Client.UI/_Imports.razor | 13 - .../Client/Client.UI/wwwroot/css/app.css | 92 - .../wwwroot/media/OctoBackupLogo.png | Bin 117472 -> 0 bytes .../Server.Api/Common/SeqConfiguration.cs | 3 - .../Bootstraper/Server/Server.Api/Dockerfile | 51 - .../Bootstraper/Server/Server.Api/Program.cs | 209 - .../Server.Api/Properties/launchSettings.json | 28 - .../Server/Server.Api/Server.Api.csproj | 35 - .../Server.Api/appsettings.Development.json | 8 - .../Server/Server.Api/appsettings.json | 31 - .../Modules.Administration.Api.csproj | 19 - .../Modules.Administration.Application.csproj | 22 - .../Services/AdminService.cs | 102 - .../Modules.Administration.Shared.csproj | 13 - .../Modules.Auth.Api/Modules.Auth.Api.csproj | 22 - .../Modules.Auth.Application.csproj | 22 - .../Services/TokenValidationService.cs | 54 - .../Modules.Auth.Core.csproj | 13 - .../Modules.Auth.Infrastructure.csproj | 33 - .../Repositories/IUserTokenService.cs | 8 - .../Repositories/UserTokenService.cs | 22 - .../ActionsRequests/ChangeEmailRequest.cs | 13 - .../ActionsRequests/ChangePasswordRequest.cs | 15 - .../ActionsRequests/TokenValidationRequest.cs | 3 - .../Entities/TokenModelDto.cs | 8 - .../Interfaces/ITokenValidationService.cs | 9 - .../Modules.Auth.Shared.csproj | 17 - .../Static/Entities/AuthHeaderName.cs | 6 - .../Setters/HttpClientAuthHeaderSetter.cs | 20 - .../Modules.Backup.Api.csproj | 15 - .../Modules.Backup.Application.csproj | 26 - .../Services/DbBackupService.cs | 335 -- .../Services/NotifyService.cs | 64 - .../Workers/BackupWorker.cs | 38 - .../Entities/Databases/MySqlDatabase.cs | 97 - .../Entities/Databases/PostgreSqlDatabase.cs | 113 - .../Entities/Databases/SqlServerDatabase.cs | 82 - .../Entities/Models/MailModel.cs | 3 - .../Modules.Backup.Core.csproj | 24 - .../StaticClasses/ToolChecker.cs | 34 - .../Modules.Backup.Infrastructure.csproj | 32 - .../Dtos/ServerNameIdDto.cs | 3 - .../Modules.Backup.Shared/Hubs/BackupHub.cs | 54 - .../Modules.Backup.Shared.csproj | 14 - .../BackupsTestsEO.cs | 120 - .../Modules.BackupsTests.Api/Extensions.cs | 19 - .../Modules.BackupsTests.Api.csproj | 26 - .../Modules.Crypto.Api.csproj | 17 - .../Modules.Crypto.Application.csproj | 18 - .../Modules.Crypto.Shared.csproj | 9 - .../AdminTokenAuthorizationFilter.cs | 39 - .../AllowWithoutTokenValidationAttribute.cs | 9 - .../BasicTokenAuthorizationFilter.cs | 47 - .../Shared/Modules.Shared/Common/DbCommon.cs | 21 - .../Modules.Shared/Modules.Shared.csproj | 23 - DbBackupService/buildAndDeployDocker.bat | 2 - DbBackupService/certs/OctoBackupCert.pfx | Bin 2652 -> 0 bytes DbBackupService/docker-compose.yml | 36 - DbBackupService/docker-composedev.yml | 36 - Frontend/Dockerfile | 18 + Frontend/docker/10-local-tls.sh | 13 + Frontend/docker/default.conf | 55 + Frontend/e2e/workspace.spec.ts | 203 + Frontend/index.html | 14 + Frontend/package-lock.json | 3881 +++++++++++++++++ Frontend/package.json | 36 + Frontend/playwright.config.ts | 25 + Frontend/scripts/run-tool.mjs | 86 + Frontend/scripts/start-test-api.mjs | 43 + Frontend/src/app/App.tsx | 334 ++ Frontend/src/features/account/AccountPage.tsx | 117 + .../admin/ApplicationSettingsPage.tsx | 347 ++ Frontend/src/features/admin/UsersPage.tsx | 202 + Frontend/src/features/auth/AuthPage.tsx | 144 + Frontend/src/features/backups/BackupsPage.tsx | 163 + Frontend/src/features/dashboard/Dashboard.tsx | 260 ++ .../src/features/queue/QueueHero.test.tsx | 128 + Frontend/src/features/queue/QueueHero.tsx | 125 + Frontend/src/features/queue/QueuePage.tsx | 206 + Frontend/src/features/queue/useBackupQueue.ts | 73 + .../features/schedules/SchedulesPage.test.tsx | 51 + .../src/features/schedules/SchedulesPage.tsx | 285 ++ Frontend/src/features/servers/ServerForm.tsx | 250 ++ Frontend/src/features/servers/ServersPage.tsx | 363 ++ Frontend/src/main.tsx | 25 + Frontend/src/shared/api.test.ts | 41 + Frontend/src/shared/api.ts | 63 + Frontend/src/shared/types.ts | 75 + Frontend/src/shared/ui.tsx | 134 + Frontend/src/styles.css | 1900 ++++++++ Frontend/src/test/setup.ts | 1 + Frontend/src/vite-env.d.ts | 1 + Frontend/tsconfig.json | 19 + Frontend/vite.config.ts | 21 + OctoBackup.sln | 363 ++ README.md | 153 +- README_PL.md | 83 - agent/skills/feature-arch/SKILL.md | 109 + .../bound-event-based-communication.md | 84 + .../references/bound-feature-isolation.md | 88 + .../bound-feature-scoped-routing.md | 76 + .../references/bound-feature-size.md | 74 + .../references/bound-interface-contracts.md | 83 + .../references/bound-minimize-shared-state.md | 73 + .../references/fcomp-colocate-styles.md | 88 + .../fcomp-composition-over-props.md | 100 + .../fcomp-container-presentational.md | 99 + .../references/fcomp-error-boundaries.md | 99 + .../fcomp-props-as-data-boundary.md | 88 + .../references/fcomp-single-responsibility.md | 99 + .../references/fquery-avoid-n-plus-one.md | 80 + .../fquery-colocate-with-feature.md | 70 + .../references/fquery-feature-scoped-keys.md | 72 + .../references/fquery-parallel-fetching.md | 71 + .../fquery-server-component-fetching.md | 88 + .../fquery-single-responsibility.md | 66 + .../references/fstate-context-sparingly.md | 73 + .../fstate-feature-scoped-stores.md | 79 + .../references/fstate-lift-minimally.md | 85 + .../references/fstate-reset-on-unmount.md | 89 + .../fstate-server-state-separation.md | 93 + .../references/import-avoid-barrel-files.md | 63 + .../references/import-no-cross-feature.md | 84 + .../references/import-path-aliases.md | 64 + .../references/import-public-api.md | 67 + .../references/import-type-only.md | 81 + .../references/import-unidirectional-flow.md | 82 + .../references/name-descriptive-exports.md | 65 + .../references/name-feature-naming.md | 60 + .../references/name-file-conventions.md | 79 + .../references/struct-app-layer.md | 73 + .../references/struct-feature-folders.md | 70 + .../struct-feature-self-contained.md | 62 + .../references/struct-flat-hierarchy.md | 58 + .../references/struct-optional-segments.md | 72 + .../references/struct-shared-layer.md | 68 + .../references/test-colocate-with-feature.md | 78 + .../references/test-feature-isolation.md | 88 + .../test-integration-at-app-layer.md | 87 + .../references/test-shared-utilities.md | 94 + agent/skills/msw/SKILL.md | 120 + .../references/advanced-bypass-requests.md | 81 + .../msw/references/advanced-cookies-auth.md | 119 + .../references/advanced-dynamic-scenarios.md | 114 + .../msw/references/advanced-file-uploads.md | 109 + .../advanced-playwright-integration.md | 78 + .../msw/references/advanced-vitest-browser.md | 100 + .../references/advanced-websocket-mocking.md | 87 + .../msw/references/debug-common-issues.md | 79 + .../msw/references/debug-lifecycle-events.md | 88 + .../msw/references/debug-request-logging.md | 113 + .../references/debug-verify-interception.md | 95 + .../msw/references/graphql-batched-queries.md | 93 + .../msw/references/graphql-error-responses.md | 119 + .../references/graphql-operation-handlers.md | 101 + .../msw/references/graphql-schema-first.md | 76 + .../references/graphql-variables-access.md | 123 + .../msw/references/handler-absolute-urls.md | 70 + .../msw/references/handler-domain-grouping.md | 81 + .../references/handler-happy-path-first.md | 60 + .../handler-request-body-parsing.md | 76 + .../references/handler-resolver-argument.md | 86 + .../handler-reusability-environments.md | 80 + .../references/handler-shared-resolvers.md | 99 + .../references/handler-v2-response-syntax.md | 94 + .../msw/references/match-custom-predicate.md | 99 + .../msw/references/match-handler-order.md | 93 + .../msw/references/match-http-methods.md | 98 + .../msw/references/match-query-params.md | 89 + .../msw/references/match-url-patterns.md | 87 + .../msw/references/response-custom-headers.md | 125 + .../references/response-delay-realistic.md | 92 + .../references/response-error-simulation.md | 110 + .../response-http-response-helpers.md | 83 + .../references/response-one-time-handlers.md | 103 + .../msw/references/response-streaming.md | 114 + .../msw/references/setup-lifecycle-hooks.md | 57 + .../msw/references/setup-node-version.md | 72 + .../setup-server-node-entrypoint.md | 45 + .../msw/references/setup-typescript-config.md | 74 + .../references/setup-unhandled-requests.md | 70 + .../references/setup-worker-script-commit.md | 65 + .../msw/references/test-async-utilities.md | 81 + .../test-avoid-request-assertions.md | 87 + .../references/test-clear-request-cache.md | 85 + .../references/test-concurrent-boundary.md | 88 + .../msw/references/test-fake-timers-config.md | 91 + .../msw/references/test-jsdom-environment.md | 67 + .../msw/references/test-reset-handlers.md | 63 + agent/skills/nextjs/SKILL.md | 114 + .../references/action-error-handling.md | 75 + .../references/action-optimistic-updates.md | 74 + .../references/action-pending-states.md | 68 + .../nextjs/references/action-revalidation.md | 78 + .../references/action-server-action-forms.md | 75 + .../nextjs/references/build-barrel-files.md | 50 + .../references/build-dynamic-imports.md | 62 + .../references/build-external-packages.md | 48 + .../build-optimize-package-imports.md | 42 + .../references/build-turbopack-config.md | 71 + .../nextjs/references/cache-fetch-options.md | 53 + .../nextjs/references/cache-react-cache.md | 58 + .../references/cache-revalidate-path.md | 62 + .../nextjs/references/cache-revalidate-tag.md | 65 + .../nextjs/references/cache-segment-config.md | 63 + .../references/cache-use-cache-directive.md | 57 + .../references/client-children-pattern.md | 75 + .../references/client-hydration-mismatch.md | 101 + .../references/client-third-party-scripts.md | 67 + .../references/client-use-client-boundary.md | 72 + .../references/meta-generate-metadata.md | 70 + .../references/meta-opengraph-images.md | 72 + agent/skills/nextjs/references/meta-robots.md | 68 + .../skills/nextjs/references/meta-sitemap.md | 76 + .../references/route-instant-navigations.md | 97 + .../references/route-intercepting-routes.md | 76 + .../nextjs/references/route-not-found.md | 59 + .../references/route-parallel-routes.md | 79 + .../references/route-partial-prefetching.md | 87 + .../nextjs/references/route-prefetching.md | 71 + .../nextjs/references/route-proxy-ts.md | 62 + .../server-avoid-client-fetching.md | 71 + .../references/server-component-streaming.md | 70 + .../references/server-data-colocation.md | 63 + .../references/server-error-handling.md | 79 + .../references/server-parallel-fetching.md | 69 + .../references/server-preload-pattern.md | 68 + .../nextjs/references/stream-error-tsx.md | 67 + .../nextjs/references/stream-loading-tsx.md | 63 + .../references/stream-nested-suspense.md | 82 + .../references/stream-skeleton-matching.md | 72 + .../references/stream-suspense-boundaries.md | 62 + agent/skills/nuqs/SKILL.md | 109 + .../references/advanced-custom-parsers.md | 70 + .../nuqs/references/advanced-eq-function.md | 94 + .../references/advanced-framework-adapters.md | 82 + .../nuqs/references/advanced-url-keys.md | 62 + .../nuqs/references/debug-common-errors.md | 53 + .../nuqs/references/debug-enable-logging.md | 51 + agent/skills/nuqs/references/debug-testing.md | 55 + .../nuqs/references/history-back-sync.md | 51 + .../references/history-push-navigation.md | 76 + .../references/history-replace-ephemeral.md | 87 + .../references/history-scroll-behavior.md | 60 + .../nuqs/references/parser-array-format.md | 59 + .../nuqs/references/parser-date-format.md | 67 + .../nuqs/references/parser-enum-validation.md | 81 + .../nuqs/references/parser-hex-colors.md | 68 + .../nuqs/references/parser-index-offset.md | 72 + .../nuqs/references/parser-json-validation.md | 97 + .../references/parser-use-typed-parsers.md | 58 + .../nuqs/references/parser-with-default.md | 65 + .../nuqs/references/perf-avoid-rerender.md | 88 + .../nuqs/references/perf-clear-on-default.md | 55 + .../nuqs/references/perf-debounce-search.md | 82 + .../nuqs/references/perf-serialize-utility.md | 81 + .../nuqs/references/perf-throttle-updates.md | 66 + .../nuqs/references/server-next15-async.md | 80 + .../references/server-parse-before-get.md | 82 + .../references/server-search-params-cache.md | 78 + .../nuqs/references/server-shallow-false.md | 74 + .../nuqs/references/server-share-parsers.md | 74 + .../nuqs/references/server-use-transition.md | 96 + .../nuqs/references/setup-import-server.md | 72 + .../nuqs/references/setup-nextjs-version.md | 64 + .../nuqs/references/setup-nuqs-adapter.md | 77 + .../nuqs/references/setup-shared-parsers.md | 73 + .../nuqs/references/setup-use-client.md | 69 + .../nuqs/references/state-avoid-derived.md | 84 + .../nuqs/references/state-clear-with-null.md | 81 + .../references/state-controlled-inputs.md | 83 + .../references/state-functional-updates.md | 68 + .../references/state-options-inheritance.md | 78 + .../nuqs/references/state-setter-return.md | 78 + .../nuqs/references/state-use-query-states.md | 75 + agent/skills/playwright/SKILL.md | 113 + .../references/arch-cleanup-state.md | 83 + .../playwright/references/arch-fixtures.md | 89 + .../references/arch-page-object-model.md | 80 + .../references/arch-parallel-execution.md | 75 + .../references/arch-test-isolation.md | 61 + .../references/arch-test-production.md | 74 + .../references/assert-aria-snapshots.md | 58 + .../playwright/references/auth-api-login.md | 99 + .../references/auth-multiple-roles.md | 111 + .../references/auth-parallel-workers.md | 101 + .../references/auth-session-storage.md | 106 + .../references/auth-storage-state.md | 97 + .../references/debug-ci-reporters.md | 81 + .../playwright/references/debug-inspector.md | 86 + .../references/debug-screenshots-videos.md | 85 + .../references/debug-trace-viewer.md | 79 + .../playwright/references/loc-avoid-xpath.md | 64 + .../references/loc-chained-locators.md | 87 + .../playwright/references/loc-data-testid.md | 80 + .../references/loc-frame-locator.md | 45 + .../references/loc-label-selectors.md | 78 + .../references/loc-placeholder-selector.md | 87 + .../references/loc-role-selectors.md | 74 + .../references/loc-text-selectors.md | 77 + .../references/mock-abort-requests.md | 107 + .../references/mock-api-responses.md | 91 + .../playwright/references/mock-har-files.md | 100 + .../references/mock-intercept-modify.md | 101 + .../references/mock-network-conditions.md | 98 + .../references/next-app-router-navigation.md | 87 + .../references/next-baseurl-config.md | 108 + .../references/next-server-actions.md | 90 + .../references/next-server-components.md | 92 + .../references/next-wait-hydration.md | 103 + .../references/perf-browser-selection.md | 99 + .../playwright/references/perf-headless-ci.md | 100 + .../playwright/references/perf-retries.md | 100 + .../references/perf-reuse-server.md | 87 + .../playwright/references/perf-sharding.md | 105 + .../references/wait-action-retries.md | 83 + .../references/wait-avoid-hard-waits.md | 90 + .../references/wait-custom-timeout.md | 98 + .../references/wait-network-idle.md | 65 + .../references/wait-soft-assertions.md | 78 + .../references/wait-web-first-assertions.md | 91 + agent/skills/react-hook-form/SKILL.md | 118 + .../references/adv-devtools-performance.md | 69 + .../references/adv-formprovider-memo.md | 78 + .../references/adv-opaque-types.md | 52 + .../references/adv-testing-wrapper.md | 63 + .../array-complete-default-objects.md | 66 + .../array-separate-crud-operations.md | 76 + .../array-unique-fieldarray-per-name.md | 58 + .../references/array-use-field-id-as-key.md | 54 + .../array-virtualization-formprovider.md | 64 + .../ctrl-avoid-double-registration.md | 46 + .../references/ctrl-controller-field-props.md | 56 + .../ctrl-local-state-combination.md | 69 + ...ctrl-single-usecontroller-per-component.md | 66 + .../ctrl-usecontroller-isolation.md | 64 + .../formcfg-async-default-values.md | 69 + .../references/formcfg-default-values.md | 57 + .../references/formcfg-revalidate-mode.md | 52 + .../references/formcfg-should-unregister.md | 64 + .../formcfg-useeffect-dependency.md | 54 + .../references/formcfg-validation-mode.md | 55 + .../formstate-avoid-isvalid-with-onsubmit.md | 57 + .../formstate-destructure-formstate.md | 48 + ...ormstate-getfieldstate-for-single-field.md | 54 + .../formstate-subscribe-to-specific-fields.md | 54 + .../formstate-useformstate-isolation.md | 65 + .../integ-mui-controller-pattern.md | 59 + .../references/integ-shadcn-form-import.md | 64 + .../references/integ-shadcn-select-wiring.md | 64 + .../integ-typed-submit-server-action.md | 52 + .../references/integ-value-transform.md | 59 + .../references/sub-avoid-watch-in-render.md | 48 + .../references/sub-deep-subscription.md | 62 + .../sub-useformcontext-sparingly.md | 58 + .../references/sub-usewatch-default-value.md | 50 + .../references/sub-usewatch-over-watch.md | 58 + .../references/sub-usewatch-with-getvalues.md | 54 + .../references/sub-watch-specific-fields.md | 54 + .../references/valid-delay-error.md | 52 + .../valid-dynamic-schema-factory.md | 57 + .../valid-error-message-strategy.md | 82 + .../references/valid-form-level-validate.md | 47 + .../references/valid-inline-vs-resolver.md | 63 + .../references/valid-native-validation.md | 60 + .../references/valid-resolver-caching.md | 58 + .../references/valid-trigger-should-touch.md | 44 + agent/skills/react/SKILL.md | 86 + agent/skills/react/references/_sections.md | 46 + .../references/conc-automatic-batching.md | 64 + .../react/references/conc-concurrent-safe.md | 71 + .../references/conc-suspense-fallback.md | 66 + .../references/conc-use-deferred-value.md | 65 + .../react/references/conc-use-transition.md | 75 + .../react/references/conc-view-transitions.md | 81 + .../references/data-cache-deduplication.md | 60 + .../react/references/data-error-boundaries.md | 76 + .../references/data-parallel-fetching.md | 74 + .../references/data-suspense-data-fetching.md | 76 + .../skills/react/references/data-use-hook.md | 77 + .../references/effect-avoid-unnecessary.md | 69 + .../skills/react/references/effect-cleanup.md | 75 + .../references/effect-object-dependencies.md | 56 + .../references/effect-use-browser-only.md | 62 + .../references/effect-use-effect-event.md | 53 + .../effect-use-sync-external-store.md | 80 + agent/skills/react/references/form-actions.md | 83 + .../react/references/form-use-action-state.md | 80 + .../react/references/form-use-form-status.md | 68 + .../react/references/form-use-optimistic.md | 77 + .../react/references/form-validation.md | 89 + .../react/references/memo-avoid-premature.md | 68 + .../skills/react/references/memo-compiler.md | 84 + .../react/references/memo-react-memo.md | 72 + .../react/references/memo-use-callback.md | 70 + .../skills/react/references/memo-use-memo.md | 53 + .../react/references/rcomp-composition.md | 75 + .../references/rcomp-controlled-components.md | 63 + .../react/references/rcomp-fragment-refs.md | 71 + .../react/references/rcomp-key-reset.md | 74 + .../react/references/rcomp-render-props.md | 69 + .../references/rsc-avoid-client-only-libs.md | 66 + .../references/rsc-composition-pattern.md | 90 + .../react/references/rsc-context-provider.md | 50 + .../references/rsc-data-fetching-server.md | 68 + .../references/rsc-serializable-props.md | 70 + .../references/rsc-server-client-boundary.md | 63 + .../skills/react/references/rsc-streaming.md | 64 + .../references/rstate-context-optimization.md | 68 + .../react/references/rstate-derived-values.md | 70 + .../references/rstate-functional-updates.md | 58 + .../references/rstate-lazy-initialization.md | 59 + .../react/references/rstate-use-reducer.md | 77 + agent/skills/shadcn/SKILL.md | 109 + .../references/ally-ensure-color-contrast.md | 62 + .../ally-maintain-focus-management.md | 84 + .../ally-preserve-aria-attributes.md | 77 + .../ally-preserve-keyboard-navigation.md | 72 + .../references/ally-provide-sr-only-labels.md | 75 + .../references/arch-current-cli-registry.md | 61 + .../arch-extend-variants-with-cva.md | 67 + ...-forward-refs-for-composable-components.md | 83 + .../arch-isolate-component-variants.md | 82 + ...arch-preserve-radix-primitive-structure.md | 57 + .../references/arch-unified-radix-package.md | 44 + .../arch-use-asChild-for-custom-triggers.md | 49 + .../arch-use-cn-for-class-merging.md | 62 + .../comp-combine-command-with-popover.md | 106 + .../comp-compose-with-compound-components.md | 104 + .../comp-create-reusable-form-fields.md | 157 + .../references/comp-nest-dialogs-correctly.md | 108 + .../comp-use-drawer-for-mobile-modals.md | 128 + .../comp-use-slot-pattern-for-flexibility.md | 118 + .../data-empty-states-with-guidance.md | 95 + .../references/data-paginate-server-side.md | 108 + .../data-use-skeleton-loading-states.md | 104 + ...a-use-tanstack-table-for-complex-tables.md | 121 + .../references/data-virtualize-large-lists.md | 82 + .../form-handle-async-validation.md | 104 + .../form-reset-form-state-correctly.md | 92 + .../form-show-validation-errors-correctly.md | 58 + .../form-use-react-hook-form-integration.md | 106 + .../form-use-zod-for-schema-validation.md | 86 + ...rf-avoid-unnecessary-rerenders-in-forms.md | 88 + .../references/perf-debounce-search-inputs.md | 85 + .../perf-lazy-load-heavy-components.md | 90 + .../perf-memoize-expensive-renders.md | 90 + .../references/perf-optimize-icon-imports.md | 60 + .../state-colocate-state-with-components.md | 103 + .../state-lift-state-to-appropriate-level.md | 103 + ...e-prefer-uncontrolled-for-simple-inputs.md | 91 + .../state-use-controlled-dialog-state.md | 127 + .../style-avoid-important-overrides.md | 58 + .../style-consistent-spacing-scale.md | 67 + .../references/style-dark-mode-support.md | 83 + .../style-responsive-design-patterns.md | 75 + .../style-use-css-variables-for-theming.md | 56 + .../style-use-tailwind-theme-extend.md | 63 + agent/skills/tailwind/SKILL.md | 108 + .../tailwind/references/anim-3d-transforms.md | 56 + .../references/anim-gpu-accelerated.md | 47 + .../references/anim-gradient-interpolation.md | 46 + .../references/anim-starting-style.md | 63 + .../tailwind/references/build-cli-package.md | 43 + .../references/build-content-detection.md | 44 + .../tailwind/references/build-css-import.md | 36 + .../tailwind/references/build-node-version.md | 44 + .../references/build-postcss-simplify.md | 40 + .../tailwind/references/build-vite-plugin.md | 39 + .../references/bundle-avoid-cdn-production.md | 56 + .../references/bundle-avoid-preprocessors.md | 53 + .../references/bundle-css-minification.md | 57 + .../bundle-remove-unused-plugins.md | 55 + .../references/bundle-split-critical-css.md | 62 + .../references/comp-avoid-apply-overuse.md | 58 + .../references/comp-container-customize.md | 59 + .../references/comp-reference-directive.md | 59 + .../tailwind/references/comp-smart-sorting.md | 50 + .../references/comp-utility-file-scope.md | 61 + .../references/gen-avoid-theme-bloat.md | 47 + .../references/gen-css-first-config.md | 54 + .../references/gen-css-variable-syntax.md | 43 + .../references/gen-dynamic-utilities.md | 51 + .../tailwind/references/gen-oklch-colors.md | 40 + .../references/gen-utility-directive.md | 52 + .../references/resp-container-queries.md | 55 + .../references/resp-custom-breakpoints.md | 54 + .../references/resp-hover-capability.md | 60 + .../references/resp-logical-properties.md | 51 + .../tailwind/references/resp-mobile-first.md | 48 + .../tailwind/references/theme-color-scheme.md | 55 + .../references/theme-dark-mode-class.md | 59 + .../references/theme-prefix-variables.md | 56 + .../references/theme-runtime-variables.md | 55 + .../references/theme-semantic-tokens.md | 65 + .../references/util-explicit-colors.md | 43 + .../references/util-gradient-via-none.md | 37 + .../references/util-important-modifier.md | 43 + .../references/util-opacity-modifier.md | 50 + .../references/util-renamed-utilities.md | 45 + .../references/util-variant-stacking.md | 41 + agent/skills/tanstack-query/SKILL.md | 116 + .../references/cache-enabled-option.md | 76 + .../references/cache-global-defaults.md | 73 + .../cache-invalidation-precision.md | 78 + .../cache-placeholder-vs-initial.md | 69 + .../references/cache-refetch-triggers.md | 68 + .../references/cache-staletime-gctime.md | 71 + .../references/error-conditional-retry.md | 93 + .../references/error-display-patterns.md | 100 + .../references/error-global-handler.md | 91 + .../references/error-retry-config.md | 80 + .../references/error-throw-on-error.md | 96 + .../references/infinite-flatten-pages.md | 108 + .../references/infinite-loading-states.md | 96 + .../references/infinite-max-pages.md | 86 + .../references/infinite-refetch-behavior.md | 79 + .../references/mutation-avoid-parallel.md | 92 + .../references/mutation-cancel-queries.md | 72 + .../mutation-invalidate-onsettled.md | 66 + .../references/mutation-optimistic-updates.md | 81 + .../references/mutation-setquerydata.md | 67 + .../references/prefetch-avoid-waterfalls.md | 98 + .../references/prefetch-flatten-api.md | 70 + .../references/prefetch-in-queryfn.md | 97 + .../references/prefetch-infinite-query.md | 60 + .../references/prefetch-on-hover.md | 94 + .../references/prefetch-server-components.md | 88 + .../references/render-notify-props.md | 66 + .../references/render-select-derived.md | 86 + .../references/render-select-memoize.md | 75 + .../references/render-structural-sharing.md | 88 + .../references/render-tracked-props.md | 80 + .../suspense-boundaries-placement.md | 97 + .../references/suspense-error-boundaries.md | 100 + .../references/suspense-parallel-queries.md | 93 + .../references/suspense-use-suspense-hooks.md | 66 + .../references/tquery-always-arrays.md | 49 + .../references/tquery-colocate-keys.md | 66 + .../references/tquery-hierarchical-keys.md | 61 + .../references/tquery-key-factories.md | 58 + .../references/tquery-options-pattern.md | 78 + .../references/tquery-serializable-objects.md | 60 + agent/skills/tdd/SKILL.md | 113 + .../tdd/references/assert-custom-matchers.md | 86 + .../tdd/references/assert-error-messages.md | 64 + .../assert-no-assertions-antipattern.md | 70 + .../tdd/references/assert-snapshot-testing.md | 71 + .../references/assert-specific-assertions.md | 71 + .../references/cycle-maintain-test-list.md | 68 + .../references/cycle-minimal-code-to-pass.md | 62 + .../references/cycle-refactor-after-green.md | 58 + .../tdd/references/cycle-small-increments.md | 69 + .../cycle-verify-test-fails-first.md | 64 + .../tdd/references/cycle-write-test-first.md | 63 + .../references/data-avoid-mystery-guests.md | 62 + .../tdd/references/data-builder-pattern.md | 99 + .../tdd/references/data-minimal-setup.md | 69 + .../tdd/references/data-unique-identifiers.md | 79 + .../tdd/references/data-use-factories.md | 87 + .../tdd/references/design-aaa-pattern.md | 68 + .../references/design-avoid-logic-in-tests.md | 74 + .../design-descriptive-test-names.md | 64 + .../design-one-assertion-per-test.md | 66 + ...design-test-behavior-not-implementation.md | 69 + .../tdd/references/design-test-edge-cases.md | 83 + .../references/isolate-deterministic-tests.md | 80 + .../isolate-mock-external-dependencies.md | 69 + .../tdd/references/isolate-no-shared-state.md | 73 + .../isolate-prefer-stubs-over-mocks.md | 72 + .../isolate-use-dependency-injection.md | 91 + .../tdd/references/org-file-structure.md | 76 + .../tdd/references/org-group-by-behavior.md | 68 + .../tdd/references/org-parameterized-tests.md | 79 + .../tdd/references/org-setup-teardown.md | 84 + .../tdd/references/org-test-utilities.md | 98 + .../references/perf-avoid-network-calls.md | 78 + .../skills/tdd/references/perf-avoid-sleep.md | 82 + .../tdd/references/perf-fast-unit-tests.md | 48 + .../tdd/references/perf-fix-flaky-tests.md | 83 + .../tdd/references/perf-parallelize-tests.md | 87 + .../tdd/references/strat-coverage-targets.md | 70 + .../references/strat-e2e-critical-paths.md | 78 + .../strat-integration-boundaries.md | 79 + .../tdd/references/strat-mutation-testing.md | 71 + .../tdd/references/strat-test-pyramid.md | 58 + agent/skills/typescript/SKILL.md | 102 + .../references/advanced-branded-types.md | 83 + .../references/advanced-satisfies-operator.md | 94 + .../advanced-template-literal-types.md | 105 + .../references/async-avoid-loop-await.md | 78 + .../async-avoid-unnecessary-async.md | 61 + .../references/async-defer-await.md | 74 + .../references/async-explicit-return-types.md | 79 + .../references/async-parallel-promises.md | 63 + .../references/mem-avoid-closure-leaks.md | 88 + .../references/mem-avoid-global-state.md | 97 + .../references/mem-cleanup-event-listeners.md | 111 + .../typescript/references/mem-clear-timers.md | 106 + .../mem-use-weakmap-for-metadata.md | 84 + .../references/module-avoid-barrel-imports.md | 70 + .../module-avoid-circular-dependencies.md | 92 + .../module-control-types-inclusion.md | 92 + .../references/module-dynamic-imports.md | 78 + .../references/module-use-type-imports.md | 80 + .../runtime-avoid-object-spread-in-loops.md | 79 + .../runtime-cache-property-access.md | 85 + .../runtime-prefer-array-methods.md | 73 + .../runtime-use-for-of-for-iteration.md | 89 + .../references/runtime-use-set-for-lookups.md | 64 + .../references/runtime-use-string-methods.md | 79 + .../references/safety-assertion-functions.md | 92 + .../references/safety-const-assertions.md | 77 + .../references/safety-exhaustive-checks.md | 83 + .../safety-prefer-unknown-over-any.md | 76 + .../references/safety-strict-null-checks.md | 72 + .../references/safety-use-type-guards.md | 86 + .../references/tscfg-enable-incremental.md | 68 + .../references/tscfg-exclude-properly.md | 85 + .../references/tscfg-isolate-modules.md | 68 + .../references/tscfg-project-references.md | 97 + .../references/tscfg-skip-lib-check.md | 63 + .../references/tscfg-strict-function-types.md | 67 + .../references/tscfg-typescript-7.md | 75 + .../references/type-avoid-deep-generics.md | 81 + .../references/type-avoid-large-unions.md | 57 + .../references/type-explicit-return-types.md | 65 + .../type-extract-conditional-types.md | 57 + .../type-interfaces-over-intersections.md | 41 + .../references/type-limit-recursion-depth.md | 65 + .../references/type-simplify-mapped-types.md | 71 + agent/skills/ui-design/SKILL.md | 101 + .../ui-design/references/access-alt-text.md | 63 + .../references/access-aria-labels.md | 57 + .../references/access-focus-indicators.md | 53 + .../references/access-heading-hierarchy.md | 48 + .../references/access-keyboard-navigation.md | 52 + .../references/access-semantic-html.md | 53 + .../references/access-target-size.md | 56 + .../references/anim-duration-easing.md | 77 + .../references/anim-gpu-properties.md | 75 + .../references/anim-reduced-motion.md | 82 + .../ui-design/references/anim-will-change.md | 78 + .../references/color-contrast-ratio.md | 67 + .../ui-design/references/color-dark-mode.md | 74 + .../references/color-not-only-indicator.md | 79 + .../references/color-semantic-palette.md | 64 + .../ui-design/references/cwv-critical-css.md | 55 + .../ui-design/references/cwv-improve-inp.md | 70 + .../references/cwv-lazy-load-offscreen.md | 60 + .../ui-design/references/cwv-minimize-cls.md | 66 + .../ui-design/references/cwv-optimize-lcp.md | 59 + .../references/cwv-responsive-images.md | 63 + .../ui-design/references/form-autocomplete.md | 62 + .../references/form-error-messages.md | 61 + .../references/form-inline-validation.md | 67 + .../ui-design/references/form-input-types.md | 63 + .../ui-design/references/form-labels-above.md | 74 + .../ui-design/references/layout-f-pattern.md | 65 + .../references/layout-grid-system.md | 67 + .../references/layout-proximity-grouping.md | 57 + .../ui-design/references/layout-single-cta.md | 64 + .../references/layout-visual-hierarchy.md | 69 + .../ui-design/references/layout-whitespace.md | 70 + .../references/resp-container-queries.md | 64 + .../references/resp-fluid-typography.md | 65 + .../ui-design/references/resp-mobile-first.md | 83 + .../references/resp-touch-targets.md | 67 + .../references/resp-viewport-meta.md | 57 + .../ui-design/references/typo-font-display.md | 61 + .../ui-design/references/typo-line-height.md | 66 + .../references/typo-preload-fonts.md | 62 + .../references/typo-readable-line-length.md | 58 + .../references/typo-system-font-stack.md | 57 + .../vercel-composition-patterns/SKILL.md | 73 + .../rules/architecture-avoid-boolean-props.md | 102 + .../rules/architecture-compound-components.md | 112 + .../patterns-children-over-render-props.md | 87 + .../rules/patterns-explicit-variants.md | 100 + .../rules/react19-no-forwardref.md | 42 + .../rules/state-context-interface.md | 191 + .../rules/state-decouple-implementation.md | 113 + .../rules/state-lift-state.md | 125 + .../vercel-react-best-practices/SKILL.md | 133 + .../rules/advanced-effect-event-deps.md | 56 + .../rules/advanced-event-handler-refs.md | 55 + .../rules/advanced-init-once.md | 42 + .../rules/advanced-use-latest.md | 39 + .../rules/async-api-routes.md | 38 + .../async-cheap-condition-before-await.md | 37 + .../rules/async-defer-await.md | 82 + .../rules/async-dependencies.md | 51 + .../rules/async-parallel.md | 28 + .../rules/async-suspense-boundaries.md | 99 + .../rules/bundle-analyzable-paths.md | 63 + .../rules/bundle-barrel-imports.md | 60 + .../rules/bundle-conditional.md | 31 + .../rules/bundle-defer-third-party.md | 49 + .../rules/bundle-dynamic-imports.md | 35 + .../rules/bundle-preload.md | 50 + .../rules/client-event-listeners.md | 74 + .../rules/client-localstorage-schema.md | 71 + .../rules/client-passive-event-listeners.md | 48 + .../rules/client-swr-dedup.md | 56 + .../rules/js-batch-dom-css.md | 107 + .../rules/js-cache-function-results.md | 80 + .../rules/js-cache-property-access.md | 28 + .../rules/js-cache-storage.md | 70 + .../rules/js-combine-iterations.md | 32 + .../rules/js-early-exit.md | 50 + .../rules/js-flatmap-filter.md | 60 + .../rules/js-hoist-regexp.md | 45 + .../rules/js-index-maps.md | 37 + .../rules/js-length-check-first.md | 49 + .../rules/js-min-max-loop.md | 82 + .../rules/js-request-idle-callback.md | 105 + .../rules/js-set-map-lookups.md | 24 + .../rules/js-tosorted-immutable.md | 57 + .../rules/rendering-activity.md | 26 + .../rules/rendering-animate-svg-wrapper.md | 47 + .../rules/rendering-conditional-render.md | 40 + .../rules/rendering-content-visibility.md | 38 + .../rules/rendering-hoist-jsx.md | 46 + .../rules/rendering-hydration-no-flicker.md | 82 + .../rendering-hydration-suppress-warning.md | 30 + .../rules/rendering-resource-hints.md | 85 + .../rules/rendering-script-defer-async.md | 68 + .../rules/rendering-svg-precision.md | 28 + .../rules/rendering-usetransition-loading.md | 79 + .../rules/rerender-defer-reads.md | 39 + .../rules/rerender-dependencies.md | 45 + .../rules/rerender-derived-state-no-effect.md | 40 + .../rules/rerender-derived-state.md | 29 + .../rules/rerender-functional-setstate.md | 74 + .../rules/rerender-lazy-state-init.md | 58 + .../rules/rerender-memo-with-default-value.md | 38 + .../rules/rerender-memo.md | 44 + .../rules/rerender-move-effect-to-event.md | 45 + .../rules/rerender-no-inline-components.md | 82 + .../rerender-simple-expression-in-memo.md | 35 + .../rules/rerender-split-combined-hooks.md | 64 + .../rules/rerender-transitions.md | 40 + .../rules/rerender-use-deferred-value.md | 59 + .../rerender-use-ref-transient-values.md | 73 + .../rules/server-after-nonblocking.md | 73 + .../rules/server-auth-actions.md | 96 + .../rules/server-cache-lru.md | 41 + .../rules/server-cache-react.md | 76 + .../rules/server-dedup-props.md | 65 + .../rules/server-hoist-static-io.md | 149 + .../rules/server-no-shared-module-state.md | 50 + .../rules/server-parallel-fetching.md | 83 + .../rules/server-parallel-nested-fetching.md | 34 + .../rules/server-serialization.md | 38 + agent/skills/vitest/SKILL.md | 121 + .../vitest/references/assert-edge-cases.md | 83 + .../references/assert-expect-assertions.md | 95 + .../assert-one-assertion-concept.md | 94 + .../references/assert-specific-matchers.md | 83 + .../references/assert-toequal-vs-tobe.md | 91 + .../vitest/references/async-act-wrapper.md | 79 + .../references/async-await-assertions.md | 45 + .../references/async-concurrent-expect.md | 60 + .../vitest/references/async-error-handling.md | 72 + .../vitest/references/async-fake-timers.md | 82 + .../references/async-return-promises.md | 60 + .../references/async-waitfor-polling.md | 84 + .../references/env-browser-api-mocking.md | 96 + .../vitest/references/env-globals-config.md | 85 + .../references/env-per-file-override.md | 115 + .../vitest/references/env-setup-files.md | 94 + .../references/mock-avoid-overmocking.md | 98 + .../references/mock-clear-between-tests.md | 86 + .../mock-implementation-not-value.md | 81 + .../vitest/references/mock-msw-network.md | 96 + .../vitest/references/mock-spyon-vs-mock.md | 85 + .../vitest/references/mock-type-safety.md | 97 + .../references/mock-vi-mock-hoisting.md | 95 + .../vitest/references/org-describe-nesting.md | 85 + .../vitest/references/org-file-colocation.md | 93 + .../vitest/references/org-test-naming.md | 86 + .../vitest/references/org-test-skip-only.md | 75 + .../vitest/references/perf-bail-fast-fail.md | 84 + .../references/perf-bench-test-context.md | 59 + .../references/perf-disable-isolation.md | 91 + .../vitest/references/perf-happy-dom.md | 103 + .../vitest/references/perf-pool-selection.md | 78 + .../vitest/references/perf-run-mode-ci.md | 93 + .../skills/vitest/references/perf-sharding.md | 101 + .../references/setup-avoid-shared-state.md | 98 + .../references/setup-beforeall-expensive.md | 81 + .../references/setup-beforeeach-cleanup.md | 83 + .../vitest/references/setup-reset-modules.md | 91 + .../vitest/references/setup-restore-mocks.md | 88 + .../vitest/references/setup-test-factories.md | 104 + .../references/setup-vitest5-migration.md | 64 + .../vitest/references/snap-avoid-large.md | 76 + .../vitest/references/snap-describe-intent.md | 78 + .../references/snap-inline-over-file.md | 73 + .../vitest/references/snap-review-updates.md | 79 + .../references/snap-stable-serialization.md | 97 + agent/skills/web-design-guidelines/SKILL.md | 38 + agent/skills/zod/SKILL.md | 127 + .../zod/references/compose-intersection.md | 147 + .../zod/references/compose-lazy-recursive.md | 154 + agent/skills/zod/references/compose-pipe.md | 113 + .../zod/references/compose-preprocess.md | 142 + .../zod/references/compose-shared-schemas.md | 138 + .../error-avoid-throwing-in-refine.md | 127 + .../zod/references/error-custom-messages.md | 113 + agent/skills/zod/references/error-i18n.md | 141 + .../zod/references/error-path-for-nested.md | 133 + .../zod/references/error-use-flatten.md | 85 + .../references/object-discriminated-unions.md | 138 + .../object-extend-for-composition.md | 145 + .../references/object-optional-vs-nullable.md | 117 + .../references/object-partial-for-updates.md | 142 + .../skills/zod/references/object-pick-omit.md | 146 + .../zod/references/object-strict-vs-strip.md | 70 + .../parse-async-for-async-refinements.md | 118 + .../parse-avoid-double-validation.md | 129 + .../zod/references/parse-handle-all-issues.md | 125 + .../zod/references/parse-never-trust-json.md | 113 + .../zod/references/parse-use-safeparse.md | 102 + .../zod/references/parse-validate-early.md | 120 + .../parse-validate-for-boolean-checks.md | 64 + agent/skills/zod/references/perf-arrays.md | 153 + .../references/perf-avoid-dynamic-creation.md | 97 + .../zod/references/perf-cache-schemas.md | 138 + .../zod/references/perf-compile-schemas.md | 76 + .../zod/references/perf-lazy-loading.md | 135 + agent/skills/zod/references/perf-zod-mini.md | 110 + .../skills/zod/references/refine-add-path.md | 141 + agent/skills/zod/references/refine-catch.md | 143 + .../skills/zod/references/refine-defaults.md | 131 + .../zod/references/refine-transform-coerce.md | 105 + .../skills/zod/references/refine-use-codec.md | 41 + .../zod/references/refine-vs-superrefine.md | 152 + .../references/schema-avoid-optional-abuse.md | 93 + .../schema-coercion-for-form-data.md | 88 + .../references/schema-string-validations.md | 114 + .../skills/zod/references/schema-use-enums.md | 115 + .../schema-use-primitives-correctly.md | 61 + .../references/schema-use-unknown-not-any.md | 88 + .../zod/references/type-branded-types.md | 102 + .../zod/references/type-enable-strict-mode.md | 130 + .../type-export-schemas-and-types.md | 116 + .../zod/references/type-input-vs-output.md | 116 + .../skills/zod/references/type-use-z-infer.md | 110 + certs/.gitignore | 2 + compose.dbs.yaml | 70 + compose.yaml | 61 + docs/ARCHITECTURE.md | 142 + docs/DESIGN.md | 65 + docs/MIGRATION.md | 245 ++ docs/OPERATIONS.md | 388 ++ docs/PRODUCT.md | 37 + docs/README_PL.md | 90 + docs/ROADMAP.md | 42 + docs/SECURITY.md | 94 + .../diagrams/BackupService_MapaMysli.png | Bin .../diagrams/ServiceLogicProject.drawio | 0 .../ServiceLogicProject_v1.0_Drawio.jpg | Bin .../ServiceLogicProject_v1.2_Drawio.png | Bin global.json | 1 + scripts/check-compose.mjs | 203 + scripts/dev.mjs | 126 + skills-lock.json | 113 + 2609 files changed, 189466 insertions(+), 7299 deletions(-) create mode 100644 .agents/skills/feature-arch/SKILL.md create mode 100644 .agents/skills/feature-arch/references/bound-event-based-communication.md create mode 100644 .agents/skills/feature-arch/references/bound-feature-isolation.md create mode 100644 .agents/skills/feature-arch/references/bound-feature-scoped-routing.md create mode 100644 .agents/skills/feature-arch/references/bound-feature-size.md create mode 100644 .agents/skills/feature-arch/references/bound-interface-contracts.md create mode 100644 .agents/skills/feature-arch/references/bound-minimize-shared-state.md create mode 100644 .agents/skills/feature-arch/references/fcomp-colocate-styles.md create mode 100644 .agents/skills/feature-arch/references/fcomp-composition-over-props.md create mode 100644 .agents/skills/feature-arch/references/fcomp-container-presentational.md create mode 100644 .agents/skills/feature-arch/references/fcomp-error-boundaries.md create mode 100644 .agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md create mode 100644 .agents/skills/feature-arch/references/fcomp-single-responsibility.md create mode 100644 .agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md create mode 100644 .agents/skills/feature-arch/references/fquery-colocate-with-feature.md create mode 100644 .agents/skills/feature-arch/references/fquery-feature-scoped-keys.md create mode 100644 .agents/skills/feature-arch/references/fquery-parallel-fetching.md create mode 100644 .agents/skills/feature-arch/references/fquery-server-component-fetching.md create mode 100644 .agents/skills/feature-arch/references/fquery-single-responsibility.md create mode 100644 .agents/skills/feature-arch/references/fstate-context-sparingly.md create mode 100644 .agents/skills/feature-arch/references/fstate-feature-scoped-stores.md create mode 100644 .agents/skills/feature-arch/references/fstate-lift-minimally.md create mode 100644 .agents/skills/feature-arch/references/fstate-reset-on-unmount.md create mode 100644 .agents/skills/feature-arch/references/fstate-server-state-separation.md create mode 100644 .agents/skills/feature-arch/references/import-avoid-barrel-files.md create mode 100644 .agents/skills/feature-arch/references/import-no-cross-feature.md create mode 100644 .agents/skills/feature-arch/references/import-path-aliases.md create mode 100644 .agents/skills/feature-arch/references/import-public-api.md create mode 100644 .agents/skills/feature-arch/references/import-type-only.md create mode 100644 .agents/skills/feature-arch/references/import-unidirectional-flow.md create mode 100644 .agents/skills/feature-arch/references/name-descriptive-exports.md create mode 100644 .agents/skills/feature-arch/references/name-feature-naming.md create mode 100644 .agents/skills/feature-arch/references/name-file-conventions.md create mode 100644 .agents/skills/feature-arch/references/struct-app-layer.md create mode 100644 .agents/skills/feature-arch/references/struct-feature-folders.md create mode 100644 .agents/skills/feature-arch/references/struct-feature-self-contained.md create mode 100644 .agents/skills/feature-arch/references/struct-flat-hierarchy.md create mode 100644 .agents/skills/feature-arch/references/struct-optional-segments.md create mode 100644 .agents/skills/feature-arch/references/struct-shared-layer.md create mode 100644 .agents/skills/feature-arch/references/test-colocate-with-feature.md create mode 100644 .agents/skills/feature-arch/references/test-feature-isolation.md create mode 100644 .agents/skills/feature-arch/references/test-integration-at-app-layer.md create mode 100644 .agents/skills/feature-arch/references/test-shared-utilities.md create mode 100644 .agents/skills/msw/SKILL.md create mode 100644 .agents/skills/msw/references/advanced-bypass-requests.md create mode 100644 .agents/skills/msw/references/advanced-cookies-auth.md create mode 100644 .agents/skills/msw/references/advanced-dynamic-scenarios.md create mode 100644 .agents/skills/msw/references/advanced-file-uploads.md create mode 100644 .agents/skills/msw/references/advanced-playwright-integration.md create mode 100644 .agents/skills/msw/references/advanced-vitest-browser.md create mode 100644 .agents/skills/msw/references/advanced-websocket-mocking.md create mode 100644 .agents/skills/msw/references/debug-common-issues.md create mode 100644 .agents/skills/msw/references/debug-lifecycle-events.md create mode 100644 .agents/skills/msw/references/debug-request-logging.md create mode 100644 .agents/skills/msw/references/debug-verify-interception.md create mode 100644 .agents/skills/msw/references/graphql-batched-queries.md create mode 100644 .agents/skills/msw/references/graphql-error-responses.md create mode 100644 .agents/skills/msw/references/graphql-operation-handlers.md create mode 100644 .agents/skills/msw/references/graphql-schema-first.md create mode 100644 .agents/skills/msw/references/graphql-variables-access.md create mode 100644 .agents/skills/msw/references/handler-absolute-urls.md create mode 100644 .agents/skills/msw/references/handler-domain-grouping.md create mode 100644 .agents/skills/msw/references/handler-happy-path-first.md create mode 100644 .agents/skills/msw/references/handler-request-body-parsing.md create mode 100644 .agents/skills/msw/references/handler-resolver-argument.md create mode 100644 .agents/skills/msw/references/handler-reusability-environments.md create mode 100644 .agents/skills/msw/references/handler-shared-resolvers.md create mode 100644 .agents/skills/msw/references/handler-v2-response-syntax.md create mode 100644 .agents/skills/msw/references/match-custom-predicate.md create mode 100644 .agents/skills/msw/references/match-handler-order.md create mode 100644 .agents/skills/msw/references/match-http-methods.md create mode 100644 .agents/skills/msw/references/match-query-params.md create mode 100644 .agents/skills/msw/references/match-url-patterns.md create mode 100644 .agents/skills/msw/references/response-custom-headers.md create mode 100644 .agents/skills/msw/references/response-delay-realistic.md create mode 100644 .agents/skills/msw/references/response-error-simulation.md create mode 100644 .agents/skills/msw/references/response-http-response-helpers.md create mode 100644 .agents/skills/msw/references/response-one-time-handlers.md create mode 100644 .agents/skills/msw/references/response-streaming.md create mode 100644 .agents/skills/msw/references/setup-lifecycle-hooks.md create mode 100644 .agents/skills/msw/references/setup-node-version.md create mode 100644 .agents/skills/msw/references/setup-server-node-entrypoint.md create mode 100644 .agents/skills/msw/references/setup-typescript-config.md create mode 100644 .agents/skills/msw/references/setup-unhandled-requests.md create mode 100644 .agents/skills/msw/references/setup-worker-script-commit.md create mode 100644 .agents/skills/msw/references/test-async-utilities.md create mode 100644 .agents/skills/msw/references/test-avoid-request-assertions.md create mode 100644 .agents/skills/msw/references/test-clear-request-cache.md create mode 100644 .agents/skills/msw/references/test-concurrent-boundary.md create mode 100644 .agents/skills/msw/references/test-fake-timers-config.md create mode 100644 .agents/skills/msw/references/test-jsdom-environment.md create mode 100644 .agents/skills/msw/references/test-reset-handlers.md create mode 100644 .agents/skills/nextjs/SKILL.md create mode 100644 .agents/skills/nextjs/references/action-error-handling.md create mode 100644 .agents/skills/nextjs/references/action-optimistic-updates.md create mode 100644 .agents/skills/nextjs/references/action-pending-states.md create mode 100644 .agents/skills/nextjs/references/action-revalidation.md create mode 100644 .agents/skills/nextjs/references/action-server-action-forms.md create mode 100644 .agents/skills/nextjs/references/build-barrel-files.md create mode 100644 .agents/skills/nextjs/references/build-dynamic-imports.md create mode 100644 .agents/skills/nextjs/references/build-external-packages.md create mode 100644 .agents/skills/nextjs/references/build-optimize-package-imports.md create mode 100644 .agents/skills/nextjs/references/build-turbopack-config.md create mode 100644 .agents/skills/nextjs/references/cache-fetch-options.md create mode 100644 .agents/skills/nextjs/references/cache-react-cache.md create mode 100644 .agents/skills/nextjs/references/cache-revalidate-path.md create mode 100644 .agents/skills/nextjs/references/cache-revalidate-tag.md create mode 100644 .agents/skills/nextjs/references/cache-segment-config.md create mode 100644 .agents/skills/nextjs/references/cache-use-cache-directive.md create mode 100644 .agents/skills/nextjs/references/client-children-pattern.md create mode 100644 .agents/skills/nextjs/references/client-hydration-mismatch.md create mode 100644 .agents/skills/nextjs/references/client-third-party-scripts.md create mode 100644 .agents/skills/nextjs/references/client-use-client-boundary.md create mode 100644 .agents/skills/nextjs/references/meta-generate-metadata.md create mode 100644 .agents/skills/nextjs/references/meta-opengraph-images.md create mode 100644 .agents/skills/nextjs/references/meta-robots.md create mode 100644 .agents/skills/nextjs/references/meta-sitemap.md create mode 100644 .agents/skills/nextjs/references/route-instant-navigations.md create mode 100644 .agents/skills/nextjs/references/route-intercepting-routes.md create mode 100644 .agents/skills/nextjs/references/route-not-found.md create mode 100644 .agents/skills/nextjs/references/route-parallel-routes.md create mode 100644 .agents/skills/nextjs/references/route-partial-prefetching.md create mode 100644 .agents/skills/nextjs/references/route-prefetching.md create mode 100644 .agents/skills/nextjs/references/route-proxy-ts.md create mode 100644 .agents/skills/nextjs/references/server-avoid-client-fetching.md create mode 100644 .agents/skills/nextjs/references/server-component-streaming.md create mode 100644 .agents/skills/nextjs/references/server-data-colocation.md create mode 100644 .agents/skills/nextjs/references/server-error-handling.md create mode 100644 .agents/skills/nextjs/references/server-parallel-fetching.md create mode 100644 .agents/skills/nextjs/references/server-preload-pattern.md create mode 100644 .agents/skills/nextjs/references/stream-error-tsx.md create mode 100644 .agents/skills/nextjs/references/stream-loading-tsx.md create mode 100644 .agents/skills/nextjs/references/stream-nested-suspense.md create mode 100644 .agents/skills/nextjs/references/stream-skeleton-matching.md create mode 100644 .agents/skills/nextjs/references/stream-suspense-boundaries.md create mode 100644 .agents/skills/nuqs/SKILL.md create mode 100644 .agents/skills/nuqs/references/advanced-custom-parsers.md create mode 100644 .agents/skills/nuqs/references/advanced-eq-function.md create mode 100644 .agents/skills/nuqs/references/advanced-framework-adapters.md create mode 100644 .agents/skills/nuqs/references/advanced-url-keys.md create mode 100644 .agents/skills/nuqs/references/debug-common-errors.md create mode 100644 .agents/skills/nuqs/references/debug-enable-logging.md create mode 100644 .agents/skills/nuqs/references/debug-testing.md create mode 100644 .agents/skills/nuqs/references/history-back-sync.md create mode 100644 .agents/skills/nuqs/references/history-push-navigation.md create mode 100644 .agents/skills/nuqs/references/history-replace-ephemeral.md create mode 100644 .agents/skills/nuqs/references/history-scroll-behavior.md create mode 100644 .agents/skills/nuqs/references/parser-array-format.md create mode 100644 .agents/skills/nuqs/references/parser-date-format.md create mode 100644 .agents/skills/nuqs/references/parser-enum-validation.md create mode 100644 .agents/skills/nuqs/references/parser-hex-colors.md create mode 100644 .agents/skills/nuqs/references/parser-index-offset.md create mode 100644 .agents/skills/nuqs/references/parser-json-validation.md create mode 100644 .agents/skills/nuqs/references/parser-use-typed-parsers.md create mode 100644 .agents/skills/nuqs/references/parser-with-default.md create mode 100644 .agents/skills/nuqs/references/perf-avoid-rerender.md create mode 100644 .agents/skills/nuqs/references/perf-clear-on-default.md create mode 100644 .agents/skills/nuqs/references/perf-debounce-search.md create mode 100644 .agents/skills/nuqs/references/perf-serialize-utility.md create mode 100644 .agents/skills/nuqs/references/perf-throttle-updates.md create mode 100644 .agents/skills/nuqs/references/server-next15-async.md create mode 100644 .agents/skills/nuqs/references/server-parse-before-get.md create mode 100644 .agents/skills/nuqs/references/server-search-params-cache.md create mode 100644 .agents/skills/nuqs/references/server-shallow-false.md create mode 100644 .agents/skills/nuqs/references/server-share-parsers.md create mode 100644 .agents/skills/nuqs/references/server-use-transition.md create mode 100644 .agents/skills/nuqs/references/setup-import-server.md create mode 100644 .agents/skills/nuqs/references/setup-nextjs-version.md create mode 100644 .agents/skills/nuqs/references/setup-nuqs-adapter.md create mode 100644 .agents/skills/nuqs/references/setup-shared-parsers.md create mode 100644 .agents/skills/nuqs/references/setup-use-client.md create mode 100644 .agents/skills/nuqs/references/state-avoid-derived.md create mode 100644 .agents/skills/nuqs/references/state-clear-with-null.md create mode 100644 .agents/skills/nuqs/references/state-controlled-inputs.md create mode 100644 .agents/skills/nuqs/references/state-functional-updates.md create mode 100644 .agents/skills/nuqs/references/state-options-inheritance.md create mode 100644 .agents/skills/nuqs/references/state-setter-return.md create mode 100644 .agents/skills/nuqs/references/state-use-query-states.md create mode 100644 .agents/skills/playwright/SKILL.md create mode 100644 .agents/skills/playwright/references/arch-cleanup-state.md create mode 100644 .agents/skills/playwright/references/arch-fixtures.md create mode 100644 .agents/skills/playwright/references/arch-page-object-model.md create mode 100644 .agents/skills/playwright/references/arch-parallel-execution.md create mode 100644 .agents/skills/playwright/references/arch-test-isolation.md create mode 100644 .agents/skills/playwright/references/arch-test-production.md create mode 100644 .agents/skills/playwright/references/assert-aria-snapshots.md create mode 100644 .agents/skills/playwright/references/auth-api-login.md create mode 100644 .agents/skills/playwright/references/auth-multiple-roles.md create mode 100644 .agents/skills/playwright/references/auth-parallel-workers.md create mode 100644 .agents/skills/playwright/references/auth-session-storage.md create mode 100644 .agents/skills/playwright/references/auth-storage-state.md create mode 100644 .agents/skills/playwright/references/debug-ci-reporters.md create mode 100644 .agents/skills/playwright/references/debug-inspector.md create mode 100644 .agents/skills/playwright/references/debug-screenshots-videos.md create mode 100644 .agents/skills/playwright/references/debug-trace-viewer.md create mode 100644 .agents/skills/playwright/references/loc-avoid-xpath.md create mode 100644 .agents/skills/playwright/references/loc-chained-locators.md create mode 100644 .agents/skills/playwright/references/loc-data-testid.md create mode 100644 .agents/skills/playwright/references/loc-frame-locator.md create mode 100644 .agents/skills/playwright/references/loc-label-selectors.md create mode 100644 .agents/skills/playwright/references/loc-placeholder-selector.md create mode 100644 .agents/skills/playwright/references/loc-role-selectors.md create mode 100644 .agents/skills/playwright/references/loc-text-selectors.md create mode 100644 .agents/skills/playwright/references/mock-abort-requests.md create mode 100644 .agents/skills/playwright/references/mock-api-responses.md create mode 100644 .agents/skills/playwright/references/mock-har-files.md create mode 100644 .agents/skills/playwright/references/mock-intercept-modify.md create mode 100644 .agents/skills/playwright/references/mock-network-conditions.md create mode 100644 .agents/skills/playwright/references/next-app-router-navigation.md create mode 100644 .agents/skills/playwright/references/next-baseurl-config.md create mode 100644 .agents/skills/playwright/references/next-server-actions.md create mode 100644 .agents/skills/playwright/references/next-server-components.md create mode 100644 .agents/skills/playwright/references/next-wait-hydration.md create mode 100644 .agents/skills/playwright/references/perf-browser-selection.md create mode 100644 .agents/skills/playwright/references/perf-headless-ci.md create mode 100644 .agents/skills/playwright/references/perf-retries.md create mode 100644 .agents/skills/playwright/references/perf-reuse-server.md create mode 100644 .agents/skills/playwright/references/perf-sharding.md create mode 100644 .agents/skills/playwright/references/wait-action-retries.md create mode 100644 .agents/skills/playwright/references/wait-avoid-hard-waits.md create mode 100644 .agents/skills/playwright/references/wait-custom-timeout.md create mode 100644 .agents/skills/playwright/references/wait-network-idle.md create mode 100644 .agents/skills/playwright/references/wait-soft-assertions.md create mode 100644 .agents/skills/playwright/references/wait-web-first-assertions.md create mode 100644 .agents/skills/react-hook-form/SKILL.md create mode 100644 .agents/skills/react-hook-form/references/adv-devtools-performance.md create mode 100644 .agents/skills/react-hook-form/references/adv-formprovider-memo.md create mode 100644 .agents/skills/react-hook-form/references/adv-opaque-types.md create mode 100644 .agents/skills/react-hook-form/references/adv-testing-wrapper.md create mode 100644 .agents/skills/react-hook-form/references/array-complete-default-objects.md create mode 100644 .agents/skills/react-hook-form/references/array-separate-crud-operations.md create mode 100644 .agents/skills/react-hook-form/references/array-unique-fieldarray-per-name.md create mode 100644 .agents/skills/react-hook-form/references/array-use-field-id-as-key.md create mode 100644 .agents/skills/react-hook-form/references/array-virtualization-formprovider.md create mode 100644 .agents/skills/react-hook-form/references/ctrl-avoid-double-registration.md create mode 100644 .agents/skills/react-hook-form/references/ctrl-controller-field-props.md create mode 100644 .agents/skills/react-hook-form/references/ctrl-local-state-combination.md create mode 100644 .agents/skills/react-hook-form/references/ctrl-single-usecontroller-per-component.md create mode 100644 .agents/skills/react-hook-form/references/ctrl-usecontroller-isolation.md create mode 100644 .agents/skills/react-hook-form/references/formcfg-async-default-values.md create mode 100644 .agents/skills/react-hook-form/references/formcfg-default-values.md create mode 100644 .agents/skills/react-hook-form/references/formcfg-revalidate-mode.md create mode 100644 .agents/skills/react-hook-form/references/formcfg-should-unregister.md create mode 100644 .agents/skills/react-hook-form/references/formcfg-useeffect-dependency.md create mode 100644 .agents/skills/react-hook-form/references/formcfg-validation-mode.md create mode 100644 .agents/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md create mode 100644 .agents/skills/react-hook-form/references/formstate-destructure-formstate.md create mode 100644 .agents/skills/react-hook-form/references/formstate-getfieldstate-for-single-field.md create mode 100644 .agents/skills/react-hook-form/references/formstate-subscribe-to-specific-fields.md create mode 100644 .agents/skills/react-hook-form/references/formstate-useformstate-isolation.md create mode 100644 .agents/skills/react-hook-form/references/integ-mui-controller-pattern.md create mode 100644 .agents/skills/react-hook-form/references/integ-shadcn-form-import.md create mode 100644 .agents/skills/react-hook-form/references/integ-shadcn-select-wiring.md create mode 100644 .agents/skills/react-hook-form/references/integ-typed-submit-server-action.md create mode 100644 .agents/skills/react-hook-form/references/integ-value-transform.md create mode 100644 .agents/skills/react-hook-form/references/sub-avoid-watch-in-render.md create mode 100644 .agents/skills/react-hook-form/references/sub-deep-subscription.md create mode 100644 .agents/skills/react-hook-form/references/sub-useformcontext-sparingly.md create mode 100644 .agents/skills/react-hook-form/references/sub-usewatch-default-value.md create mode 100644 .agents/skills/react-hook-form/references/sub-usewatch-over-watch.md create mode 100644 .agents/skills/react-hook-form/references/sub-usewatch-with-getvalues.md create mode 100644 .agents/skills/react-hook-form/references/sub-watch-specific-fields.md create mode 100644 .agents/skills/react-hook-form/references/valid-delay-error.md create mode 100644 .agents/skills/react-hook-form/references/valid-dynamic-schema-factory.md create mode 100644 .agents/skills/react-hook-form/references/valid-error-message-strategy.md create mode 100644 .agents/skills/react-hook-form/references/valid-form-level-validate.md create mode 100644 .agents/skills/react-hook-form/references/valid-inline-vs-resolver.md create mode 100644 .agents/skills/react-hook-form/references/valid-native-validation.md create mode 100644 .agents/skills/react-hook-form/references/valid-resolver-caching.md create mode 100644 .agents/skills/react-hook-form/references/valid-trigger-should-touch.md create mode 100644 .agents/skills/react/SKILL.md create mode 100644 .agents/skills/react/references/_sections.md create mode 100644 .agents/skills/react/references/conc-automatic-batching.md create mode 100644 .agents/skills/react/references/conc-concurrent-safe.md create mode 100644 .agents/skills/react/references/conc-suspense-fallback.md create mode 100644 .agents/skills/react/references/conc-use-deferred-value.md create mode 100644 .agents/skills/react/references/conc-use-transition.md create mode 100644 .agents/skills/react/references/conc-view-transitions.md create mode 100644 .agents/skills/react/references/data-cache-deduplication.md create mode 100644 .agents/skills/react/references/data-error-boundaries.md create mode 100644 .agents/skills/react/references/data-parallel-fetching.md create mode 100644 .agents/skills/react/references/data-suspense-data-fetching.md create mode 100644 .agents/skills/react/references/data-use-hook.md create mode 100644 .agents/skills/react/references/effect-avoid-unnecessary.md create mode 100644 .agents/skills/react/references/effect-cleanup.md create mode 100644 .agents/skills/react/references/effect-object-dependencies.md create mode 100644 .agents/skills/react/references/effect-use-browser-only.md create mode 100644 .agents/skills/react/references/effect-use-effect-event.md create mode 100644 .agents/skills/react/references/effect-use-sync-external-store.md create mode 100644 .agents/skills/react/references/form-actions.md create mode 100644 .agents/skills/react/references/form-use-action-state.md create mode 100644 .agents/skills/react/references/form-use-form-status.md create mode 100644 .agents/skills/react/references/form-use-optimistic.md create mode 100644 .agents/skills/react/references/form-validation.md create mode 100644 .agents/skills/react/references/memo-avoid-premature.md create mode 100644 .agents/skills/react/references/memo-compiler.md create mode 100644 .agents/skills/react/references/memo-react-memo.md create mode 100644 .agents/skills/react/references/memo-use-callback.md create mode 100644 .agents/skills/react/references/memo-use-memo.md create mode 100644 .agents/skills/react/references/rcomp-composition.md create mode 100644 .agents/skills/react/references/rcomp-controlled-components.md create mode 100644 .agents/skills/react/references/rcomp-fragment-refs.md create mode 100644 .agents/skills/react/references/rcomp-key-reset.md create mode 100644 .agents/skills/react/references/rcomp-render-props.md create mode 100644 .agents/skills/react/references/rsc-avoid-client-only-libs.md create mode 100644 .agents/skills/react/references/rsc-composition-pattern.md create mode 100644 .agents/skills/react/references/rsc-context-provider.md create mode 100644 .agents/skills/react/references/rsc-data-fetching-server.md create mode 100644 .agents/skills/react/references/rsc-serializable-props.md create mode 100644 .agents/skills/react/references/rsc-server-client-boundary.md create mode 100644 .agents/skills/react/references/rsc-streaming.md create mode 100644 .agents/skills/react/references/rstate-context-optimization.md create mode 100644 .agents/skills/react/references/rstate-derived-values.md create mode 100644 .agents/skills/react/references/rstate-functional-updates.md create mode 100644 .agents/skills/react/references/rstate-lazy-initialization.md create mode 100644 .agents/skills/react/references/rstate-use-reducer.md create mode 100644 .agents/skills/shadcn/SKILL.md create mode 100644 .agents/skills/shadcn/references/ally-ensure-color-contrast.md create mode 100644 .agents/skills/shadcn/references/ally-maintain-focus-management.md create mode 100644 .agents/skills/shadcn/references/ally-preserve-aria-attributes.md create mode 100644 .agents/skills/shadcn/references/ally-preserve-keyboard-navigation.md create mode 100644 .agents/skills/shadcn/references/ally-provide-sr-only-labels.md create mode 100644 .agents/skills/shadcn/references/arch-current-cli-registry.md create mode 100644 .agents/skills/shadcn/references/arch-extend-variants-with-cva.md create mode 100644 .agents/skills/shadcn/references/arch-forward-refs-for-composable-components.md create mode 100644 .agents/skills/shadcn/references/arch-isolate-component-variants.md create mode 100644 .agents/skills/shadcn/references/arch-preserve-radix-primitive-structure.md create mode 100644 .agents/skills/shadcn/references/arch-unified-radix-package.md create mode 100644 .agents/skills/shadcn/references/arch-use-asChild-for-custom-triggers.md create mode 100644 .agents/skills/shadcn/references/arch-use-cn-for-class-merging.md create mode 100644 .agents/skills/shadcn/references/comp-combine-command-with-popover.md create mode 100644 .agents/skills/shadcn/references/comp-compose-with-compound-components.md create mode 100644 .agents/skills/shadcn/references/comp-create-reusable-form-fields.md create mode 100644 .agents/skills/shadcn/references/comp-nest-dialogs-correctly.md create mode 100644 .agents/skills/shadcn/references/comp-use-drawer-for-mobile-modals.md create mode 100644 .agents/skills/shadcn/references/comp-use-slot-pattern-for-flexibility.md create mode 100644 .agents/skills/shadcn/references/data-empty-states-with-guidance.md create mode 100644 .agents/skills/shadcn/references/data-paginate-server-side.md create mode 100644 .agents/skills/shadcn/references/data-use-skeleton-loading-states.md create mode 100644 .agents/skills/shadcn/references/data-use-tanstack-table-for-complex-tables.md create mode 100644 .agents/skills/shadcn/references/data-virtualize-large-lists.md create mode 100644 .agents/skills/shadcn/references/form-handle-async-validation.md create mode 100644 .agents/skills/shadcn/references/form-reset-form-state-correctly.md create mode 100644 .agents/skills/shadcn/references/form-show-validation-errors-correctly.md create mode 100644 .agents/skills/shadcn/references/form-use-react-hook-form-integration.md create mode 100644 .agents/skills/shadcn/references/form-use-zod-for-schema-validation.md create mode 100644 .agents/skills/shadcn/references/perf-avoid-unnecessary-rerenders-in-forms.md create mode 100644 .agents/skills/shadcn/references/perf-debounce-search-inputs.md create mode 100644 .agents/skills/shadcn/references/perf-lazy-load-heavy-components.md create mode 100644 .agents/skills/shadcn/references/perf-memoize-expensive-renders.md create mode 100644 .agents/skills/shadcn/references/perf-optimize-icon-imports.md create mode 100644 .agents/skills/shadcn/references/state-colocate-state-with-components.md create mode 100644 .agents/skills/shadcn/references/state-lift-state-to-appropriate-level.md create mode 100644 .agents/skills/shadcn/references/state-prefer-uncontrolled-for-simple-inputs.md create mode 100644 .agents/skills/shadcn/references/state-use-controlled-dialog-state.md create mode 100644 .agents/skills/shadcn/references/style-avoid-important-overrides.md create mode 100644 .agents/skills/shadcn/references/style-consistent-spacing-scale.md create mode 100644 .agents/skills/shadcn/references/style-dark-mode-support.md create mode 100644 .agents/skills/shadcn/references/style-responsive-design-patterns.md create mode 100644 .agents/skills/shadcn/references/style-use-css-variables-for-theming.md create mode 100644 .agents/skills/shadcn/references/style-use-tailwind-theme-extend.md create mode 100644 .agents/skills/tailwind/SKILL.md create mode 100644 .agents/skills/tailwind/references/anim-3d-transforms.md create mode 100644 .agents/skills/tailwind/references/anim-gpu-accelerated.md create mode 100644 .agents/skills/tailwind/references/anim-gradient-interpolation.md create mode 100644 .agents/skills/tailwind/references/anim-starting-style.md create mode 100644 .agents/skills/tailwind/references/build-cli-package.md create mode 100644 .agents/skills/tailwind/references/build-content-detection.md create mode 100644 .agents/skills/tailwind/references/build-css-import.md create mode 100644 .agents/skills/tailwind/references/build-node-version.md create mode 100644 .agents/skills/tailwind/references/build-postcss-simplify.md create mode 100644 .agents/skills/tailwind/references/build-vite-plugin.md create mode 100644 .agents/skills/tailwind/references/bundle-avoid-cdn-production.md create mode 100644 .agents/skills/tailwind/references/bundle-avoid-preprocessors.md create mode 100644 .agents/skills/tailwind/references/bundle-css-minification.md create mode 100644 .agents/skills/tailwind/references/bundle-remove-unused-plugins.md create mode 100644 .agents/skills/tailwind/references/bundle-split-critical-css.md create mode 100644 .agents/skills/tailwind/references/comp-avoid-apply-overuse.md create mode 100644 .agents/skills/tailwind/references/comp-container-customize.md create mode 100644 .agents/skills/tailwind/references/comp-reference-directive.md create mode 100644 .agents/skills/tailwind/references/comp-smart-sorting.md create mode 100644 .agents/skills/tailwind/references/comp-utility-file-scope.md create mode 100644 .agents/skills/tailwind/references/gen-avoid-theme-bloat.md create mode 100644 .agents/skills/tailwind/references/gen-css-first-config.md create mode 100644 .agents/skills/tailwind/references/gen-css-variable-syntax.md create mode 100644 .agents/skills/tailwind/references/gen-dynamic-utilities.md create mode 100644 .agents/skills/tailwind/references/gen-oklch-colors.md create mode 100644 .agents/skills/tailwind/references/gen-utility-directive.md create mode 100644 .agents/skills/tailwind/references/resp-container-queries.md create mode 100644 .agents/skills/tailwind/references/resp-custom-breakpoints.md create mode 100644 .agents/skills/tailwind/references/resp-hover-capability.md create mode 100644 .agents/skills/tailwind/references/resp-logical-properties.md create mode 100644 .agents/skills/tailwind/references/resp-mobile-first.md create mode 100644 .agents/skills/tailwind/references/theme-color-scheme.md create mode 100644 .agents/skills/tailwind/references/theme-dark-mode-class.md create mode 100644 .agents/skills/tailwind/references/theme-prefix-variables.md create mode 100644 .agents/skills/tailwind/references/theme-runtime-variables.md create mode 100644 .agents/skills/tailwind/references/theme-semantic-tokens.md create mode 100644 .agents/skills/tailwind/references/util-explicit-colors.md create mode 100644 .agents/skills/tailwind/references/util-gradient-via-none.md create mode 100644 .agents/skills/tailwind/references/util-important-modifier.md create mode 100644 .agents/skills/tailwind/references/util-opacity-modifier.md create mode 100644 .agents/skills/tailwind/references/util-renamed-utilities.md create mode 100644 .agents/skills/tailwind/references/util-variant-stacking.md create mode 100644 .agents/skills/tanstack-query/SKILL.md create mode 100644 .agents/skills/tanstack-query/references/cache-enabled-option.md create mode 100644 .agents/skills/tanstack-query/references/cache-global-defaults.md create mode 100644 .agents/skills/tanstack-query/references/cache-invalidation-precision.md create mode 100644 .agents/skills/tanstack-query/references/cache-placeholder-vs-initial.md create mode 100644 .agents/skills/tanstack-query/references/cache-refetch-triggers.md create mode 100644 .agents/skills/tanstack-query/references/cache-staletime-gctime.md create mode 100644 .agents/skills/tanstack-query/references/error-conditional-retry.md create mode 100644 .agents/skills/tanstack-query/references/error-display-patterns.md create mode 100644 .agents/skills/tanstack-query/references/error-global-handler.md create mode 100644 .agents/skills/tanstack-query/references/error-retry-config.md create mode 100644 .agents/skills/tanstack-query/references/error-throw-on-error.md create mode 100644 .agents/skills/tanstack-query/references/infinite-flatten-pages.md create mode 100644 .agents/skills/tanstack-query/references/infinite-loading-states.md create mode 100644 .agents/skills/tanstack-query/references/infinite-max-pages.md create mode 100644 .agents/skills/tanstack-query/references/infinite-refetch-behavior.md create mode 100644 .agents/skills/tanstack-query/references/mutation-avoid-parallel.md create mode 100644 .agents/skills/tanstack-query/references/mutation-cancel-queries.md create mode 100644 .agents/skills/tanstack-query/references/mutation-invalidate-onsettled.md create mode 100644 .agents/skills/tanstack-query/references/mutation-optimistic-updates.md create mode 100644 .agents/skills/tanstack-query/references/mutation-setquerydata.md create mode 100644 .agents/skills/tanstack-query/references/prefetch-avoid-waterfalls.md create mode 100644 .agents/skills/tanstack-query/references/prefetch-flatten-api.md create mode 100644 .agents/skills/tanstack-query/references/prefetch-in-queryfn.md create mode 100644 .agents/skills/tanstack-query/references/prefetch-infinite-query.md create mode 100644 .agents/skills/tanstack-query/references/prefetch-on-hover.md create mode 100644 .agents/skills/tanstack-query/references/prefetch-server-components.md create mode 100644 .agents/skills/tanstack-query/references/render-notify-props.md create mode 100644 .agents/skills/tanstack-query/references/render-select-derived.md create mode 100644 .agents/skills/tanstack-query/references/render-select-memoize.md create mode 100644 .agents/skills/tanstack-query/references/render-structural-sharing.md create mode 100644 .agents/skills/tanstack-query/references/render-tracked-props.md create mode 100644 .agents/skills/tanstack-query/references/suspense-boundaries-placement.md create mode 100644 .agents/skills/tanstack-query/references/suspense-error-boundaries.md create mode 100644 .agents/skills/tanstack-query/references/suspense-parallel-queries.md create mode 100644 .agents/skills/tanstack-query/references/suspense-use-suspense-hooks.md create mode 100644 .agents/skills/tanstack-query/references/tquery-always-arrays.md create mode 100644 .agents/skills/tanstack-query/references/tquery-colocate-keys.md create mode 100644 .agents/skills/tanstack-query/references/tquery-hierarchical-keys.md create mode 100644 .agents/skills/tanstack-query/references/tquery-key-factories.md create mode 100644 .agents/skills/tanstack-query/references/tquery-options-pattern.md create mode 100644 .agents/skills/tanstack-query/references/tquery-serializable-objects.md create mode 100644 .agents/skills/tdd/SKILL.md create mode 100644 .agents/skills/tdd/references/assert-custom-matchers.md create mode 100644 .agents/skills/tdd/references/assert-error-messages.md create mode 100644 .agents/skills/tdd/references/assert-no-assertions-antipattern.md create mode 100644 .agents/skills/tdd/references/assert-snapshot-testing.md create mode 100644 .agents/skills/tdd/references/assert-specific-assertions.md create mode 100644 .agents/skills/tdd/references/cycle-maintain-test-list.md create mode 100644 .agents/skills/tdd/references/cycle-minimal-code-to-pass.md create mode 100644 .agents/skills/tdd/references/cycle-refactor-after-green.md create mode 100644 .agents/skills/tdd/references/cycle-small-increments.md create mode 100644 .agents/skills/tdd/references/cycle-verify-test-fails-first.md create mode 100644 .agents/skills/tdd/references/cycle-write-test-first.md create mode 100644 .agents/skills/tdd/references/data-avoid-mystery-guests.md create mode 100644 .agents/skills/tdd/references/data-builder-pattern.md create mode 100644 .agents/skills/tdd/references/data-minimal-setup.md create mode 100644 .agents/skills/tdd/references/data-unique-identifiers.md create mode 100644 .agents/skills/tdd/references/data-use-factories.md create mode 100644 .agents/skills/tdd/references/design-aaa-pattern.md create mode 100644 .agents/skills/tdd/references/design-avoid-logic-in-tests.md create mode 100644 .agents/skills/tdd/references/design-descriptive-test-names.md create mode 100644 .agents/skills/tdd/references/design-one-assertion-per-test.md create mode 100644 .agents/skills/tdd/references/design-test-behavior-not-implementation.md create mode 100644 .agents/skills/tdd/references/design-test-edge-cases.md create mode 100644 .agents/skills/tdd/references/isolate-deterministic-tests.md create mode 100644 .agents/skills/tdd/references/isolate-mock-external-dependencies.md create mode 100644 .agents/skills/tdd/references/isolate-no-shared-state.md create mode 100644 .agents/skills/tdd/references/isolate-prefer-stubs-over-mocks.md create mode 100644 .agents/skills/tdd/references/isolate-use-dependency-injection.md create mode 100644 .agents/skills/tdd/references/org-file-structure.md create mode 100644 .agents/skills/tdd/references/org-group-by-behavior.md create mode 100644 .agents/skills/tdd/references/org-parameterized-tests.md create mode 100644 .agents/skills/tdd/references/org-setup-teardown.md create mode 100644 .agents/skills/tdd/references/org-test-utilities.md create mode 100644 .agents/skills/tdd/references/perf-avoid-network-calls.md create mode 100644 .agents/skills/tdd/references/perf-avoid-sleep.md create mode 100644 .agents/skills/tdd/references/perf-fast-unit-tests.md create mode 100644 .agents/skills/tdd/references/perf-fix-flaky-tests.md create mode 100644 .agents/skills/tdd/references/perf-parallelize-tests.md create mode 100644 .agents/skills/tdd/references/strat-coverage-targets.md create mode 100644 .agents/skills/tdd/references/strat-e2e-critical-paths.md create mode 100644 .agents/skills/tdd/references/strat-integration-boundaries.md create mode 100644 .agents/skills/tdd/references/strat-mutation-testing.md create mode 100644 .agents/skills/tdd/references/strat-test-pyramid.md create mode 100644 .agents/skills/typescript/SKILL.md create mode 100644 .agents/skills/typescript/references/advanced-branded-types.md create mode 100644 .agents/skills/typescript/references/advanced-satisfies-operator.md create mode 100644 .agents/skills/typescript/references/advanced-template-literal-types.md create mode 100644 .agents/skills/typescript/references/async-avoid-loop-await.md create mode 100644 .agents/skills/typescript/references/async-avoid-unnecessary-async.md create mode 100644 .agents/skills/typescript/references/async-defer-await.md create mode 100644 .agents/skills/typescript/references/async-explicit-return-types.md create mode 100644 .agents/skills/typescript/references/async-parallel-promises.md create mode 100644 .agents/skills/typescript/references/mem-avoid-closure-leaks.md create mode 100644 .agents/skills/typescript/references/mem-avoid-global-state.md create mode 100644 .agents/skills/typescript/references/mem-cleanup-event-listeners.md create mode 100644 .agents/skills/typescript/references/mem-clear-timers.md create mode 100644 .agents/skills/typescript/references/mem-use-weakmap-for-metadata.md create mode 100644 .agents/skills/typescript/references/module-avoid-barrel-imports.md create mode 100644 .agents/skills/typescript/references/module-avoid-circular-dependencies.md create mode 100644 .agents/skills/typescript/references/module-control-types-inclusion.md create mode 100644 .agents/skills/typescript/references/module-dynamic-imports.md create mode 100644 .agents/skills/typescript/references/module-use-type-imports.md create mode 100644 .agents/skills/typescript/references/runtime-avoid-object-spread-in-loops.md create mode 100644 .agents/skills/typescript/references/runtime-cache-property-access.md create mode 100644 .agents/skills/typescript/references/runtime-prefer-array-methods.md create mode 100644 .agents/skills/typescript/references/runtime-use-for-of-for-iteration.md create mode 100644 .agents/skills/typescript/references/runtime-use-set-for-lookups.md create mode 100644 .agents/skills/typescript/references/runtime-use-string-methods.md create mode 100644 .agents/skills/typescript/references/safety-assertion-functions.md create mode 100644 .agents/skills/typescript/references/safety-const-assertions.md create mode 100644 .agents/skills/typescript/references/safety-exhaustive-checks.md create mode 100644 .agents/skills/typescript/references/safety-prefer-unknown-over-any.md create mode 100644 .agents/skills/typescript/references/safety-strict-null-checks.md create mode 100644 .agents/skills/typescript/references/safety-use-type-guards.md create mode 100644 .agents/skills/typescript/references/tscfg-enable-incremental.md create mode 100644 .agents/skills/typescript/references/tscfg-exclude-properly.md create mode 100644 .agents/skills/typescript/references/tscfg-isolate-modules.md create mode 100644 .agents/skills/typescript/references/tscfg-project-references.md create mode 100644 .agents/skills/typescript/references/tscfg-skip-lib-check.md create mode 100644 .agents/skills/typescript/references/tscfg-strict-function-types.md create mode 100644 .agents/skills/typescript/references/tscfg-typescript-7.md create mode 100644 .agents/skills/typescript/references/type-avoid-deep-generics.md create mode 100644 .agents/skills/typescript/references/type-avoid-large-unions.md create mode 100644 .agents/skills/typescript/references/type-explicit-return-types.md create mode 100644 .agents/skills/typescript/references/type-extract-conditional-types.md create mode 100644 .agents/skills/typescript/references/type-interfaces-over-intersections.md create mode 100644 .agents/skills/typescript/references/type-limit-recursion-depth.md create mode 100644 .agents/skills/typescript/references/type-simplify-mapped-types.md create mode 100644 .agents/skills/ui-design/SKILL.md create mode 100644 .agents/skills/ui-design/references/access-alt-text.md create mode 100644 .agents/skills/ui-design/references/access-aria-labels.md create mode 100644 .agents/skills/ui-design/references/access-focus-indicators.md create mode 100644 .agents/skills/ui-design/references/access-heading-hierarchy.md create mode 100644 .agents/skills/ui-design/references/access-keyboard-navigation.md create mode 100644 .agents/skills/ui-design/references/access-semantic-html.md create mode 100644 .agents/skills/ui-design/references/access-target-size.md create mode 100644 .agents/skills/ui-design/references/anim-duration-easing.md create mode 100644 .agents/skills/ui-design/references/anim-gpu-properties.md create mode 100644 .agents/skills/ui-design/references/anim-reduced-motion.md create mode 100644 .agents/skills/ui-design/references/anim-will-change.md create mode 100644 .agents/skills/ui-design/references/color-contrast-ratio.md create mode 100644 .agents/skills/ui-design/references/color-dark-mode.md create mode 100644 .agents/skills/ui-design/references/color-not-only-indicator.md create mode 100644 .agents/skills/ui-design/references/color-semantic-palette.md create mode 100644 .agents/skills/ui-design/references/cwv-critical-css.md create mode 100644 .agents/skills/ui-design/references/cwv-improve-inp.md create mode 100644 .agents/skills/ui-design/references/cwv-lazy-load-offscreen.md create mode 100644 .agents/skills/ui-design/references/cwv-minimize-cls.md create mode 100644 .agents/skills/ui-design/references/cwv-optimize-lcp.md create mode 100644 .agents/skills/ui-design/references/cwv-responsive-images.md create mode 100644 .agents/skills/ui-design/references/form-autocomplete.md create mode 100644 .agents/skills/ui-design/references/form-error-messages.md create mode 100644 .agents/skills/ui-design/references/form-inline-validation.md create mode 100644 .agents/skills/ui-design/references/form-input-types.md create mode 100644 .agents/skills/ui-design/references/form-labels-above.md create mode 100644 .agents/skills/ui-design/references/layout-f-pattern.md create mode 100644 .agents/skills/ui-design/references/layout-grid-system.md create mode 100644 .agents/skills/ui-design/references/layout-proximity-grouping.md create mode 100644 .agents/skills/ui-design/references/layout-single-cta.md create mode 100644 .agents/skills/ui-design/references/layout-visual-hierarchy.md create mode 100644 .agents/skills/ui-design/references/layout-whitespace.md create mode 100644 .agents/skills/ui-design/references/resp-container-queries.md create mode 100644 .agents/skills/ui-design/references/resp-fluid-typography.md create mode 100644 .agents/skills/ui-design/references/resp-mobile-first.md create mode 100644 .agents/skills/ui-design/references/resp-touch-targets.md create mode 100644 .agents/skills/ui-design/references/resp-viewport-meta.md create mode 100644 .agents/skills/ui-design/references/typo-font-display.md create mode 100644 .agents/skills/ui-design/references/typo-line-height.md create mode 100644 .agents/skills/ui-design/references/typo-preload-fonts.md create mode 100644 .agents/skills/ui-design/references/typo-readable-line-length.md create mode 100644 .agents/skills/ui-design/references/typo-system-font-stack.md create mode 100644 .agents/skills/vercel-composition-patterns/SKILL.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/architecture-compound-components.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/react19-no-forwardref.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/state-context-interface.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/state-decouple-implementation.md create mode 100644 .agents/skills/vercel-composition-patterns/rules/state-lift-state.md create mode 100644 .agents/skills/vercel-react-best-practices/SKILL.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-init-once.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-api-routes.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-defer-await.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-dependencies.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-parallel.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-conditional.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-preload.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-event-listeners.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-cache-storage.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-early-exit.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-index-maps.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-length-check-first.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-activity.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-memo.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-transitions.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-auth-actions.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-cache-lru.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-cache-react.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-dedup-props.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-serialization.md create mode 100644 .agents/skills/vitest/SKILL.md create mode 100644 .agents/skills/vitest/references/assert-edge-cases.md create mode 100644 .agents/skills/vitest/references/assert-expect-assertions.md create mode 100644 .agents/skills/vitest/references/assert-one-assertion-concept.md create mode 100644 .agents/skills/vitest/references/assert-specific-matchers.md create mode 100644 .agents/skills/vitest/references/assert-toequal-vs-tobe.md create mode 100644 .agents/skills/vitest/references/async-act-wrapper.md create mode 100644 .agents/skills/vitest/references/async-await-assertions.md create mode 100644 .agents/skills/vitest/references/async-concurrent-expect.md create mode 100644 .agents/skills/vitest/references/async-error-handling.md create mode 100644 .agents/skills/vitest/references/async-fake-timers.md create mode 100644 .agents/skills/vitest/references/async-return-promises.md create mode 100644 .agents/skills/vitest/references/async-waitfor-polling.md create mode 100644 .agents/skills/vitest/references/env-browser-api-mocking.md create mode 100644 .agents/skills/vitest/references/env-globals-config.md create mode 100644 .agents/skills/vitest/references/env-per-file-override.md create mode 100644 .agents/skills/vitest/references/env-setup-files.md create mode 100644 .agents/skills/vitest/references/mock-avoid-overmocking.md create mode 100644 .agents/skills/vitest/references/mock-clear-between-tests.md create mode 100644 .agents/skills/vitest/references/mock-implementation-not-value.md create mode 100644 .agents/skills/vitest/references/mock-msw-network.md create mode 100644 .agents/skills/vitest/references/mock-spyon-vs-mock.md create mode 100644 .agents/skills/vitest/references/mock-type-safety.md create mode 100644 .agents/skills/vitest/references/mock-vi-mock-hoisting.md create mode 100644 .agents/skills/vitest/references/org-describe-nesting.md create mode 100644 .agents/skills/vitest/references/org-file-colocation.md create mode 100644 .agents/skills/vitest/references/org-test-naming.md create mode 100644 .agents/skills/vitest/references/org-test-skip-only.md create mode 100644 .agents/skills/vitest/references/perf-bail-fast-fail.md create mode 100644 .agents/skills/vitest/references/perf-bench-test-context.md create mode 100644 .agents/skills/vitest/references/perf-disable-isolation.md create mode 100644 .agents/skills/vitest/references/perf-happy-dom.md create mode 100644 .agents/skills/vitest/references/perf-pool-selection.md create mode 100644 .agents/skills/vitest/references/perf-run-mode-ci.md create mode 100644 .agents/skills/vitest/references/perf-sharding.md create mode 100644 .agents/skills/vitest/references/setup-avoid-shared-state.md create mode 100644 .agents/skills/vitest/references/setup-beforeall-expensive.md create mode 100644 .agents/skills/vitest/references/setup-beforeeach-cleanup.md create mode 100644 .agents/skills/vitest/references/setup-reset-modules.md create mode 100644 .agents/skills/vitest/references/setup-restore-mocks.md create mode 100644 .agents/skills/vitest/references/setup-test-factories.md create mode 100644 .agents/skills/vitest/references/setup-vitest5-migration.md create mode 100644 .agents/skills/vitest/references/snap-avoid-large.md create mode 100644 .agents/skills/vitest/references/snap-describe-intent.md create mode 100644 .agents/skills/vitest/references/snap-inline-over-file.md create mode 100644 .agents/skills/vitest/references/snap-review-updates.md create mode 100644 .agents/skills/vitest/references/snap-stable-serialization.md create mode 100644 .agents/skills/web-design-guidelines/SKILL.md create mode 100644 .agents/skills/zod/SKILL.md create mode 100644 .agents/skills/zod/references/compose-intersection.md create mode 100644 .agents/skills/zod/references/compose-lazy-recursive.md create mode 100644 .agents/skills/zod/references/compose-pipe.md create mode 100644 .agents/skills/zod/references/compose-preprocess.md create mode 100644 .agents/skills/zod/references/compose-shared-schemas.md create mode 100644 .agents/skills/zod/references/error-avoid-throwing-in-refine.md create mode 100644 .agents/skills/zod/references/error-custom-messages.md create mode 100644 .agents/skills/zod/references/error-i18n.md create mode 100644 .agents/skills/zod/references/error-path-for-nested.md create mode 100644 .agents/skills/zod/references/error-use-flatten.md create mode 100644 .agents/skills/zod/references/object-discriminated-unions.md create mode 100644 .agents/skills/zod/references/object-extend-for-composition.md create mode 100644 .agents/skills/zod/references/object-optional-vs-nullable.md create mode 100644 .agents/skills/zod/references/object-partial-for-updates.md create mode 100644 .agents/skills/zod/references/object-pick-omit.md create mode 100644 .agents/skills/zod/references/object-strict-vs-strip.md create mode 100644 .agents/skills/zod/references/parse-async-for-async-refinements.md create mode 100644 .agents/skills/zod/references/parse-avoid-double-validation.md create mode 100644 .agents/skills/zod/references/parse-handle-all-issues.md create mode 100644 .agents/skills/zod/references/parse-never-trust-json.md create mode 100644 .agents/skills/zod/references/parse-use-safeparse.md create mode 100644 .agents/skills/zod/references/parse-validate-early.md create mode 100644 .agents/skills/zod/references/parse-validate-for-boolean-checks.md create mode 100644 .agents/skills/zod/references/perf-arrays.md create mode 100644 .agents/skills/zod/references/perf-avoid-dynamic-creation.md create mode 100644 .agents/skills/zod/references/perf-cache-schemas.md create mode 100644 .agents/skills/zod/references/perf-compile-schemas.md create mode 100644 .agents/skills/zod/references/perf-lazy-loading.md create mode 100644 .agents/skills/zod/references/perf-zod-mini.md create mode 100644 .agents/skills/zod/references/refine-add-path.md create mode 100644 .agents/skills/zod/references/refine-catch.md create mode 100644 .agents/skills/zod/references/refine-defaults.md create mode 100644 .agents/skills/zod/references/refine-transform-coerce.md create mode 100644 .agents/skills/zod/references/refine-use-codec.md create mode 100644 .agents/skills/zod/references/refine-vs-superrefine.md create mode 100644 .agents/skills/zod/references/schema-avoid-optional-abuse.md create mode 100644 .agents/skills/zod/references/schema-coercion-for-form-data.md create mode 100644 .agents/skills/zod/references/schema-string-validations.md create mode 100644 .agents/skills/zod/references/schema-use-enums.md create mode 100644 .agents/skills/zod/references/schema-use-primitives-correctly.md create mode 100644 .agents/skills/zod/references/schema-use-unknown-not-any.md create mode 100644 .agents/skills/zod/references/type-branded-types.md create mode 100644 .agents/skills/zod/references/type-enable-strict-mode.md create mode 100644 .agents/skills/zod/references/type-export-schemas-and-types.md create mode 100644 .agents/skills/zod/references/type-input-vs-output.md create mode 100644 .agents/skills/zod/references/type-use-z-infer.md create mode 100644 .claude/skills/feature-arch/SKILL.md create mode 100644 .claude/skills/feature-arch/references/bound-event-based-communication.md create mode 100644 .claude/skills/feature-arch/references/bound-feature-isolation.md create mode 100644 .claude/skills/feature-arch/references/bound-feature-scoped-routing.md create mode 100644 .claude/skills/feature-arch/references/bound-feature-size.md create mode 100644 .claude/skills/feature-arch/references/bound-interface-contracts.md create mode 100644 .claude/skills/feature-arch/references/bound-minimize-shared-state.md create mode 100644 .claude/skills/feature-arch/references/fcomp-colocate-styles.md create mode 100644 .claude/skills/feature-arch/references/fcomp-composition-over-props.md create mode 100644 .claude/skills/feature-arch/references/fcomp-container-presentational.md create mode 100644 .claude/skills/feature-arch/references/fcomp-error-boundaries.md create mode 100644 .claude/skills/feature-arch/references/fcomp-props-as-data-boundary.md create mode 100644 .claude/skills/feature-arch/references/fcomp-single-responsibility.md create mode 100644 .claude/skills/feature-arch/references/fquery-avoid-n-plus-one.md create mode 100644 .claude/skills/feature-arch/references/fquery-colocate-with-feature.md create mode 100644 .claude/skills/feature-arch/references/fquery-feature-scoped-keys.md create mode 100644 .claude/skills/feature-arch/references/fquery-parallel-fetching.md create mode 100644 .claude/skills/feature-arch/references/fquery-server-component-fetching.md create mode 100644 .claude/skills/feature-arch/references/fquery-single-responsibility.md create mode 100644 .claude/skills/feature-arch/references/fstate-context-sparingly.md create mode 100644 .claude/skills/feature-arch/references/fstate-feature-scoped-stores.md create mode 100644 .claude/skills/feature-arch/references/fstate-lift-minimally.md create mode 100644 .claude/skills/feature-arch/references/fstate-reset-on-unmount.md create mode 100644 .claude/skills/feature-arch/references/fstate-server-state-separation.md create mode 100644 .claude/skills/feature-arch/references/import-avoid-barrel-files.md create mode 100644 .claude/skills/feature-arch/references/import-no-cross-feature.md create mode 100644 .claude/skills/feature-arch/references/import-path-aliases.md create mode 100644 .claude/skills/feature-arch/references/import-public-api.md create mode 100644 .claude/skills/feature-arch/references/import-type-only.md create mode 100644 .claude/skills/feature-arch/references/import-unidirectional-flow.md create mode 100644 .claude/skills/feature-arch/references/name-descriptive-exports.md create mode 100644 .claude/skills/feature-arch/references/name-feature-naming.md create mode 100644 .claude/skills/feature-arch/references/name-file-conventions.md create mode 100644 .claude/skills/feature-arch/references/struct-app-layer.md create mode 100644 .claude/skills/feature-arch/references/struct-feature-folders.md create mode 100644 .claude/skills/feature-arch/references/struct-feature-self-contained.md create mode 100644 .claude/skills/feature-arch/references/struct-flat-hierarchy.md create mode 100644 .claude/skills/feature-arch/references/struct-optional-segments.md create mode 100644 .claude/skills/feature-arch/references/struct-shared-layer.md create mode 100644 .claude/skills/feature-arch/references/test-colocate-with-feature.md create mode 100644 .claude/skills/feature-arch/references/test-feature-isolation.md create mode 100644 .claude/skills/feature-arch/references/test-integration-at-app-layer.md create mode 100644 .claude/skills/feature-arch/references/test-shared-utilities.md create mode 100644 .claude/skills/msw/SKILL.md create mode 100644 .claude/skills/msw/references/advanced-bypass-requests.md create mode 100644 .claude/skills/msw/references/advanced-cookies-auth.md create mode 100644 .claude/skills/msw/references/advanced-dynamic-scenarios.md create mode 100644 .claude/skills/msw/references/advanced-file-uploads.md create mode 100644 .claude/skills/msw/references/advanced-playwright-integration.md create mode 100644 .claude/skills/msw/references/advanced-vitest-browser.md create mode 100644 .claude/skills/msw/references/advanced-websocket-mocking.md create mode 100644 .claude/skills/msw/references/debug-common-issues.md create mode 100644 .claude/skills/msw/references/debug-lifecycle-events.md create mode 100644 .claude/skills/msw/references/debug-request-logging.md create mode 100644 .claude/skills/msw/references/debug-verify-interception.md create mode 100644 .claude/skills/msw/references/graphql-batched-queries.md create mode 100644 .claude/skills/msw/references/graphql-error-responses.md create mode 100644 .claude/skills/msw/references/graphql-operation-handlers.md create mode 100644 .claude/skills/msw/references/graphql-schema-first.md create mode 100644 .claude/skills/msw/references/graphql-variables-access.md create mode 100644 .claude/skills/msw/references/handler-absolute-urls.md create mode 100644 .claude/skills/msw/references/handler-domain-grouping.md create mode 100644 .claude/skills/msw/references/handler-happy-path-first.md create mode 100644 .claude/skills/msw/references/handler-request-body-parsing.md create mode 100644 .claude/skills/msw/references/handler-resolver-argument.md create mode 100644 .claude/skills/msw/references/handler-reusability-environments.md create mode 100644 .claude/skills/msw/references/handler-shared-resolvers.md create mode 100644 .claude/skills/msw/references/handler-v2-response-syntax.md create mode 100644 .claude/skills/msw/references/match-custom-predicate.md create mode 100644 .claude/skills/msw/references/match-handler-order.md create mode 100644 .claude/skills/msw/references/match-http-methods.md create mode 100644 .claude/skills/msw/references/match-query-params.md create mode 100644 .claude/skills/msw/references/match-url-patterns.md create mode 100644 .claude/skills/msw/references/response-custom-headers.md create mode 100644 .claude/skills/msw/references/response-delay-realistic.md create mode 100644 .claude/skills/msw/references/response-error-simulation.md create mode 100644 .claude/skills/msw/references/response-http-response-helpers.md create mode 100644 .claude/skills/msw/references/response-one-time-handlers.md create mode 100644 .claude/skills/msw/references/response-streaming.md create mode 100644 .claude/skills/msw/references/setup-lifecycle-hooks.md create mode 100644 .claude/skills/msw/references/setup-node-version.md create mode 100644 .claude/skills/msw/references/setup-server-node-entrypoint.md create mode 100644 .claude/skills/msw/references/setup-typescript-config.md create mode 100644 .claude/skills/msw/references/setup-unhandled-requests.md create mode 100644 .claude/skills/msw/references/setup-worker-script-commit.md create mode 100644 .claude/skills/msw/references/test-async-utilities.md create mode 100644 .claude/skills/msw/references/test-avoid-request-assertions.md create mode 100644 .claude/skills/msw/references/test-clear-request-cache.md create mode 100644 .claude/skills/msw/references/test-concurrent-boundary.md create mode 100644 .claude/skills/msw/references/test-fake-timers-config.md create mode 100644 .claude/skills/msw/references/test-jsdom-environment.md create mode 100644 .claude/skills/msw/references/test-reset-handlers.md create mode 100644 .claude/skills/nextjs/SKILL.md create mode 100644 .claude/skills/nextjs/references/action-error-handling.md create mode 100644 .claude/skills/nextjs/references/action-optimistic-updates.md create mode 100644 .claude/skills/nextjs/references/action-pending-states.md create mode 100644 .claude/skills/nextjs/references/action-revalidation.md create mode 100644 .claude/skills/nextjs/references/action-server-action-forms.md create mode 100644 .claude/skills/nextjs/references/build-barrel-files.md create mode 100644 .claude/skills/nextjs/references/build-dynamic-imports.md create mode 100644 .claude/skills/nextjs/references/build-external-packages.md create mode 100644 .claude/skills/nextjs/references/build-optimize-package-imports.md create mode 100644 .claude/skills/nextjs/references/build-turbopack-config.md create mode 100644 .claude/skills/nextjs/references/cache-fetch-options.md create mode 100644 .claude/skills/nextjs/references/cache-react-cache.md create mode 100644 .claude/skills/nextjs/references/cache-revalidate-path.md create mode 100644 .claude/skills/nextjs/references/cache-revalidate-tag.md create mode 100644 .claude/skills/nextjs/references/cache-segment-config.md create mode 100644 .claude/skills/nextjs/references/cache-use-cache-directive.md create mode 100644 .claude/skills/nextjs/references/client-children-pattern.md create mode 100644 .claude/skills/nextjs/references/client-hydration-mismatch.md create mode 100644 .claude/skills/nextjs/references/client-third-party-scripts.md create mode 100644 .claude/skills/nextjs/references/client-use-client-boundary.md create mode 100644 .claude/skills/nextjs/references/meta-generate-metadata.md create mode 100644 .claude/skills/nextjs/references/meta-opengraph-images.md create mode 100644 .claude/skills/nextjs/references/meta-robots.md create mode 100644 .claude/skills/nextjs/references/meta-sitemap.md create mode 100644 .claude/skills/nextjs/references/route-instant-navigations.md create mode 100644 .claude/skills/nextjs/references/route-intercepting-routes.md create mode 100644 .claude/skills/nextjs/references/route-not-found.md create mode 100644 .claude/skills/nextjs/references/route-parallel-routes.md create mode 100644 .claude/skills/nextjs/references/route-partial-prefetching.md create mode 100644 .claude/skills/nextjs/references/route-prefetching.md create mode 100644 .claude/skills/nextjs/references/route-proxy-ts.md create mode 100644 .claude/skills/nextjs/references/server-avoid-client-fetching.md create mode 100644 .claude/skills/nextjs/references/server-component-streaming.md create mode 100644 .claude/skills/nextjs/references/server-data-colocation.md create mode 100644 .claude/skills/nextjs/references/server-error-handling.md create mode 100644 .claude/skills/nextjs/references/server-parallel-fetching.md create mode 100644 .claude/skills/nextjs/references/server-preload-pattern.md create mode 100644 .claude/skills/nextjs/references/stream-error-tsx.md create mode 100644 .claude/skills/nextjs/references/stream-loading-tsx.md create mode 100644 .claude/skills/nextjs/references/stream-nested-suspense.md create mode 100644 .claude/skills/nextjs/references/stream-skeleton-matching.md create mode 100644 .claude/skills/nextjs/references/stream-suspense-boundaries.md create mode 100644 .claude/skills/nuqs/SKILL.md create mode 100644 .claude/skills/nuqs/references/advanced-custom-parsers.md create mode 100644 .claude/skills/nuqs/references/advanced-eq-function.md create mode 100644 .claude/skills/nuqs/references/advanced-framework-adapters.md create mode 100644 .claude/skills/nuqs/references/advanced-url-keys.md create mode 100644 .claude/skills/nuqs/references/debug-common-errors.md create mode 100644 .claude/skills/nuqs/references/debug-enable-logging.md create mode 100644 .claude/skills/nuqs/references/debug-testing.md create mode 100644 .claude/skills/nuqs/references/history-back-sync.md create mode 100644 .claude/skills/nuqs/references/history-push-navigation.md create mode 100644 .claude/skills/nuqs/references/history-replace-ephemeral.md create mode 100644 .claude/skills/nuqs/references/history-scroll-behavior.md create mode 100644 .claude/skills/nuqs/references/parser-array-format.md create mode 100644 .claude/skills/nuqs/references/parser-date-format.md create mode 100644 .claude/skills/nuqs/references/parser-enum-validation.md create mode 100644 .claude/skills/nuqs/references/parser-hex-colors.md create mode 100644 .claude/skills/nuqs/references/parser-index-offset.md create mode 100644 .claude/skills/nuqs/references/parser-json-validation.md create mode 100644 .claude/skills/nuqs/references/parser-use-typed-parsers.md create mode 100644 .claude/skills/nuqs/references/parser-with-default.md create mode 100644 .claude/skills/nuqs/references/perf-avoid-rerender.md create mode 100644 .claude/skills/nuqs/references/perf-clear-on-default.md create mode 100644 .claude/skills/nuqs/references/perf-debounce-search.md create mode 100644 .claude/skills/nuqs/references/perf-serialize-utility.md create mode 100644 .claude/skills/nuqs/references/perf-throttle-updates.md create mode 100644 .claude/skills/nuqs/references/server-next15-async.md create mode 100644 .claude/skills/nuqs/references/server-parse-before-get.md create mode 100644 .claude/skills/nuqs/references/server-search-params-cache.md create mode 100644 .claude/skills/nuqs/references/server-shallow-false.md create mode 100644 .claude/skills/nuqs/references/server-share-parsers.md create mode 100644 .claude/skills/nuqs/references/server-use-transition.md create mode 100644 .claude/skills/nuqs/references/setup-import-server.md create mode 100644 .claude/skills/nuqs/references/setup-nextjs-version.md create mode 100644 .claude/skills/nuqs/references/setup-nuqs-adapter.md create mode 100644 .claude/skills/nuqs/references/setup-shared-parsers.md create mode 100644 .claude/skills/nuqs/references/setup-use-client.md create mode 100644 .claude/skills/nuqs/references/state-avoid-derived.md create mode 100644 .claude/skills/nuqs/references/state-clear-with-null.md create mode 100644 .claude/skills/nuqs/references/state-controlled-inputs.md create mode 100644 .claude/skills/nuqs/references/state-functional-updates.md create mode 100644 .claude/skills/nuqs/references/state-options-inheritance.md create mode 100644 .claude/skills/nuqs/references/state-setter-return.md create mode 100644 .claude/skills/nuqs/references/state-use-query-states.md create mode 100644 .claude/skills/playwright/SKILL.md create mode 100644 .claude/skills/playwright/references/arch-cleanup-state.md create mode 100644 .claude/skills/playwright/references/arch-fixtures.md create mode 100644 .claude/skills/playwright/references/arch-page-object-model.md create mode 100644 .claude/skills/playwright/references/arch-parallel-execution.md create mode 100644 .claude/skills/playwright/references/arch-test-isolation.md create mode 100644 .claude/skills/playwright/references/arch-test-production.md create mode 100644 .claude/skills/playwright/references/assert-aria-snapshots.md create mode 100644 .claude/skills/playwright/references/auth-api-login.md create mode 100644 .claude/skills/playwright/references/auth-multiple-roles.md create mode 100644 .claude/skills/playwright/references/auth-parallel-workers.md create mode 100644 .claude/skills/playwright/references/auth-session-storage.md create mode 100644 .claude/skills/playwright/references/auth-storage-state.md create mode 100644 .claude/skills/playwright/references/debug-ci-reporters.md create mode 100644 .claude/skills/playwright/references/debug-inspector.md create mode 100644 .claude/skills/playwright/references/debug-screenshots-videos.md create mode 100644 .claude/skills/playwright/references/debug-trace-viewer.md create mode 100644 .claude/skills/playwright/references/loc-avoid-xpath.md create mode 100644 .claude/skills/playwright/references/loc-chained-locators.md create mode 100644 .claude/skills/playwright/references/loc-data-testid.md create mode 100644 .claude/skills/playwright/references/loc-frame-locator.md create mode 100644 .claude/skills/playwright/references/loc-label-selectors.md create mode 100644 .claude/skills/playwright/references/loc-placeholder-selector.md create mode 100644 .claude/skills/playwright/references/loc-role-selectors.md create mode 100644 .claude/skills/playwright/references/loc-text-selectors.md create mode 100644 .claude/skills/playwright/references/mock-abort-requests.md create mode 100644 .claude/skills/playwright/references/mock-api-responses.md create mode 100644 .claude/skills/playwright/references/mock-har-files.md create mode 100644 .claude/skills/playwright/references/mock-intercept-modify.md create mode 100644 .claude/skills/playwright/references/mock-network-conditions.md create mode 100644 .claude/skills/playwright/references/next-app-router-navigation.md create mode 100644 .claude/skills/playwright/references/next-baseurl-config.md create mode 100644 .claude/skills/playwright/references/next-server-actions.md create mode 100644 .claude/skills/playwright/references/next-server-components.md create mode 100644 .claude/skills/playwright/references/next-wait-hydration.md create mode 100644 .claude/skills/playwright/references/perf-browser-selection.md create mode 100644 .claude/skills/playwright/references/perf-headless-ci.md create mode 100644 .claude/skills/playwright/references/perf-retries.md create mode 100644 .claude/skills/playwright/references/perf-reuse-server.md create mode 100644 .claude/skills/playwright/references/perf-sharding.md create mode 100644 .claude/skills/playwright/references/wait-action-retries.md create mode 100644 .claude/skills/playwright/references/wait-avoid-hard-waits.md create mode 100644 .claude/skills/playwright/references/wait-custom-timeout.md create mode 100644 .claude/skills/playwright/references/wait-network-idle.md create mode 100644 .claude/skills/playwright/references/wait-soft-assertions.md create mode 100644 .claude/skills/playwright/references/wait-web-first-assertions.md create mode 100644 .claude/skills/react-hook-form/SKILL.md create mode 100644 .claude/skills/react-hook-form/references/adv-devtools-performance.md create mode 100644 .claude/skills/react-hook-form/references/adv-formprovider-memo.md create mode 100644 .claude/skills/react-hook-form/references/adv-opaque-types.md create mode 100644 .claude/skills/react-hook-form/references/adv-testing-wrapper.md create mode 100644 .claude/skills/react-hook-form/references/array-complete-default-objects.md create mode 100644 .claude/skills/react-hook-form/references/array-separate-crud-operations.md create mode 100644 .claude/skills/react-hook-form/references/array-unique-fieldarray-per-name.md create mode 100644 .claude/skills/react-hook-form/references/array-use-field-id-as-key.md create mode 100644 .claude/skills/react-hook-form/references/array-virtualization-formprovider.md create mode 100644 .claude/skills/react-hook-form/references/ctrl-avoid-double-registration.md create mode 100644 .claude/skills/react-hook-form/references/ctrl-controller-field-props.md create mode 100644 .claude/skills/react-hook-form/references/ctrl-local-state-combination.md create mode 100644 .claude/skills/react-hook-form/references/ctrl-single-usecontroller-per-component.md create mode 100644 .claude/skills/react-hook-form/references/ctrl-usecontroller-isolation.md create mode 100644 .claude/skills/react-hook-form/references/formcfg-async-default-values.md create mode 100644 .claude/skills/react-hook-form/references/formcfg-default-values.md create mode 100644 .claude/skills/react-hook-form/references/formcfg-revalidate-mode.md create mode 100644 .claude/skills/react-hook-form/references/formcfg-should-unregister.md create mode 100644 .claude/skills/react-hook-form/references/formcfg-useeffect-dependency.md create mode 100644 .claude/skills/react-hook-form/references/formcfg-validation-mode.md create mode 100644 .claude/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md create mode 100644 .claude/skills/react-hook-form/references/formstate-destructure-formstate.md create mode 100644 .claude/skills/react-hook-form/references/formstate-getfieldstate-for-single-field.md create mode 100644 .claude/skills/react-hook-form/references/formstate-subscribe-to-specific-fields.md create mode 100644 .claude/skills/react-hook-form/references/formstate-useformstate-isolation.md create mode 100644 .claude/skills/react-hook-form/references/integ-mui-controller-pattern.md create mode 100644 .claude/skills/react-hook-form/references/integ-shadcn-form-import.md create mode 100644 .claude/skills/react-hook-form/references/integ-shadcn-select-wiring.md create mode 100644 .claude/skills/react-hook-form/references/integ-typed-submit-server-action.md create mode 100644 .claude/skills/react-hook-form/references/integ-value-transform.md create mode 100644 .claude/skills/react-hook-form/references/sub-avoid-watch-in-render.md create mode 100644 .claude/skills/react-hook-form/references/sub-deep-subscription.md create mode 100644 .claude/skills/react-hook-form/references/sub-useformcontext-sparingly.md create mode 100644 .claude/skills/react-hook-form/references/sub-usewatch-default-value.md create mode 100644 .claude/skills/react-hook-form/references/sub-usewatch-over-watch.md create mode 100644 .claude/skills/react-hook-form/references/sub-usewatch-with-getvalues.md create mode 100644 .claude/skills/react-hook-form/references/sub-watch-specific-fields.md create mode 100644 .claude/skills/react-hook-form/references/valid-delay-error.md create mode 100644 .claude/skills/react-hook-form/references/valid-dynamic-schema-factory.md create mode 100644 .claude/skills/react-hook-form/references/valid-error-message-strategy.md create mode 100644 .claude/skills/react-hook-form/references/valid-form-level-validate.md create mode 100644 .claude/skills/react-hook-form/references/valid-inline-vs-resolver.md create mode 100644 .claude/skills/react-hook-form/references/valid-native-validation.md create mode 100644 .claude/skills/react-hook-form/references/valid-resolver-caching.md create mode 100644 .claude/skills/react-hook-form/references/valid-trigger-should-touch.md create mode 100644 .claude/skills/react/SKILL.md create mode 100644 .claude/skills/react/references/_sections.md create mode 100644 .claude/skills/react/references/conc-automatic-batching.md create mode 100644 .claude/skills/react/references/conc-concurrent-safe.md create mode 100644 .claude/skills/react/references/conc-suspense-fallback.md create mode 100644 .claude/skills/react/references/conc-use-deferred-value.md create mode 100644 .claude/skills/react/references/conc-use-transition.md create mode 100644 .claude/skills/react/references/conc-view-transitions.md create mode 100644 .claude/skills/react/references/data-cache-deduplication.md create mode 100644 .claude/skills/react/references/data-error-boundaries.md create mode 100644 .claude/skills/react/references/data-parallel-fetching.md create mode 100644 .claude/skills/react/references/data-suspense-data-fetching.md create mode 100644 .claude/skills/react/references/data-use-hook.md create mode 100644 .claude/skills/react/references/effect-avoid-unnecessary.md create mode 100644 .claude/skills/react/references/effect-cleanup.md create mode 100644 .claude/skills/react/references/effect-object-dependencies.md create mode 100644 .claude/skills/react/references/effect-use-browser-only.md create mode 100644 .claude/skills/react/references/effect-use-effect-event.md create mode 100644 .claude/skills/react/references/effect-use-sync-external-store.md create mode 100644 .claude/skills/react/references/form-actions.md create mode 100644 .claude/skills/react/references/form-use-action-state.md create mode 100644 .claude/skills/react/references/form-use-form-status.md create mode 100644 .claude/skills/react/references/form-use-optimistic.md create mode 100644 .claude/skills/react/references/form-validation.md create mode 100644 .claude/skills/react/references/memo-avoid-premature.md create mode 100644 .claude/skills/react/references/memo-compiler.md create mode 100644 .claude/skills/react/references/memo-react-memo.md create mode 100644 .claude/skills/react/references/memo-use-callback.md create mode 100644 .claude/skills/react/references/memo-use-memo.md create mode 100644 .claude/skills/react/references/rcomp-composition.md create mode 100644 .claude/skills/react/references/rcomp-controlled-components.md create mode 100644 .claude/skills/react/references/rcomp-fragment-refs.md create mode 100644 .claude/skills/react/references/rcomp-key-reset.md create mode 100644 .claude/skills/react/references/rcomp-render-props.md create mode 100644 .claude/skills/react/references/rsc-avoid-client-only-libs.md create mode 100644 .claude/skills/react/references/rsc-composition-pattern.md create mode 100644 .claude/skills/react/references/rsc-context-provider.md create mode 100644 .claude/skills/react/references/rsc-data-fetching-server.md create mode 100644 .claude/skills/react/references/rsc-serializable-props.md create mode 100644 .claude/skills/react/references/rsc-server-client-boundary.md create mode 100644 .claude/skills/react/references/rsc-streaming.md create mode 100644 .claude/skills/react/references/rstate-context-optimization.md create mode 100644 .claude/skills/react/references/rstate-derived-values.md create mode 100644 .claude/skills/react/references/rstate-functional-updates.md create mode 100644 .claude/skills/react/references/rstate-lazy-initialization.md create mode 100644 .claude/skills/react/references/rstate-use-reducer.md create mode 100644 .claude/skills/shadcn/SKILL.md create mode 100644 .claude/skills/shadcn/references/ally-ensure-color-contrast.md create mode 100644 .claude/skills/shadcn/references/ally-maintain-focus-management.md create mode 100644 .claude/skills/shadcn/references/ally-preserve-aria-attributes.md create mode 100644 .claude/skills/shadcn/references/ally-preserve-keyboard-navigation.md create mode 100644 .claude/skills/shadcn/references/ally-provide-sr-only-labels.md create mode 100644 .claude/skills/shadcn/references/arch-current-cli-registry.md create mode 100644 .claude/skills/shadcn/references/arch-extend-variants-with-cva.md create mode 100644 .claude/skills/shadcn/references/arch-forward-refs-for-composable-components.md create mode 100644 .claude/skills/shadcn/references/arch-isolate-component-variants.md create mode 100644 .claude/skills/shadcn/references/arch-preserve-radix-primitive-structure.md create mode 100644 .claude/skills/shadcn/references/arch-unified-radix-package.md create mode 100644 .claude/skills/shadcn/references/arch-use-asChild-for-custom-triggers.md create mode 100644 .claude/skills/shadcn/references/arch-use-cn-for-class-merging.md create mode 100644 .claude/skills/shadcn/references/comp-combine-command-with-popover.md create mode 100644 .claude/skills/shadcn/references/comp-compose-with-compound-components.md create mode 100644 .claude/skills/shadcn/references/comp-create-reusable-form-fields.md create mode 100644 .claude/skills/shadcn/references/comp-nest-dialogs-correctly.md create mode 100644 .claude/skills/shadcn/references/comp-use-drawer-for-mobile-modals.md create mode 100644 .claude/skills/shadcn/references/comp-use-slot-pattern-for-flexibility.md create mode 100644 .claude/skills/shadcn/references/data-empty-states-with-guidance.md create mode 100644 .claude/skills/shadcn/references/data-paginate-server-side.md create mode 100644 .claude/skills/shadcn/references/data-use-skeleton-loading-states.md create mode 100644 .claude/skills/shadcn/references/data-use-tanstack-table-for-complex-tables.md create mode 100644 .claude/skills/shadcn/references/data-virtualize-large-lists.md create mode 100644 .claude/skills/shadcn/references/form-handle-async-validation.md create mode 100644 .claude/skills/shadcn/references/form-reset-form-state-correctly.md create mode 100644 .claude/skills/shadcn/references/form-show-validation-errors-correctly.md create mode 100644 .claude/skills/shadcn/references/form-use-react-hook-form-integration.md create mode 100644 .claude/skills/shadcn/references/form-use-zod-for-schema-validation.md create mode 100644 .claude/skills/shadcn/references/perf-avoid-unnecessary-rerenders-in-forms.md create mode 100644 .claude/skills/shadcn/references/perf-debounce-search-inputs.md create mode 100644 .claude/skills/shadcn/references/perf-lazy-load-heavy-components.md create mode 100644 .claude/skills/shadcn/references/perf-memoize-expensive-renders.md create mode 100644 .claude/skills/shadcn/references/perf-optimize-icon-imports.md create mode 100644 .claude/skills/shadcn/references/state-colocate-state-with-components.md create mode 100644 .claude/skills/shadcn/references/state-lift-state-to-appropriate-level.md create mode 100644 .claude/skills/shadcn/references/state-prefer-uncontrolled-for-simple-inputs.md create mode 100644 .claude/skills/shadcn/references/state-use-controlled-dialog-state.md create mode 100644 .claude/skills/shadcn/references/style-avoid-important-overrides.md create mode 100644 .claude/skills/shadcn/references/style-consistent-spacing-scale.md create mode 100644 .claude/skills/shadcn/references/style-dark-mode-support.md create mode 100644 .claude/skills/shadcn/references/style-responsive-design-patterns.md create mode 100644 .claude/skills/shadcn/references/style-use-css-variables-for-theming.md create mode 100644 .claude/skills/shadcn/references/style-use-tailwind-theme-extend.md create mode 100644 .claude/skills/tailwind/SKILL.md create mode 100644 .claude/skills/tailwind/references/anim-3d-transforms.md create mode 100644 .claude/skills/tailwind/references/anim-gpu-accelerated.md create mode 100644 .claude/skills/tailwind/references/anim-gradient-interpolation.md create mode 100644 .claude/skills/tailwind/references/anim-starting-style.md create mode 100644 .claude/skills/tailwind/references/build-cli-package.md create mode 100644 .claude/skills/tailwind/references/build-content-detection.md create mode 100644 .claude/skills/tailwind/references/build-css-import.md create mode 100644 .claude/skills/tailwind/references/build-node-version.md create mode 100644 .claude/skills/tailwind/references/build-postcss-simplify.md create mode 100644 .claude/skills/tailwind/references/build-vite-plugin.md create mode 100644 .claude/skills/tailwind/references/bundle-avoid-cdn-production.md create mode 100644 .claude/skills/tailwind/references/bundle-avoid-preprocessors.md create mode 100644 .claude/skills/tailwind/references/bundle-css-minification.md create mode 100644 .claude/skills/tailwind/references/bundle-remove-unused-plugins.md create mode 100644 .claude/skills/tailwind/references/bundle-split-critical-css.md create mode 100644 .claude/skills/tailwind/references/comp-avoid-apply-overuse.md create mode 100644 .claude/skills/tailwind/references/comp-container-customize.md create mode 100644 .claude/skills/tailwind/references/comp-reference-directive.md create mode 100644 .claude/skills/tailwind/references/comp-smart-sorting.md create mode 100644 .claude/skills/tailwind/references/comp-utility-file-scope.md create mode 100644 .claude/skills/tailwind/references/gen-avoid-theme-bloat.md create mode 100644 .claude/skills/tailwind/references/gen-css-first-config.md create mode 100644 .claude/skills/tailwind/references/gen-css-variable-syntax.md create mode 100644 .claude/skills/tailwind/references/gen-dynamic-utilities.md create mode 100644 .claude/skills/tailwind/references/gen-oklch-colors.md create mode 100644 .claude/skills/tailwind/references/gen-utility-directive.md create mode 100644 .claude/skills/tailwind/references/resp-container-queries.md create mode 100644 .claude/skills/tailwind/references/resp-custom-breakpoints.md create mode 100644 .claude/skills/tailwind/references/resp-hover-capability.md create mode 100644 .claude/skills/tailwind/references/resp-logical-properties.md create mode 100644 .claude/skills/tailwind/references/resp-mobile-first.md create mode 100644 .claude/skills/tailwind/references/theme-color-scheme.md create mode 100644 .claude/skills/tailwind/references/theme-dark-mode-class.md create mode 100644 .claude/skills/tailwind/references/theme-prefix-variables.md create mode 100644 .claude/skills/tailwind/references/theme-runtime-variables.md create mode 100644 .claude/skills/tailwind/references/theme-semantic-tokens.md create mode 100644 .claude/skills/tailwind/references/util-explicit-colors.md create mode 100644 .claude/skills/tailwind/references/util-gradient-via-none.md create mode 100644 .claude/skills/tailwind/references/util-important-modifier.md create mode 100644 .claude/skills/tailwind/references/util-opacity-modifier.md create mode 100644 .claude/skills/tailwind/references/util-renamed-utilities.md create mode 100644 .claude/skills/tailwind/references/util-variant-stacking.md create mode 100644 .claude/skills/tanstack-query/SKILL.md create mode 100644 .claude/skills/tanstack-query/references/cache-enabled-option.md create mode 100644 .claude/skills/tanstack-query/references/cache-global-defaults.md create mode 100644 .claude/skills/tanstack-query/references/cache-invalidation-precision.md create mode 100644 .claude/skills/tanstack-query/references/cache-placeholder-vs-initial.md create mode 100644 .claude/skills/tanstack-query/references/cache-refetch-triggers.md create mode 100644 .claude/skills/tanstack-query/references/cache-staletime-gctime.md create mode 100644 .claude/skills/tanstack-query/references/error-conditional-retry.md create mode 100644 .claude/skills/tanstack-query/references/error-display-patterns.md create mode 100644 .claude/skills/tanstack-query/references/error-global-handler.md create mode 100644 .claude/skills/tanstack-query/references/error-retry-config.md create mode 100644 .claude/skills/tanstack-query/references/error-throw-on-error.md create mode 100644 .claude/skills/tanstack-query/references/infinite-flatten-pages.md create mode 100644 .claude/skills/tanstack-query/references/infinite-loading-states.md create mode 100644 .claude/skills/tanstack-query/references/infinite-max-pages.md create mode 100644 .claude/skills/tanstack-query/references/infinite-refetch-behavior.md create mode 100644 .claude/skills/tanstack-query/references/mutation-avoid-parallel.md create mode 100644 .claude/skills/tanstack-query/references/mutation-cancel-queries.md create mode 100644 .claude/skills/tanstack-query/references/mutation-invalidate-onsettled.md create mode 100644 .claude/skills/tanstack-query/references/mutation-optimistic-updates.md create mode 100644 .claude/skills/tanstack-query/references/mutation-setquerydata.md create mode 100644 .claude/skills/tanstack-query/references/prefetch-avoid-waterfalls.md create mode 100644 .claude/skills/tanstack-query/references/prefetch-flatten-api.md create mode 100644 .claude/skills/tanstack-query/references/prefetch-in-queryfn.md create mode 100644 .claude/skills/tanstack-query/references/prefetch-infinite-query.md create mode 100644 .claude/skills/tanstack-query/references/prefetch-on-hover.md create mode 100644 .claude/skills/tanstack-query/references/prefetch-server-components.md create mode 100644 .claude/skills/tanstack-query/references/render-notify-props.md create mode 100644 .claude/skills/tanstack-query/references/render-select-derived.md create mode 100644 .claude/skills/tanstack-query/references/render-select-memoize.md create mode 100644 .claude/skills/tanstack-query/references/render-structural-sharing.md create mode 100644 .claude/skills/tanstack-query/references/render-tracked-props.md create mode 100644 .claude/skills/tanstack-query/references/suspense-boundaries-placement.md create mode 100644 .claude/skills/tanstack-query/references/suspense-error-boundaries.md create mode 100644 .claude/skills/tanstack-query/references/suspense-parallel-queries.md create mode 100644 .claude/skills/tanstack-query/references/suspense-use-suspense-hooks.md create mode 100644 .claude/skills/tanstack-query/references/tquery-always-arrays.md create mode 100644 .claude/skills/tanstack-query/references/tquery-colocate-keys.md create mode 100644 .claude/skills/tanstack-query/references/tquery-hierarchical-keys.md create mode 100644 .claude/skills/tanstack-query/references/tquery-key-factories.md create mode 100644 .claude/skills/tanstack-query/references/tquery-options-pattern.md create mode 100644 .claude/skills/tanstack-query/references/tquery-serializable-objects.md create mode 100644 .claude/skills/tdd/SKILL.md create mode 100644 .claude/skills/tdd/references/assert-custom-matchers.md create mode 100644 .claude/skills/tdd/references/assert-error-messages.md create mode 100644 .claude/skills/tdd/references/assert-no-assertions-antipattern.md create mode 100644 .claude/skills/tdd/references/assert-snapshot-testing.md create mode 100644 .claude/skills/tdd/references/assert-specific-assertions.md create mode 100644 .claude/skills/tdd/references/cycle-maintain-test-list.md create mode 100644 .claude/skills/tdd/references/cycle-minimal-code-to-pass.md create mode 100644 .claude/skills/tdd/references/cycle-refactor-after-green.md create mode 100644 .claude/skills/tdd/references/cycle-small-increments.md create mode 100644 .claude/skills/tdd/references/cycle-verify-test-fails-first.md create mode 100644 .claude/skills/tdd/references/cycle-write-test-first.md create mode 100644 .claude/skills/tdd/references/data-avoid-mystery-guests.md create mode 100644 .claude/skills/tdd/references/data-builder-pattern.md create mode 100644 .claude/skills/tdd/references/data-minimal-setup.md create mode 100644 .claude/skills/tdd/references/data-unique-identifiers.md create mode 100644 .claude/skills/tdd/references/data-use-factories.md create mode 100644 .claude/skills/tdd/references/design-aaa-pattern.md create mode 100644 .claude/skills/tdd/references/design-avoid-logic-in-tests.md create mode 100644 .claude/skills/tdd/references/design-descriptive-test-names.md create mode 100644 .claude/skills/tdd/references/design-one-assertion-per-test.md create mode 100644 .claude/skills/tdd/references/design-test-behavior-not-implementation.md create mode 100644 .claude/skills/tdd/references/design-test-edge-cases.md create mode 100644 .claude/skills/tdd/references/isolate-deterministic-tests.md create mode 100644 .claude/skills/tdd/references/isolate-mock-external-dependencies.md create mode 100644 .claude/skills/tdd/references/isolate-no-shared-state.md create mode 100644 .claude/skills/tdd/references/isolate-prefer-stubs-over-mocks.md create mode 100644 .claude/skills/tdd/references/isolate-use-dependency-injection.md create mode 100644 .claude/skills/tdd/references/org-file-structure.md create mode 100644 .claude/skills/tdd/references/org-group-by-behavior.md create mode 100644 .claude/skills/tdd/references/org-parameterized-tests.md create mode 100644 .claude/skills/tdd/references/org-setup-teardown.md create mode 100644 .claude/skills/tdd/references/org-test-utilities.md create mode 100644 .claude/skills/tdd/references/perf-avoid-network-calls.md create mode 100644 .claude/skills/tdd/references/perf-avoid-sleep.md create mode 100644 .claude/skills/tdd/references/perf-fast-unit-tests.md create mode 100644 .claude/skills/tdd/references/perf-fix-flaky-tests.md create mode 100644 .claude/skills/tdd/references/perf-parallelize-tests.md create mode 100644 .claude/skills/tdd/references/strat-coverage-targets.md create mode 100644 .claude/skills/tdd/references/strat-e2e-critical-paths.md create mode 100644 .claude/skills/tdd/references/strat-integration-boundaries.md create mode 100644 .claude/skills/tdd/references/strat-mutation-testing.md create mode 100644 .claude/skills/tdd/references/strat-test-pyramid.md create mode 100644 .claude/skills/typescript/SKILL.md create mode 100644 .claude/skills/typescript/references/advanced-branded-types.md create mode 100644 .claude/skills/typescript/references/advanced-satisfies-operator.md create mode 100644 .claude/skills/typescript/references/advanced-template-literal-types.md create mode 100644 .claude/skills/typescript/references/async-avoid-loop-await.md create mode 100644 .claude/skills/typescript/references/async-avoid-unnecessary-async.md create mode 100644 .claude/skills/typescript/references/async-defer-await.md create mode 100644 .claude/skills/typescript/references/async-explicit-return-types.md create mode 100644 .claude/skills/typescript/references/async-parallel-promises.md create mode 100644 .claude/skills/typescript/references/mem-avoid-closure-leaks.md create mode 100644 .claude/skills/typescript/references/mem-avoid-global-state.md create mode 100644 .claude/skills/typescript/references/mem-cleanup-event-listeners.md create mode 100644 .claude/skills/typescript/references/mem-clear-timers.md create mode 100644 .claude/skills/typescript/references/mem-use-weakmap-for-metadata.md create mode 100644 .claude/skills/typescript/references/module-avoid-barrel-imports.md create mode 100644 .claude/skills/typescript/references/module-avoid-circular-dependencies.md create mode 100644 .claude/skills/typescript/references/module-control-types-inclusion.md create mode 100644 .claude/skills/typescript/references/module-dynamic-imports.md create mode 100644 .claude/skills/typescript/references/module-use-type-imports.md create mode 100644 .claude/skills/typescript/references/runtime-avoid-object-spread-in-loops.md create mode 100644 .claude/skills/typescript/references/runtime-cache-property-access.md create mode 100644 .claude/skills/typescript/references/runtime-prefer-array-methods.md create mode 100644 .claude/skills/typescript/references/runtime-use-for-of-for-iteration.md create mode 100644 .claude/skills/typescript/references/runtime-use-set-for-lookups.md create mode 100644 .claude/skills/typescript/references/runtime-use-string-methods.md create mode 100644 .claude/skills/typescript/references/safety-assertion-functions.md create mode 100644 .claude/skills/typescript/references/safety-const-assertions.md create mode 100644 .claude/skills/typescript/references/safety-exhaustive-checks.md create mode 100644 .claude/skills/typescript/references/safety-prefer-unknown-over-any.md create mode 100644 .claude/skills/typescript/references/safety-strict-null-checks.md create mode 100644 .claude/skills/typescript/references/safety-use-type-guards.md create mode 100644 .claude/skills/typescript/references/tscfg-enable-incremental.md create mode 100644 .claude/skills/typescript/references/tscfg-exclude-properly.md create mode 100644 .claude/skills/typescript/references/tscfg-isolate-modules.md create mode 100644 .claude/skills/typescript/references/tscfg-project-references.md create mode 100644 .claude/skills/typescript/references/tscfg-skip-lib-check.md create mode 100644 .claude/skills/typescript/references/tscfg-strict-function-types.md create mode 100644 .claude/skills/typescript/references/tscfg-typescript-7.md create mode 100644 .claude/skills/typescript/references/type-avoid-deep-generics.md create mode 100644 .claude/skills/typescript/references/type-avoid-large-unions.md create mode 100644 .claude/skills/typescript/references/type-explicit-return-types.md create mode 100644 .claude/skills/typescript/references/type-extract-conditional-types.md create mode 100644 .claude/skills/typescript/references/type-interfaces-over-intersections.md create mode 100644 .claude/skills/typescript/references/type-limit-recursion-depth.md create mode 100644 .claude/skills/typescript/references/type-simplify-mapped-types.md create mode 100644 .claude/skills/ui-design/SKILL.md create mode 100644 .claude/skills/ui-design/references/access-alt-text.md create mode 100644 .claude/skills/ui-design/references/access-aria-labels.md create mode 100644 .claude/skills/ui-design/references/access-focus-indicators.md create mode 100644 .claude/skills/ui-design/references/access-heading-hierarchy.md create mode 100644 .claude/skills/ui-design/references/access-keyboard-navigation.md create mode 100644 .claude/skills/ui-design/references/access-semantic-html.md create mode 100644 .claude/skills/ui-design/references/access-target-size.md create mode 100644 .claude/skills/ui-design/references/anim-duration-easing.md create mode 100644 .claude/skills/ui-design/references/anim-gpu-properties.md create mode 100644 .claude/skills/ui-design/references/anim-reduced-motion.md create mode 100644 .claude/skills/ui-design/references/anim-will-change.md create mode 100644 .claude/skills/ui-design/references/color-contrast-ratio.md create mode 100644 .claude/skills/ui-design/references/color-dark-mode.md create mode 100644 .claude/skills/ui-design/references/color-not-only-indicator.md create mode 100644 .claude/skills/ui-design/references/color-semantic-palette.md create mode 100644 .claude/skills/ui-design/references/cwv-critical-css.md create mode 100644 .claude/skills/ui-design/references/cwv-improve-inp.md create mode 100644 .claude/skills/ui-design/references/cwv-lazy-load-offscreen.md create mode 100644 .claude/skills/ui-design/references/cwv-minimize-cls.md create mode 100644 .claude/skills/ui-design/references/cwv-optimize-lcp.md create mode 100644 .claude/skills/ui-design/references/cwv-responsive-images.md create mode 100644 .claude/skills/ui-design/references/form-autocomplete.md create mode 100644 .claude/skills/ui-design/references/form-error-messages.md create mode 100644 .claude/skills/ui-design/references/form-inline-validation.md create mode 100644 .claude/skills/ui-design/references/form-input-types.md create mode 100644 .claude/skills/ui-design/references/form-labels-above.md create mode 100644 .claude/skills/ui-design/references/layout-f-pattern.md create mode 100644 .claude/skills/ui-design/references/layout-grid-system.md create mode 100644 .claude/skills/ui-design/references/layout-proximity-grouping.md create mode 100644 .claude/skills/ui-design/references/layout-single-cta.md create mode 100644 .claude/skills/ui-design/references/layout-visual-hierarchy.md create mode 100644 .claude/skills/ui-design/references/layout-whitespace.md create mode 100644 .claude/skills/ui-design/references/resp-container-queries.md create mode 100644 .claude/skills/ui-design/references/resp-fluid-typography.md create mode 100644 .claude/skills/ui-design/references/resp-mobile-first.md create mode 100644 .claude/skills/ui-design/references/resp-touch-targets.md create mode 100644 .claude/skills/ui-design/references/resp-viewport-meta.md create mode 100644 .claude/skills/ui-design/references/typo-font-display.md create mode 100644 .claude/skills/ui-design/references/typo-line-height.md create mode 100644 .claude/skills/ui-design/references/typo-preload-fonts.md create mode 100644 .claude/skills/ui-design/references/typo-readable-line-length.md create mode 100644 .claude/skills/ui-design/references/typo-system-font-stack.md create mode 100644 .claude/skills/vercel-composition-patterns/SKILL.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/architecture-compound-components.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/react19-no-forwardref.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/state-context-interface.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/state-decouple-implementation.md create mode 100644 .claude/skills/vercel-composition-patterns/rules/state-lift-state.md create mode 100644 .claude/skills/vercel-react-best-practices/SKILL.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-init-once.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-use-latest.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-api-routes.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-defer-await.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-dependencies.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-parallel.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-conditional.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-preload.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-event-listeners.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-localstorage-schema.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-swr-dedup.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-batch-dom-css.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-cache-function-results.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-cache-property-access.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-cache-storage.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-combine-iterations.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-early-exit.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-flatmap-filter.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-hoist-regexp.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-index-maps.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-length-check-first.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-min-max-loop.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-request-idle-callback.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-set-map-lookups.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-activity.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-conditional-render.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-content-visibility.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-resource-hints.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-svg-precision.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-defer-reads.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-dependencies.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-derived-state.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-memo.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-transitions.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-after-nonblocking.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-auth-actions.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-cache-lru.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-cache-react.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-dedup-props.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-hoist-static-io.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-parallel-fetching.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-serialization.md create mode 100644 .claude/skills/vitest/SKILL.md create mode 100644 .claude/skills/vitest/references/assert-edge-cases.md create mode 100644 .claude/skills/vitest/references/assert-expect-assertions.md create mode 100644 .claude/skills/vitest/references/assert-one-assertion-concept.md create mode 100644 .claude/skills/vitest/references/assert-specific-matchers.md create mode 100644 .claude/skills/vitest/references/assert-toequal-vs-tobe.md create mode 100644 .claude/skills/vitest/references/async-act-wrapper.md create mode 100644 .claude/skills/vitest/references/async-await-assertions.md create mode 100644 .claude/skills/vitest/references/async-concurrent-expect.md create mode 100644 .claude/skills/vitest/references/async-error-handling.md create mode 100644 .claude/skills/vitest/references/async-fake-timers.md create mode 100644 .claude/skills/vitest/references/async-return-promises.md create mode 100644 .claude/skills/vitest/references/async-waitfor-polling.md create mode 100644 .claude/skills/vitest/references/env-browser-api-mocking.md create mode 100644 .claude/skills/vitest/references/env-globals-config.md create mode 100644 .claude/skills/vitest/references/env-per-file-override.md create mode 100644 .claude/skills/vitest/references/env-setup-files.md create mode 100644 .claude/skills/vitest/references/mock-avoid-overmocking.md create mode 100644 .claude/skills/vitest/references/mock-clear-between-tests.md create mode 100644 .claude/skills/vitest/references/mock-implementation-not-value.md create mode 100644 .claude/skills/vitest/references/mock-msw-network.md create mode 100644 .claude/skills/vitest/references/mock-spyon-vs-mock.md create mode 100644 .claude/skills/vitest/references/mock-type-safety.md create mode 100644 .claude/skills/vitest/references/mock-vi-mock-hoisting.md create mode 100644 .claude/skills/vitest/references/org-describe-nesting.md create mode 100644 .claude/skills/vitest/references/org-file-colocation.md create mode 100644 .claude/skills/vitest/references/org-test-naming.md create mode 100644 .claude/skills/vitest/references/org-test-skip-only.md create mode 100644 .claude/skills/vitest/references/perf-bail-fast-fail.md create mode 100644 .claude/skills/vitest/references/perf-bench-test-context.md create mode 100644 .claude/skills/vitest/references/perf-disable-isolation.md create mode 100644 .claude/skills/vitest/references/perf-happy-dom.md create mode 100644 .claude/skills/vitest/references/perf-pool-selection.md create mode 100644 .claude/skills/vitest/references/perf-run-mode-ci.md create mode 100644 .claude/skills/vitest/references/perf-sharding.md create mode 100644 .claude/skills/vitest/references/setup-avoid-shared-state.md create mode 100644 .claude/skills/vitest/references/setup-beforeall-expensive.md create mode 100644 .claude/skills/vitest/references/setup-beforeeach-cleanup.md create mode 100644 .claude/skills/vitest/references/setup-reset-modules.md create mode 100644 .claude/skills/vitest/references/setup-restore-mocks.md create mode 100644 .claude/skills/vitest/references/setup-test-factories.md create mode 100644 .claude/skills/vitest/references/setup-vitest5-migration.md create mode 100644 .claude/skills/vitest/references/snap-avoid-large.md create mode 100644 .claude/skills/vitest/references/snap-describe-intent.md create mode 100644 .claude/skills/vitest/references/snap-inline-over-file.md create mode 100644 .claude/skills/vitest/references/snap-review-updates.md create mode 100644 .claude/skills/vitest/references/snap-stable-serialization.md create mode 100644 .claude/skills/web-design-guidelines/SKILL.md create mode 100644 .claude/skills/zod/SKILL.md create mode 100644 .claude/skills/zod/references/compose-intersection.md create mode 100644 .claude/skills/zod/references/compose-lazy-recursive.md create mode 100644 .claude/skills/zod/references/compose-pipe.md create mode 100644 .claude/skills/zod/references/compose-preprocess.md create mode 100644 .claude/skills/zod/references/compose-shared-schemas.md create mode 100644 .claude/skills/zod/references/error-avoid-throwing-in-refine.md create mode 100644 .claude/skills/zod/references/error-custom-messages.md create mode 100644 .claude/skills/zod/references/error-i18n.md create mode 100644 .claude/skills/zod/references/error-path-for-nested.md create mode 100644 .claude/skills/zod/references/error-use-flatten.md create mode 100644 .claude/skills/zod/references/object-discriminated-unions.md create mode 100644 .claude/skills/zod/references/object-extend-for-composition.md create mode 100644 .claude/skills/zod/references/object-optional-vs-nullable.md create mode 100644 .claude/skills/zod/references/object-partial-for-updates.md create mode 100644 .claude/skills/zod/references/object-pick-omit.md create mode 100644 .claude/skills/zod/references/object-strict-vs-strip.md create mode 100644 .claude/skills/zod/references/parse-async-for-async-refinements.md create mode 100644 .claude/skills/zod/references/parse-avoid-double-validation.md create mode 100644 .claude/skills/zod/references/parse-handle-all-issues.md create mode 100644 .claude/skills/zod/references/parse-never-trust-json.md create mode 100644 .claude/skills/zod/references/parse-use-safeparse.md create mode 100644 .claude/skills/zod/references/parse-validate-early.md create mode 100644 .claude/skills/zod/references/parse-validate-for-boolean-checks.md create mode 100644 .claude/skills/zod/references/perf-arrays.md create mode 100644 .claude/skills/zod/references/perf-avoid-dynamic-creation.md create mode 100644 .claude/skills/zod/references/perf-cache-schemas.md create mode 100644 .claude/skills/zod/references/perf-compile-schemas.md create mode 100644 .claude/skills/zod/references/perf-lazy-loading.md create mode 100644 .claude/skills/zod/references/perf-zod-mini.md create mode 100644 .claude/skills/zod/references/refine-add-path.md create mode 100644 .claude/skills/zod/references/refine-catch.md create mode 100644 .claude/skills/zod/references/refine-defaults.md create mode 100644 .claude/skills/zod/references/refine-transform-coerce.md create mode 100644 .claude/skills/zod/references/refine-use-codec.md create mode 100644 .claude/skills/zod/references/refine-vs-superrefine.md create mode 100644 .claude/skills/zod/references/schema-avoid-optional-abuse.md create mode 100644 .claude/skills/zod/references/schema-coercion-for-form-data.md create mode 100644 .claude/skills/zod/references/schema-string-validations.md create mode 100644 .claude/skills/zod/references/schema-use-enums.md create mode 100644 .claude/skills/zod/references/schema-use-primitives-correctly.md create mode 100644 .claude/skills/zod/references/schema-use-unknown-not-any.md create mode 100644 .claude/skills/zod/references/type-branded-types.md create mode 100644 .claude/skills/zod/references/type-enable-strict-mode.md create mode 100644 .claude/skills/zod/references/type-export-schemas-and-types.md create mode 100644 .claude/skills/zod/references/type-input-vs-output.md create mode 100644 .claude/skills/zod/references/type-use-z-infer.md create mode 100644 .config/dotnet-tools.json create mode 100644 .dockerignore create mode 100644 .env.example create mode 100644 .github/SECURITY.md create mode 100644 AGENTS.md create mode 100644 Backend/Directory.Build.props create mode 100644 Backend/Dockerfile create mode 100644 Backend/docker/mysql-init.sh rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Api/Endpoints/AdministrationEndpoints.cs (74%) rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Api/Extensions.cs (93%) create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Api/Operations/AdministrationOperations.cs (84%) rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Application/Extensions.cs (88%) create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Application/Services/AdminModuleApi.cs (84%) create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Application/Services/AdminService.cs rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Shared/Interfaces/IAdminModuleApi.cs (58%) create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs (57%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Api/Extensions.cs (93%) create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs (65%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Application/Extensions.cs (76%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs (63%) create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs (55%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Core/Entities/AppUser.cs (75%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Core/Entities/AuthSettings.cs (99%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Core/Entities/TokenModel.cs (99%) create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/AppIdentityDbContext.cs (92%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/AppIdentityDbContextFactory.cs (91%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250825091711_Initial.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250825091711_Initial.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250902202604_AddIsBlockedColumn.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250902202604_AddIsBlockedColumn.cs (100%) create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20261021180313_UpgradeNet10Identity.Designer.cs create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20261021180313_UpgradeNet10Identity.cs rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/AppIdentityDbContextModelSnapshot.cs (99%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/Extensions.cs (82%) create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangePasswordRequest.cs rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/EditUserRequest.cs (69%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/LoginRequest.cs (52%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/RegisterRequest.cs (99%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/Dtos/UserDto.cs (99%) rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/Entities/CurrentUser.cs (99%) create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/Static/Entities/AppRoles.cs (99%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Api/Backups/BackupQueueEndpoints.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Backups/BackupsEo.cs (67%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Extensions.cs (92%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Schedules/SchedulesEo.cs (95%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Api/Security/ResourceAccessFilter.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Servers/ServersEo.cs (92%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs (93%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Extensions.cs (62%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Interfaces/IBackupExecutor.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Interfaces/IDbBackupService.cs (76%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Interfaces/IEmailProviderService.cs (80%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupExecutor.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupQueueCoordinator.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupQueueProcessor.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupQueueService.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupTarget.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/EmailProviderService.cs (99%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/NotifyService.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/SchedulesService.cs (83%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs (88%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs (96%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs (86%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Workers/BackupWorker.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/DatabaseBase.cs (75%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/PostgreSqlDatabase.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/SqlServerDatabase.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/AutomaticBackupTestConfig.cs (76%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupRequest.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupSchedule.cs (93%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs (88%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs (95%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs (92%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs (86%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/ServerBackupsConfiguration.cs (70%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/ServersUsers.cs (76%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/UserNotificationsSettings.cs (89%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/AppEmailConfigurationModel.cs (81%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/ApplicationConfigurationModel.cs (99%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/BackupDayTime.cs (67%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/EWeekDay.cs (69%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/EmailProviderConfigurationModel.cs (88%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Models/MailModel.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Exceptions/EmptyListOfConfigurationsException.cs (82%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Interfaces/IDatabase.cs (92%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/CompressBackupFile.cs (98%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/DeleteOldBackup.cs (99%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/DumpFailureException.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/DumpProcess.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/MySqlDumpClient.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/PrepareEmailMessageBody.cs (95%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/SafeBackupPath.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/SshHostKeys.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/SshTunnelHelper.cs (77%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Configuration/LoggerPrepareSetup.cs (99%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Configuration/PrepareApplicationSettings.cs (99%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/BackupsDbContext.cs (55%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250903215501_Initial.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250903215501_Initial.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250904111233_AddPKToServersUsers.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250904111233_AddPKToServersUsers.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250909144138_UpdateSchedulesEntity.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250909144138_UpdateSchedulesEntity.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250910104700_AddPEMPassphraseToTunnelEntity.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250910104700_AddPEMPassphraseToTunnelEntity.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911091310_UpdateBackupsColumns.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911091310_UpdateBackupsColumns.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911125405_UpdateBackupEntity.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911125405_UpdateBackupEntity.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911172706_ModifyNullsInBackupEntity.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911172706_ModifyNullsInBackupEntity.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs (100%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20261021203734_AddPersistentBackupQueue.Designer.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20261021203734_AddPersistentBackupQueue.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs (78%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Extensions.cs (85%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251010094225_UpdateAutoTestConfigEntity.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251010094225_UpdateAutoTestConfigEntity.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs (100%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs (100%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs (88%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/AutoTestBackupConfigDto.cs (98%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupRequestDto.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupScheduleConfiguration.cs (93%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs (86%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupsScheduleDto.cs (90%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs (94%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs (86%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerNameIdDto.cs rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs (97%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServersUsersListDto.cs (84%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs (87%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Enums/DatabaseType.cs (61%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs (98%) rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Helpers/BackupScheduleHelper.cs (86%) create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Hubs/BackupHub.cs create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Modules.Backup.Shared.csproj rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Requests/ModifyServerAccessRequest.cs (54%) rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Api/Extension.cs (83%) create mode 100644 Backend/src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Application/Extensions.cs (86%) create mode 100644 Backend/src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Application/Services/CryptoService.cs (63%) rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Shared/Interfaces/ICryptoService.cs (71%) create mode 100644 Backend/src/Modules/CryptoModule/Modules.Crypto.Shared/Modules.Crypto.Shared.csproj create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Attributes/AdminTokenAuthorizationFilter.cs create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Attributes/RequestValidationFilter.cs rename {DbBackupService/Src => Backend/src}/Modules/Shared/Modules.Shared/Common/ApiBaseController.cs (79%) create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Common/DbCommon.cs create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Modules.Shared.csproj create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Settings/ApplicationSettings.cs create mode 100644 Backend/src/Server.Api/Configuration/ApplicationSettingsEndpoints.cs create mode 100644 Backend/src/Server.Api/Configuration/DevelopmentSettings.cs create mode 100644 Backend/src/Server.Api/Configuration/FileApplicationSettings.cs create mode 100644 Backend/src/Server.Api/Program.cs create mode 100644 Backend/src/Server.Api/Properties/launchSettings.json create mode 100644 Backend/src/Server.Api/Security/ApiExceptionHandler.cs create mode 100644 Backend/src/Server.Api/Security/BootstrapAdmin.cs create mode 100644 Backend/src/Server.Api/Server.Api.csproj create mode 100644 Backend/src/Server.Api/appsettings.Development.json create mode 100644 Backend/src/Server.Api/appsettings.json create mode 100644 Backend/tests/DumpToolFixture/DumpToolFixture.csproj create mode 100644 Backend/tests/DumpToolFixture/Program.cs create mode 100644 Backend/tests/MySqlDumpSmoke/MySqlDumpSmoke.csproj create mode 100644 Backend/tests/MySqlDumpSmoke/Program.cs create mode 100644 Backend/tests/OctoBackup.Tests/ApplicationSettingsTests.cs create mode 100644 Backend/tests/OctoBackup.Tests/BackupQueueTests.cs create mode 100644 Backend/tests/OctoBackup.Tests/DevelopmentSettingsTests.cs create mode 100644 Backend/tests/OctoBackup.Tests/DumpProcessTests.cs create mode 100644 Backend/tests/OctoBackup.Tests/OctoBackup.Tests.csproj create mode 100644 Backend/tests/OctoBackup.Tests/SecurityTests.cs delete mode 100644 DbBackupService/.dockerignore delete mode 100644 DbBackupService/OctoBackup.sln delete mode 100644 DbBackupService/Src/.dockerignore delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/App.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/HttpHandlers/HttpTokenAuthHeaderHandler.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Interfaces/IAuthHttpClientService.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/AdministrationHttpService.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/AuthHttpClientHttpClientService.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/AuthStateProvider.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/TokenHttpClientService.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/AuthLayout.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/AuthorizedNavMenu.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/DefaultLayout.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/MainLayout.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/NotAuthorizedNavMenu.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationServersUsers.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/ServersUsersManagement/AddUserToServerDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/ServersUsersManagement/ManageUsersInServerDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/UsersManagement/CreateNewUserDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/UsersManagement/EditUserDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/ConfirmPassword.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Login.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Register.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Schedule/BackupScheduleDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerAutoTestConfigurationDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/TestServerDialog.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Components/AuthorizingUserInfoComponent.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Properties/launchSettings.json delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Routes.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/_Imports.razor delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/wwwroot/css/app.css delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/wwwroot/media/OctoBackupLogo.png delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Common/SeqConfiguration.cs delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Properties/launchSettings.json delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/appsettings.Development.json delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/appsettings.json delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Services/AdminService.cs delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/TokenValidationService.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Repositories/IUserTokenService.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Repositories/UserTokenService.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangePasswordRequest.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/TokenValidationRequest.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Entities/TokenModelDto.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Interfaces/ITokenValidationService.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Static/Entities/AuthHeaderName.cs delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Static/Setters/HttpClientAuthHeaderSetter.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/NotifyService.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Workers/BackupWorker.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/PostgreSqlDatabase.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/SqlServerDatabase.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Models/MailModel.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/ToolChecker.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerNameIdDto.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Hubs/BackupHub.cs delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Modules.Backup.Shared.csproj delete mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs delete mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs delete mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj delete mode 100644 DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj delete mode 100644 DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj delete mode 100644 DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Shared/Modules.Crypto.Shared.csproj delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Attributes/AdminTokenAuthorizationFilter.cs delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Attributes/AllowWithoutTokenValidationAttribute.cs delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Attributes/BasicTokenAuthorizationFilter.cs delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj delete mode 100755 DbBackupService/buildAndDeployDocker.bat delete mode 100644 DbBackupService/certs/OctoBackupCert.pfx delete mode 100644 DbBackupService/docker-compose.yml delete mode 100644 DbBackupService/docker-composedev.yml create mode 100644 Frontend/Dockerfile create mode 100644 Frontend/docker/10-local-tls.sh create mode 100644 Frontend/docker/default.conf create mode 100644 Frontend/e2e/workspace.spec.ts create mode 100644 Frontend/index.html create mode 100644 Frontend/package-lock.json create mode 100644 Frontend/package.json create mode 100644 Frontend/playwright.config.ts create mode 100644 Frontend/scripts/run-tool.mjs create mode 100644 Frontend/scripts/start-test-api.mjs create mode 100644 Frontend/src/app/App.tsx create mode 100644 Frontend/src/features/account/AccountPage.tsx create mode 100644 Frontend/src/features/admin/ApplicationSettingsPage.tsx create mode 100644 Frontend/src/features/admin/UsersPage.tsx create mode 100644 Frontend/src/features/auth/AuthPage.tsx create mode 100644 Frontend/src/features/backups/BackupsPage.tsx create mode 100644 Frontend/src/features/dashboard/Dashboard.tsx create mode 100644 Frontend/src/features/queue/QueueHero.test.tsx create mode 100644 Frontend/src/features/queue/QueueHero.tsx create mode 100644 Frontend/src/features/queue/QueuePage.tsx create mode 100644 Frontend/src/features/queue/useBackupQueue.ts create mode 100644 Frontend/src/features/schedules/SchedulesPage.test.tsx create mode 100644 Frontend/src/features/schedules/SchedulesPage.tsx create mode 100644 Frontend/src/features/servers/ServerForm.tsx create mode 100644 Frontend/src/features/servers/ServersPage.tsx create mode 100644 Frontend/src/main.tsx create mode 100644 Frontend/src/shared/api.test.ts create mode 100644 Frontend/src/shared/api.ts create mode 100644 Frontend/src/shared/types.ts create mode 100644 Frontend/src/shared/ui.tsx create mode 100644 Frontend/src/styles.css create mode 100644 Frontend/src/test/setup.ts create mode 100644 Frontend/src/vite-env.d.ts create mode 100644 Frontend/tsconfig.json create mode 100644 Frontend/vite.config.ts create mode 100644 OctoBackup.sln delete mode 100644 README_PL.md create mode 100644 agent/skills/feature-arch/SKILL.md create mode 100644 agent/skills/feature-arch/references/bound-event-based-communication.md create mode 100644 agent/skills/feature-arch/references/bound-feature-isolation.md create mode 100644 agent/skills/feature-arch/references/bound-feature-scoped-routing.md create mode 100644 agent/skills/feature-arch/references/bound-feature-size.md create mode 100644 agent/skills/feature-arch/references/bound-interface-contracts.md create mode 100644 agent/skills/feature-arch/references/bound-minimize-shared-state.md create mode 100644 agent/skills/feature-arch/references/fcomp-colocate-styles.md create mode 100644 agent/skills/feature-arch/references/fcomp-composition-over-props.md create mode 100644 agent/skills/feature-arch/references/fcomp-container-presentational.md create mode 100644 agent/skills/feature-arch/references/fcomp-error-boundaries.md create mode 100644 agent/skills/feature-arch/references/fcomp-props-as-data-boundary.md create mode 100644 agent/skills/feature-arch/references/fcomp-single-responsibility.md create mode 100644 agent/skills/feature-arch/references/fquery-avoid-n-plus-one.md create mode 100644 agent/skills/feature-arch/references/fquery-colocate-with-feature.md create mode 100644 agent/skills/feature-arch/references/fquery-feature-scoped-keys.md create mode 100644 agent/skills/feature-arch/references/fquery-parallel-fetching.md create mode 100644 agent/skills/feature-arch/references/fquery-server-component-fetching.md create mode 100644 agent/skills/feature-arch/references/fquery-single-responsibility.md create mode 100644 agent/skills/feature-arch/references/fstate-context-sparingly.md create mode 100644 agent/skills/feature-arch/references/fstate-feature-scoped-stores.md create mode 100644 agent/skills/feature-arch/references/fstate-lift-minimally.md create mode 100644 agent/skills/feature-arch/references/fstate-reset-on-unmount.md create mode 100644 agent/skills/feature-arch/references/fstate-server-state-separation.md create mode 100644 agent/skills/feature-arch/references/import-avoid-barrel-files.md create mode 100644 agent/skills/feature-arch/references/import-no-cross-feature.md create mode 100644 agent/skills/feature-arch/references/import-path-aliases.md create mode 100644 agent/skills/feature-arch/references/import-public-api.md create mode 100644 agent/skills/feature-arch/references/import-type-only.md create mode 100644 agent/skills/feature-arch/references/import-unidirectional-flow.md create mode 100644 agent/skills/feature-arch/references/name-descriptive-exports.md create mode 100644 agent/skills/feature-arch/references/name-feature-naming.md create mode 100644 agent/skills/feature-arch/references/name-file-conventions.md create mode 100644 agent/skills/feature-arch/references/struct-app-layer.md create mode 100644 agent/skills/feature-arch/references/struct-feature-folders.md create mode 100644 agent/skills/feature-arch/references/struct-feature-self-contained.md create mode 100644 agent/skills/feature-arch/references/struct-flat-hierarchy.md create mode 100644 agent/skills/feature-arch/references/struct-optional-segments.md create mode 100644 agent/skills/feature-arch/references/struct-shared-layer.md create mode 100644 agent/skills/feature-arch/references/test-colocate-with-feature.md create mode 100644 agent/skills/feature-arch/references/test-feature-isolation.md create mode 100644 agent/skills/feature-arch/references/test-integration-at-app-layer.md create mode 100644 agent/skills/feature-arch/references/test-shared-utilities.md create mode 100644 agent/skills/msw/SKILL.md create mode 100644 agent/skills/msw/references/advanced-bypass-requests.md create mode 100644 agent/skills/msw/references/advanced-cookies-auth.md create mode 100644 agent/skills/msw/references/advanced-dynamic-scenarios.md create mode 100644 agent/skills/msw/references/advanced-file-uploads.md create mode 100644 agent/skills/msw/references/advanced-playwright-integration.md create mode 100644 agent/skills/msw/references/advanced-vitest-browser.md create mode 100644 agent/skills/msw/references/advanced-websocket-mocking.md create mode 100644 agent/skills/msw/references/debug-common-issues.md create mode 100644 agent/skills/msw/references/debug-lifecycle-events.md create mode 100644 agent/skills/msw/references/debug-request-logging.md create mode 100644 agent/skills/msw/references/debug-verify-interception.md create mode 100644 agent/skills/msw/references/graphql-batched-queries.md create mode 100644 agent/skills/msw/references/graphql-error-responses.md create mode 100644 agent/skills/msw/references/graphql-operation-handlers.md create mode 100644 agent/skills/msw/references/graphql-schema-first.md create mode 100644 agent/skills/msw/references/graphql-variables-access.md create mode 100644 agent/skills/msw/references/handler-absolute-urls.md create mode 100644 agent/skills/msw/references/handler-domain-grouping.md create mode 100644 agent/skills/msw/references/handler-happy-path-first.md create mode 100644 agent/skills/msw/references/handler-request-body-parsing.md create mode 100644 agent/skills/msw/references/handler-resolver-argument.md create mode 100644 agent/skills/msw/references/handler-reusability-environments.md create mode 100644 agent/skills/msw/references/handler-shared-resolvers.md create mode 100644 agent/skills/msw/references/handler-v2-response-syntax.md create mode 100644 agent/skills/msw/references/match-custom-predicate.md create mode 100644 agent/skills/msw/references/match-handler-order.md create mode 100644 agent/skills/msw/references/match-http-methods.md create mode 100644 agent/skills/msw/references/match-query-params.md create mode 100644 agent/skills/msw/references/match-url-patterns.md create mode 100644 agent/skills/msw/references/response-custom-headers.md create mode 100644 agent/skills/msw/references/response-delay-realistic.md create mode 100644 agent/skills/msw/references/response-error-simulation.md create mode 100644 agent/skills/msw/references/response-http-response-helpers.md create mode 100644 agent/skills/msw/references/response-one-time-handlers.md create mode 100644 agent/skills/msw/references/response-streaming.md create mode 100644 agent/skills/msw/references/setup-lifecycle-hooks.md create mode 100644 agent/skills/msw/references/setup-node-version.md create mode 100644 agent/skills/msw/references/setup-server-node-entrypoint.md create mode 100644 agent/skills/msw/references/setup-typescript-config.md create mode 100644 agent/skills/msw/references/setup-unhandled-requests.md create mode 100644 agent/skills/msw/references/setup-worker-script-commit.md create mode 100644 agent/skills/msw/references/test-async-utilities.md create mode 100644 agent/skills/msw/references/test-avoid-request-assertions.md create mode 100644 agent/skills/msw/references/test-clear-request-cache.md create mode 100644 agent/skills/msw/references/test-concurrent-boundary.md create mode 100644 agent/skills/msw/references/test-fake-timers-config.md create mode 100644 agent/skills/msw/references/test-jsdom-environment.md create mode 100644 agent/skills/msw/references/test-reset-handlers.md create mode 100644 agent/skills/nextjs/SKILL.md create mode 100644 agent/skills/nextjs/references/action-error-handling.md create mode 100644 agent/skills/nextjs/references/action-optimistic-updates.md create mode 100644 agent/skills/nextjs/references/action-pending-states.md create mode 100644 agent/skills/nextjs/references/action-revalidation.md create mode 100644 agent/skills/nextjs/references/action-server-action-forms.md create mode 100644 agent/skills/nextjs/references/build-barrel-files.md create mode 100644 agent/skills/nextjs/references/build-dynamic-imports.md create mode 100644 agent/skills/nextjs/references/build-external-packages.md create mode 100644 agent/skills/nextjs/references/build-optimize-package-imports.md create mode 100644 agent/skills/nextjs/references/build-turbopack-config.md create mode 100644 agent/skills/nextjs/references/cache-fetch-options.md create mode 100644 agent/skills/nextjs/references/cache-react-cache.md create mode 100644 agent/skills/nextjs/references/cache-revalidate-path.md create mode 100644 agent/skills/nextjs/references/cache-revalidate-tag.md create mode 100644 agent/skills/nextjs/references/cache-segment-config.md create mode 100644 agent/skills/nextjs/references/cache-use-cache-directive.md create mode 100644 agent/skills/nextjs/references/client-children-pattern.md create mode 100644 agent/skills/nextjs/references/client-hydration-mismatch.md create mode 100644 agent/skills/nextjs/references/client-third-party-scripts.md create mode 100644 agent/skills/nextjs/references/client-use-client-boundary.md create mode 100644 agent/skills/nextjs/references/meta-generate-metadata.md create mode 100644 agent/skills/nextjs/references/meta-opengraph-images.md create mode 100644 agent/skills/nextjs/references/meta-robots.md create mode 100644 agent/skills/nextjs/references/meta-sitemap.md create mode 100644 agent/skills/nextjs/references/route-instant-navigations.md create mode 100644 agent/skills/nextjs/references/route-intercepting-routes.md create mode 100644 agent/skills/nextjs/references/route-not-found.md create mode 100644 agent/skills/nextjs/references/route-parallel-routes.md create mode 100644 agent/skills/nextjs/references/route-partial-prefetching.md create mode 100644 agent/skills/nextjs/references/route-prefetching.md create mode 100644 agent/skills/nextjs/references/route-proxy-ts.md create mode 100644 agent/skills/nextjs/references/server-avoid-client-fetching.md create mode 100644 agent/skills/nextjs/references/server-component-streaming.md create mode 100644 agent/skills/nextjs/references/server-data-colocation.md create mode 100644 agent/skills/nextjs/references/server-error-handling.md create mode 100644 agent/skills/nextjs/references/server-parallel-fetching.md create mode 100644 agent/skills/nextjs/references/server-preload-pattern.md create mode 100644 agent/skills/nextjs/references/stream-error-tsx.md create mode 100644 agent/skills/nextjs/references/stream-loading-tsx.md create mode 100644 agent/skills/nextjs/references/stream-nested-suspense.md create mode 100644 agent/skills/nextjs/references/stream-skeleton-matching.md create mode 100644 agent/skills/nextjs/references/stream-suspense-boundaries.md create mode 100644 agent/skills/nuqs/SKILL.md create mode 100644 agent/skills/nuqs/references/advanced-custom-parsers.md create mode 100644 agent/skills/nuqs/references/advanced-eq-function.md create mode 100644 agent/skills/nuqs/references/advanced-framework-adapters.md create mode 100644 agent/skills/nuqs/references/advanced-url-keys.md create mode 100644 agent/skills/nuqs/references/debug-common-errors.md create mode 100644 agent/skills/nuqs/references/debug-enable-logging.md create mode 100644 agent/skills/nuqs/references/debug-testing.md create mode 100644 agent/skills/nuqs/references/history-back-sync.md create mode 100644 agent/skills/nuqs/references/history-push-navigation.md create mode 100644 agent/skills/nuqs/references/history-replace-ephemeral.md create mode 100644 agent/skills/nuqs/references/history-scroll-behavior.md create mode 100644 agent/skills/nuqs/references/parser-array-format.md create mode 100644 agent/skills/nuqs/references/parser-date-format.md create mode 100644 agent/skills/nuqs/references/parser-enum-validation.md create mode 100644 agent/skills/nuqs/references/parser-hex-colors.md create mode 100644 agent/skills/nuqs/references/parser-index-offset.md create mode 100644 agent/skills/nuqs/references/parser-json-validation.md create mode 100644 agent/skills/nuqs/references/parser-use-typed-parsers.md create mode 100644 agent/skills/nuqs/references/parser-with-default.md create mode 100644 agent/skills/nuqs/references/perf-avoid-rerender.md create mode 100644 agent/skills/nuqs/references/perf-clear-on-default.md create mode 100644 agent/skills/nuqs/references/perf-debounce-search.md create mode 100644 agent/skills/nuqs/references/perf-serialize-utility.md create mode 100644 agent/skills/nuqs/references/perf-throttle-updates.md create mode 100644 agent/skills/nuqs/references/server-next15-async.md create mode 100644 agent/skills/nuqs/references/server-parse-before-get.md create mode 100644 agent/skills/nuqs/references/server-search-params-cache.md create mode 100644 agent/skills/nuqs/references/server-shallow-false.md create mode 100644 agent/skills/nuqs/references/server-share-parsers.md create mode 100644 agent/skills/nuqs/references/server-use-transition.md create mode 100644 agent/skills/nuqs/references/setup-import-server.md create mode 100644 agent/skills/nuqs/references/setup-nextjs-version.md create mode 100644 agent/skills/nuqs/references/setup-nuqs-adapter.md create mode 100644 agent/skills/nuqs/references/setup-shared-parsers.md create mode 100644 agent/skills/nuqs/references/setup-use-client.md create mode 100644 agent/skills/nuqs/references/state-avoid-derived.md create mode 100644 agent/skills/nuqs/references/state-clear-with-null.md create mode 100644 agent/skills/nuqs/references/state-controlled-inputs.md create mode 100644 agent/skills/nuqs/references/state-functional-updates.md create mode 100644 agent/skills/nuqs/references/state-options-inheritance.md create mode 100644 agent/skills/nuqs/references/state-setter-return.md create mode 100644 agent/skills/nuqs/references/state-use-query-states.md create mode 100644 agent/skills/playwright/SKILL.md create mode 100644 agent/skills/playwright/references/arch-cleanup-state.md create mode 100644 agent/skills/playwright/references/arch-fixtures.md create mode 100644 agent/skills/playwright/references/arch-page-object-model.md create mode 100644 agent/skills/playwright/references/arch-parallel-execution.md create mode 100644 agent/skills/playwright/references/arch-test-isolation.md create mode 100644 agent/skills/playwright/references/arch-test-production.md create mode 100644 agent/skills/playwright/references/assert-aria-snapshots.md create mode 100644 agent/skills/playwright/references/auth-api-login.md create mode 100644 agent/skills/playwright/references/auth-multiple-roles.md create mode 100644 agent/skills/playwright/references/auth-parallel-workers.md create mode 100644 agent/skills/playwright/references/auth-session-storage.md create mode 100644 agent/skills/playwright/references/auth-storage-state.md create mode 100644 agent/skills/playwright/references/debug-ci-reporters.md create mode 100644 agent/skills/playwright/references/debug-inspector.md create mode 100644 agent/skills/playwright/references/debug-screenshots-videos.md create mode 100644 agent/skills/playwright/references/debug-trace-viewer.md create mode 100644 agent/skills/playwright/references/loc-avoid-xpath.md create mode 100644 agent/skills/playwright/references/loc-chained-locators.md create mode 100644 agent/skills/playwright/references/loc-data-testid.md create mode 100644 agent/skills/playwright/references/loc-frame-locator.md create mode 100644 agent/skills/playwright/references/loc-label-selectors.md create mode 100644 agent/skills/playwright/references/loc-placeholder-selector.md create mode 100644 agent/skills/playwright/references/loc-role-selectors.md create mode 100644 agent/skills/playwright/references/loc-text-selectors.md create mode 100644 agent/skills/playwright/references/mock-abort-requests.md create mode 100644 agent/skills/playwright/references/mock-api-responses.md create mode 100644 agent/skills/playwright/references/mock-har-files.md create mode 100644 agent/skills/playwright/references/mock-intercept-modify.md create mode 100644 agent/skills/playwright/references/mock-network-conditions.md create mode 100644 agent/skills/playwright/references/next-app-router-navigation.md create mode 100644 agent/skills/playwright/references/next-baseurl-config.md create mode 100644 agent/skills/playwright/references/next-server-actions.md create mode 100644 agent/skills/playwright/references/next-server-components.md create mode 100644 agent/skills/playwright/references/next-wait-hydration.md create mode 100644 agent/skills/playwright/references/perf-browser-selection.md create mode 100644 agent/skills/playwright/references/perf-headless-ci.md create mode 100644 agent/skills/playwright/references/perf-retries.md create mode 100644 agent/skills/playwright/references/perf-reuse-server.md create mode 100644 agent/skills/playwright/references/perf-sharding.md create mode 100644 agent/skills/playwright/references/wait-action-retries.md create mode 100644 agent/skills/playwright/references/wait-avoid-hard-waits.md create mode 100644 agent/skills/playwright/references/wait-custom-timeout.md create mode 100644 agent/skills/playwright/references/wait-network-idle.md create mode 100644 agent/skills/playwright/references/wait-soft-assertions.md create mode 100644 agent/skills/playwright/references/wait-web-first-assertions.md create mode 100644 agent/skills/react-hook-form/SKILL.md create mode 100644 agent/skills/react-hook-form/references/adv-devtools-performance.md create mode 100644 agent/skills/react-hook-form/references/adv-formprovider-memo.md create mode 100644 agent/skills/react-hook-form/references/adv-opaque-types.md create mode 100644 agent/skills/react-hook-form/references/adv-testing-wrapper.md create mode 100644 agent/skills/react-hook-form/references/array-complete-default-objects.md create mode 100644 agent/skills/react-hook-form/references/array-separate-crud-operations.md create mode 100644 agent/skills/react-hook-form/references/array-unique-fieldarray-per-name.md create mode 100644 agent/skills/react-hook-form/references/array-use-field-id-as-key.md create mode 100644 agent/skills/react-hook-form/references/array-virtualization-formprovider.md create mode 100644 agent/skills/react-hook-form/references/ctrl-avoid-double-registration.md create mode 100644 agent/skills/react-hook-form/references/ctrl-controller-field-props.md create mode 100644 agent/skills/react-hook-form/references/ctrl-local-state-combination.md create mode 100644 agent/skills/react-hook-form/references/ctrl-single-usecontroller-per-component.md create mode 100644 agent/skills/react-hook-form/references/ctrl-usecontroller-isolation.md create mode 100644 agent/skills/react-hook-form/references/formcfg-async-default-values.md create mode 100644 agent/skills/react-hook-form/references/formcfg-default-values.md create mode 100644 agent/skills/react-hook-form/references/formcfg-revalidate-mode.md create mode 100644 agent/skills/react-hook-form/references/formcfg-should-unregister.md create mode 100644 agent/skills/react-hook-form/references/formcfg-useeffect-dependency.md create mode 100644 agent/skills/react-hook-form/references/formcfg-validation-mode.md create mode 100644 agent/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md create mode 100644 agent/skills/react-hook-form/references/formstate-destructure-formstate.md create mode 100644 agent/skills/react-hook-form/references/formstate-getfieldstate-for-single-field.md create mode 100644 agent/skills/react-hook-form/references/formstate-subscribe-to-specific-fields.md create mode 100644 agent/skills/react-hook-form/references/formstate-useformstate-isolation.md create mode 100644 agent/skills/react-hook-form/references/integ-mui-controller-pattern.md create mode 100644 agent/skills/react-hook-form/references/integ-shadcn-form-import.md create mode 100644 agent/skills/react-hook-form/references/integ-shadcn-select-wiring.md create mode 100644 agent/skills/react-hook-form/references/integ-typed-submit-server-action.md create mode 100644 agent/skills/react-hook-form/references/integ-value-transform.md create mode 100644 agent/skills/react-hook-form/references/sub-avoid-watch-in-render.md create mode 100644 agent/skills/react-hook-form/references/sub-deep-subscription.md create mode 100644 agent/skills/react-hook-form/references/sub-useformcontext-sparingly.md create mode 100644 agent/skills/react-hook-form/references/sub-usewatch-default-value.md create mode 100644 agent/skills/react-hook-form/references/sub-usewatch-over-watch.md create mode 100644 agent/skills/react-hook-form/references/sub-usewatch-with-getvalues.md create mode 100644 agent/skills/react-hook-form/references/sub-watch-specific-fields.md create mode 100644 agent/skills/react-hook-form/references/valid-delay-error.md create mode 100644 agent/skills/react-hook-form/references/valid-dynamic-schema-factory.md create mode 100644 agent/skills/react-hook-form/references/valid-error-message-strategy.md create mode 100644 agent/skills/react-hook-form/references/valid-form-level-validate.md create mode 100644 agent/skills/react-hook-form/references/valid-inline-vs-resolver.md create mode 100644 agent/skills/react-hook-form/references/valid-native-validation.md create mode 100644 agent/skills/react-hook-form/references/valid-resolver-caching.md create mode 100644 agent/skills/react-hook-form/references/valid-trigger-should-touch.md create mode 100644 agent/skills/react/SKILL.md create mode 100644 agent/skills/react/references/_sections.md create mode 100644 agent/skills/react/references/conc-automatic-batching.md create mode 100644 agent/skills/react/references/conc-concurrent-safe.md create mode 100644 agent/skills/react/references/conc-suspense-fallback.md create mode 100644 agent/skills/react/references/conc-use-deferred-value.md create mode 100644 agent/skills/react/references/conc-use-transition.md create mode 100644 agent/skills/react/references/conc-view-transitions.md create mode 100644 agent/skills/react/references/data-cache-deduplication.md create mode 100644 agent/skills/react/references/data-error-boundaries.md create mode 100644 agent/skills/react/references/data-parallel-fetching.md create mode 100644 agent/skills/react/references/data-suspense-data-fetching.md create mode 100644 agent/skills/react/references/data-use-hook.md create mode 100644 agent/skills/react/references/effect-avoid-unnecessary.md create mode 100644 agent/skills/react/references/effect-cleanup.md create mode 100644 agent/skills/react/references/effect-object-dependencies.md create mode 100644 agent/skills/react/references/effect-use-browser-only.md create mode 100644 agent/skills/react/references/effect-use-effect-event.md create mode 100644 agent/skills/react/references/effect-use-sync-external-store.md create mode 100644 agent/skills/react/references/form-actions.md create mode 100644 agent/skills/react/references/form-use-action-state.md create mode 100644 agent/skills/react/references/form-use-form-status.md create mode 100644 agent/skills/react/references/form-use-optimistic.md create mode 100644 agent/skills/react/references/form-validation.md create mode 100644 agent/skills/react/references/memo-avoid-premature.md create mode 100644 agent/skills/react/references/memo-compiler.md create mode 100644 agent/skills/react/references/memo-react-memo.md create mode 100644 agent/skills/react/references/memo-use-callback.md create mode 100644 agent/skills/react/references/memo-use-memo.md create mode 100644 agent/skills/react/references/rcomp-composition.md create mode 100644 agent/skills/react/references/rcomp-controlled-components.md create mode 100644 agent/skills/react/references/rcomp-fragment-refs.md create mode 100644 agent/skills/react/references/rcomp-key-reset.md create mode 100644 agent/skills/react/references/rcomp-render-props.md create mode 100644 agent/skills/react/references/rsc-avoid-client-only-libs.md create mode 100644 agent/skills/react/references/rsc-composition-pattern.md create mode 100644 agent/skills/react/references/rsc-context-provider.md create mode 100644 agent/skills/react/references/rsc-data-fetching-server.md create mode 100644 agent/skills/react/references/rsc-serializable-props.md create mode 100644 agent/skills/react/references/rsc-server-client-boundary.md create mode 100644 agent/skills/react/references/rsc-streaming.md create mode 100644 agent/skills/react/references/rstate-context-optimization.md create mode 100644 agent/skills/react/references/rstate-derived-values.md create mode 100644 agent/skills/react/references/rstate-functional-updates.md create mode 100644 agent/skills/react/references/rstate-lazy-initialization.md create mode 100644 agent/skills/react/references/rstate-use-reducer.md create mode 100644 agent/skills/shadcn/SKILL.md create mode 100644 agent/skills/shadcn/references/ally-ensure-color-contrast.md create mode 100644 agent/skills/shadcn/references/ally-maintain-focus-management.md create mode 100644 agent/skills/shadcn/references/ally-preserve-aria-attributes.md create mode 100644 agent/skills/shadcn/references/ally-preserve-keyboard-navigation.md create mode 100644 agent/skills/shadcn/references/ally-provide-sr-only-labels.md create mode 100644 agent/skills/shadcn/references/arch-current-cli-registry.md create mode 100644 agent/skills/shadcn/references/arch-extend-variants-with-cva.md create mode 100644 agent/skills/shadcn/references/arch-forward-refs-for-composable-components.md create mode 100644 agent/skills/shadcn/references/arch-isolate-component-variants.md create mode 100644 agent/skills/shadcn/references/arch-preserve-radix-primitive-structure.md create mode 100644 agent/skills/shadcn/references/arch-unified-radix-package.md create mode 100644 agent/skills/shadcn/references/arch-use-asChild-for-custom-triggers.md create mode 100644 agent/skills/shadcn/references/arch-use-cn-for-class-merging.md create mode 100644 agent/skills/shadcn/references/comp-combine-command-with-popover.md create mode 100644 agent/skills/shadcn/references/comp-compose-with-compound-components.md create mode 100644 agent/skills/shadcn/references/comp-create-reusable-form-fields.md create mode 100644 agent/skills/shadcn/references/comp-nest-dialogs-correctly.md create mode 100644 agent/skills/shadcn/references/comp-use-drawer-for-mobile-modals.md create mode 100644 agent/skills/shadcn/references/comp-use-slot-pattern-for-flexibility.md create mode 100644 agent/skills/shadcn/references/data-empty-states-with-guidance.md create mode 100644 agent/skills/shadcn/references/data-paginate-server-side.md create mode 100644 agent/skills/shadcn/references/data-use-skeleton-loading-states.md create mode 100644 agent/skills/shadcn/references/data-use-tanstack-table-for-complex-tables.md create mode 100644 agent/skills/shadcn/references/data-virtualize-large-lists.md create mode 100644 agent/skills/shadcn/references/form-handle-async-validation.md create mode 100644 agent/skills/shadcn/references/form-reset-form-state-correctly.md create mode 100644 agent/skills/shadcn/references/form-show-validation-errors-correctly.md create mode 100644 agent/skills/shadcn/references/form-use-react-hook-form-integration.md create mode 100644 agent/skills/shadcn/references/form-use-zod-for-schema-validation.md create mode 100644 agent/skills/shadcn/references/perf-avoid-unnecessary-rerenders-in-forms.md create mode 100644 agent/skills/shadcn/references/perf-debounce-search-inputs.md create mode 100644 agent/skills/shadcn/references/perf-lazy-load-heavy-components.md create mode 100644 agent/skills/shadcn/references/perf-memoize-expensive-renders.md create mode 100644 agent/skills/shadcn/references/perf-optimize-icon-imports.md create mode 100644 agent/skills/shadcn/references/state-colocate-state-with-components.md create mode 100644 agent/skills/shadcn/references/state-lift-state-to-appropriate-level.md create mode 100644 agent/skills/shadcn/references/state-prefer-uncontrolled-for-simple-inputs.md create mode 100644 agent/skills/shadcn/references/state-use-controlled-dialog-state.md create mode 100644 agent/skills/shadcn/references/style-avoid-important-overrides.md create mode 100644 agent/skills/shadcn/references/style-consistent-spacing-scale.md create mode 100644 agent/skills/shadcn/references/style-dark-mode-support.md create mode 100644 agent/skills/shadcn/references/style-responsive-design-patterns.md create mode 100644 agent/skills/shadcn/references/style-use-css-variables-for-theming.md create mode 100644 agent/skills/shadcn/references/style-use-tailwind-theme-extend.md create mode 100644 agent/skills/tailwind/SKILL.md create mode 100644 agent/skills/tailwind/references/anim-3d-transforms.md create mode 100644 agent/skills/tailwind/references/anim-gpu-accelerated.md create mode 100644 agent/skills/tailwind/references/anim-gradient-interpolation.md create mode 100644 agent/skills/tailwind/references/anim-starting-style.md create mode 100644 agent/skills/tailwind/references/build-cli-package.md create mode 100644 agent/skills/tailwind/references/build-content-detection.md create mode 100644 agent/skills/tailwind/references/build-css-import.md create mode 100644 agent/skills/tailwind/references/build-node-version.md create mode 100644 agent/skills/tailwind/references/build-postcss-simplify.md create mode 100644 agent/skills/tailwind/references/build-vite-plugin.md create mode 100644 agent/skills/tailwind/references/bundle-avoid-cdn-production.md create mode 100644 agent/skills/tailwind/references/bundle-avoid-preprocessors.md create mode 100644 agent/skills/tailwind/references/bundle-css-minification.md create mode 100644 agent/skills/tailwind/references/bundle-remove-unused-plugins.md create mode 100644 agent/skills/tailwind/references/bundle-split-critical-css.md create mode 100644 agent/skills/tailwind/references/comp-avoid-apply-overuse.md create mode 100644 agent/skills/tailwind/references/comp-container-customize.md create mode 100644 agent/skills/tailwind/references/comp-reference-directive.md create mode 100644 agent/skills/tailwind/references/comp-smart-sorting.md create mode 100644 agent/skills/tailwind/references/comp-utility-file-scope.md create mode 100644 agent/skills/tailwind/references/gen-avoid-theme-bloat.md create mode 100644 agent/skills/tailwind/references/gen-css-first-config.md create mode 100644 agent/skills/tailwind/references/gen-css-variable-syntax.md create mode 100644 agent/skills/tailwind/references/gen-dynamic-utilities.md create mode 100644 agent/skills/tailwind/references/gen-oklch-colors.md create mode 100644 agent/skills/tailwind/references/gen-utility-directive.md create mode 100644 agent/skills/tailwind/references/resp-container-queries.md create mode 100644 agent/skills/tailwind/references/resp-custom-breakpoints.md create mode 100644 agent/skills/tailwind/references/resp-hover-capability.md create mode 100644 agent/skills/tailwind/references/resp-logical-properties.md create mode 100644 agent/skills/tailwind/references/resp-mobile-first.md create mode 100644 agent/skills/tailwind/references/theme-color-scheme.md create mode 100644 agent/skills/tailwind/references/theme-dark-mode-class.md create mode 100644 agent/skills/tailwind/references/theme-prefix-variables.md create mode 100644 agent/skills/tailwind/references/theme-runtime-variables.md create mode 100644 agent/skills/tailwind/references/theme-semantic-tokens.md create mode 100644 agent/skills/tailwind/references/util-explicit-colors.md create mode 100644 agent/skills/tailwind/references/util-gradient-via-none.md create mode 100644 agent/skills/tailwind/references/util-important-modifier.md create mode 100644 agent/skills/tailwind/references/util-opacity-modifier.md create mode 100644 agent/skills/tailwind/references/util-renamed-utilities.md create mode 100644 agent/skills/tailwind/references/util-variant-stacking.md create mode 100644 agent/skills/tanstack-query/SKILL.md create mode 100644 agent/skills/tanstack-query/references/cache-enabled-option.md create mode 100644 agent/skills/tanstack-query/references/cache-global-defaults.md create mode 100644 agent/skills/tanstack-query/references/cache-invalidation-precision.md create mode 100644 agent/skills/tanstack-query/references/cache-placeholder-vs-initial.md create mode 100644 agent/skills/tanstack-query/references/cache-refetch-triggers.md create mode 100644 agent/skills/tanstack-query/references/cache-staletime-gctime.md create mode 100644 agent/skills/tanstack-query/references/error-conditional-retry.md create mode 100644 agent/skills/tanstack-query/references/error-display-patterns.md create mode 100644 agent/skills/tanstack-query/references/error-global-handler.md create mode 100644 agent/skills/tanstack-query/references/error-retry-config.md create mode 100644 agent/skills/tanstack-query/references/error-throw-on-error.md create mode 100644 agent/skills/tanstack-query/references/infinite-flatten-pages.md create mode 100644 agent/skills/tanstack-query/references/infinite-loading-states.md create mode 100644 agent/skills/tanstack-query/references/infinite-max-pages.md create mode 100644 agent/skills/tanstack-query/references/infinite-refetch-behavior.md create mode 100644 agent/skills/tanstack-query/references/mutation-avoid-parallel.md create mode 100644 agent/skills/tanstack-query/references/mutation-cancel-queries.md create mode 100644 agent/skills/tanstack-query/references/mutation-invalidate-onsettled.md create mode 100644 agent/skills/tanstack-query/references/mutation-optimistic-updates.md create mode 100644 agent/skills/tanstack-query/references/mutation-setquerydata.md create mode 100644 agent/skills/tanstack-query/references/prefetch-avoid-waterfalls.md create mode 100644 agent/skills/tanstack-query/references/prefetch-flatten-api.md create mode 100644 agent/skills/tanstack-query/references/prefetch-in-queryfn.md create mode 100644 agent/skills/tanstack-query/references/prefetch-infinite-query.md create mode 100644 agent/skills/tanstack-query/references/prefetch-on-hover.md create mode 100644 agent/skills/tanstack-query/references/prefetch-server-components.md create mode 100644 agent/skills/tanstack-query/references/render-notify-props.md create mode 100644 agent/skills/tanstack-query/references/render-select-derived.md create mode 100644 agent/skills/tanstack-query/references/render-select-memoize.md create mode 100644 agent/skills/tanstack-query/references/render-structural-sharing.md create mode 100644 agent/skills/tanstack-query/references/render-tracked-props.md create mode 100644 agent/skills/tanstack-query/references/suspense-boundaries-placement.md create mode 100644 agent/skills/tanstack-query/references/suspense-error-boundaries.md create mode 100644 agent/skills/tanstack-query/references/suspense-parallel-queries.md create mode 100644 agent/skills/tanstack-query/references/suspense-use-suspense-hooks.md create mode 100644 agent/skills/tanstack-query/references/tquery-always-arrays.md create mode 100644 agent/skills/tanstack-query/references/tquery-colocate-keys.md create mode 100644 agent/skills/tanstack-query/references/tquery-hierarchical-keys.md create mode 100644 agent/skills/tanstack-query/references/tquery-key-factories.md create mode 100644 agent/skills/tanstack-query/references/tquery-options-pattern.md create mode 100644 agent/skills/tanstack-query/references/tquery-serializable-objects.md create mode 100644 agent/skills/tdd/SKILL.md create mode 100644 agent/skills/tdd/references/assert-custom-matchers.md create mode 100644 agent/skills/tdd/references/assert-error-messages.md create mode 100644 agent/skills/tdd/references/assert-no-assertions-antipattern.md create mode 100644 agent/skills/tdd/references/assert-snapshot-testing.md create mode 100644 agent/skills/tdd/references/assert-specific-assertions.md create mode 100644 agent/skills/tdd/references/cycle-maintain-test-list.md create mode 100644 agent/skills/tdd/references/cycle-minimal-code-to-pass.md create mode 100644 agent/skills/tdd/references/cycle-refactor-after-green.md create mode 100644 agent/skills/tdd/references/cycle-small-increments.md create mode 100644 agent/skills/tdd/references/cycle-verify-test-fails-first.md create mode 100644 agent/skills/tdd/references/cycle-write-test-first.md create mode 100644 agent/skills/tdd/references/data-avoid-mystery-guests.md create mode 100644 agent/skills/tdd/references/data-builder-pattern.md create mode 100644 agent/skills/tdd/references/data-minimal-setup.md create mode 100644 agent/skills/tdd/references/data-unique-identifiers.md create mode 100644 agent/skills/tdd/references/data-use-factories.md create mode 100644 agent/skills/tdd/references/design-aaa-pattern.md create mode 100644 agent/skills/tdd/references/design-avoid-logic-in-tests.md create mode 100644 agent/skills/tdd/references/design-descriptive-test-names.md create mode 100644 agent/skills/tdd/references/design-one-assertion-per-test.md create mode 100644 agent/skills/tdd/references/design-test-behavior-not-implementation.md create mode 100644 agent/skills/tdd/references/design-test-edge-cases.md create mode 100644 agent/skills/tdd/references/isolate-deterministic-tests.md create mode 100644 agent/skills/tdd/references/isolate-mock-external-dependencies.md create mode 100644 agent/skills/tdd/references/isolate-no-shared-state.md create mode 100644 agent/skills/tdd/references/isolate-prefer-stubs-over-mocks.md create mode 100644 agent/skills/tdd/references/isolate-use-dependency-injection.md create mode 100644 agent/skills/tdd/references/org-file-structure.md create mode 100644 agent/skills/tdd/references/org-group-by-behavior.md create mode 100644 agent/skills/tdd/references/org-parameterized-tests.md create mode 100644 agent/skills/tdd/references/org-setup-teardown.md create mode 100644 agent/skills/tdd/references/org-test-utilities.md create mode 100644 agent/skills/tdd/references/perf-avoid-network-calls.md create mode 100644 agent/skills/tdd/references/perf-avoid-sleep.md create mode 100644 agent/skills/tdd/references/perf-fast-unit-tests.md create mode 100644 agent/skills/tdd/references/perf-fix-flaky-tests.md create mode 100644 agent/skills/tdd/references/perf-parallelize-tests.md create mode 100644 agent/skills/tdd/references/strat-coverage-targets.md create mode 100644 agent/skills/tdd/references/strat-e2e-critical-paths.md create mode 100644 agent/skills/tdd/references/strat-integration-boundaries.md create mode 100644 agent/skills/tdd/references/strat-mutation-testing.md create mode 100644 agent/skills/tdd/references/strat-test-pyramid.md create mode 100644 agent/skills/typescript/SKILL.md create mode 100644 agent/skills/typescript/references/advanced-branded-types.md create mode 100644 agent/skills/typescript/references/advanced-satisfies-operator.md create mode 100644 agent/skills/typescript/references/advanced-template-literal-types.md create mode 100644 agent/skills/typescript/references/async-avoid-loop-await.md create mode 100644 agent/skills/typescript/references/async-avoid-unnecessary-async.md create mode 100644 agent/skills/typescript/references/async-defer-await.md create mode 100644 agent/skills/typescript/references/async-explicit-return-types.md create mode 100644 agent/skills/typescript/references/async-parallel-promises.md create mode 100644 agent/skills/typescript/references/mem-avoid-closure-leaks.md create mode 100644 agent/skills/typescript/references/mem-avoid-global-state.md create mode 100644 agent/skills/typescript/references/mem-cleanup-event-listeners.md create mode 100644 agent/skills/typescript/references/mem-clear-timers.md create mode 100644 agent/skills/typescript/references/mem-use-weakmap-for-metadata.md create mode 100644 agent/skills/typescript/references/module-avoid-barrel-imports.md create mode 100644 agent/skills/typescript/references/module-avoid-circular-dependencies.md create mode 100644 agent/skills/typescript/references/module-control-types-inclusion.md create mode 100644 agent/skills/typescript/references/module-dynamic-imports.md create mode 100644 agent/skills/typescript/references/module-use-type-imports.md create mode 100644 agent/skills/typescript/references/runtime-avoid-object-spread-in-loops.md create mode 100644 agent/skills/typescript/references/runtime-cache-property-access.md create mode 100644 agent/skills/typescript/references/runtime-prefer-array-methods.md create mode 100644 agent/skills/typescript/references/runtime-use-for-of-for-iteration.md create mode 100644 agent/skills/typescript/references/runtime-use-set-for-lookups.md create mode 100644 agent/skills/typescript/references/runtime-use-string-methods.md create mode 100644 agent/skills/typescript/references/safety-assertion-functions.md create mode 100644 agent/skills/typescript/references/safety-const-assertions.md create mode 100644 agent/skills/typescript/references/safety-exhaustive-checks.md create mode 100644 agent/skills/typescript/references/safety-prefer-unknown-over-any.md create mode 100644 agent/skills/typescript/references/safety-strict-null-checks.md create mode 100644 agent/skills/typescript/references/safety-use-type-guards.md create mode 100644 agent/skills/typescript/references/tscfg-enable-incremental.md create mode 100644 agent/skills/typescript/references/tscfg-exclude-properly.md create mode 100644 agent/skills/typescript/references/tscfg-isolate-modules.md create mode 100644 agent/skills/typescript/references/tscfg-project-references.md create mode 100644 agent/skills/typescript/references/tscfg-skip-lib-check.md create mode 100644 agent/skills/typescript/references/tscfg-strict-function-types.md create mode 100644 agent/skills/typescript/references/tscfg-typescript-7.md create mode 100644 agent/skills/typescript/references/type-avoid-deep-generics.md create mode 100644 agent/skills/typescript/references/type-avoid-large-unions.md create mode 100644 agent/skills/typescript/references/type-explicit-return-types.md create mode 100644 agent/skills/typescript/references/type-extract-conditional-types.md create mode 100644 agent/skills/typescript/references/type-interfaces-over-intersections.md create mode 100644 agent/skills/typescript/references/type-limit-recursion-depth.md create mode 100644 agent/skills/typescript/references/type-simplify-mapped-types.md create mode 100644 agent/skills/ui-design/SKILL.md create mode 100644 agent/skills/ui-design/references/access-alt-text.md create mode 100644 agent/skills/ui-design/references/access-aria-labels.md create mode 100644 agent/skills/ui-design/references/access-focus-indicators.md create mode 100644 agent/skills/ui-design/references/access-heading-hierarchy.md create mode 100644 agent/skills/ui-design/references/access-keyboard-navigation.md create mode 100644 agent/skills/ui-design/references/access-semantic-html.md create mode 100644 agent/skills/ui-design/references/access-target-size.md create mode 100644 agent/skills/ui-design/references/anim-duration-easing.md create mode 100644 agent/skills/ui-design/references/anim-gpu-properties.md create mode 100644 agent/skills/ui-design/references/anim-reduced-motion.md create mode 100644 agent/skills/ui-design/references/anim-will-change.md create mode 100644 agent/skills/ui-design/references/color-contrast-ratio.md create mode 100644 agent/skills/ui-design/references/color-dark-mode.md create mode 100644 agent/skills/ui-design/references/color-not-only-indicator.md create mode 100644 agent/skills/ui-design/references/color-semantic-palette.md create mode 100644 agent/skills/ui-design/references/cwv-critical-css.md create mode 100644 agent/skills/ui-design/references/cwv-improve-inp.md create mode 100644 agent/skills/ui-design/references/cwv-lazy-load-offscreen.md create mode 100644 agent/skills/ui-design/references/cwv-minimize-cls.md create mode 100644 agent/skills/ui-design/references/cwv-optimize-lcp.md create mode 100644 agent/skills/ui-design/references/cwv-responsive-images.md create mode 100644 agent/skills/ui-design/references/form-autocomplete.md create mode 100644 agent/skills/ui-design/references/form-error-messages.md create mode 100644 agent/skills/ui-design/references/form-inline-validation.md create mode 100644 agent/skills/ui-design/references/form-input-types.md create mode 100644 agent/skills/ui-design/references/form-labels-above.md create mode 100644 agent/skills/ui-design/references/layout-f-pattern.md create mode 100644 agent/skills/ui-design/references/layout-grid-system.md create mode 100644 agent/skills/ui-design/references/layout-proximity-grouping.md create mode 100644 agent/skills/ui-design/references/layout-single-cta.md create mode 100644 agent/skills/ui-design/references/layout-visual-hierarchy.md create mode 100644 agent/skills/ui-design/references/layout-whitespace.md create mode 100644 agent/skills/ui-design/references/resp-container-queries.md create mode 100644 agent/skills/ui-design/references/resp-fluid-typography.md create mode 100644 agent/skills/ui-design/references/resp-mobile-first.md create mode 100644 agent/skills/ui-design/references/resp-touch-targets.md create mode 100644 agent/skills/ui-design/references/resp-viewport-meta.md create mode 100644 agent/skills/ui-design/references/typo-font-display.md create mode 100644 agent/skills/ui-design/references/typo-line-height.md create mode 100644 agent/skills/ui-design/references/typo-preload-fonts.md create mode 100644 agent/skills/ui-design/references/typo-readable-line-length.md create mode 100644 agent/skills/ui-design/references/typo-system-font-stack.md create mode 100644 agent/skills/vercel-composition-patterns/SKILL.md create mode 100644 agent/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md create mode 100644 agent/skills/vercel-composition-patterns/rules/architecture-compound-components.md create mode 100644 agent/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md create mode 100644 agent/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md create mode 100644 agent/skills/vercel-composition-patterns/rules/react19-no-forwardref.md create mode 100644 agent/skills/vercel-composition-patterns/rules/state-context-interface.md create mode 100644 agent/skills/vercel-composition-patterns/rules/state-decouple-implementation.md create mode 100644 agent/skills/vercel-composition-patterns/rules/state-lift-state.md create mode 100644 agent/skills/vercel-react-best-practices/SKILL.md create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-init-once.md create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-use-latest.md create mode 100644 agent/skills/vercel-react-best-practices/rules/async-api-routes.md create mode 100644 agent/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md create mode 100644 agent/skills/vercel-react-best-practices/rules/async-defer-await.md create mode 100644 agent/skills/vercel-react-best-practices/rules/async-dependencies.md create mode 100644 agent/skills/vercel-react-best-practices/rules/async-parallel.md create mode 100644 agent/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-conditional.md create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-preload.md create mode 100644 agent/skills/vercel-react-best-practices/rules/client-event-listeners.md create mode 100644 agent/skills/vercel-react-best-practices/rules/client-localstorage-schema.md create mode 100644 agent/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md create mode 100644 agent/skills/vercel-react-best-practices/rules/client-swr-dedup.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-batch-dom-css.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-cache-function-results.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-cache-property-access.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-cache-storage.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-combine-iterations.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-early-exit.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-flatmap-filter.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-hoist-regexp.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-index-maps.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-length-check-first.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-min-max-loop.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-request-idle-callback.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-set-map-lookups.md create mode 100644 agent/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-activity.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-conditional-render.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-content-visibility.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-resource-hints.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-svg-precision.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-defer-reads.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-dependencies.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-derived-state.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-memo.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-transitions.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-after-nonblocking.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-auth-actions.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-cache-lru.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-cache-react.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-dedup-props.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-hoist-static-io.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-parallel-fetching.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md create mode 100644 agent/skills/vercel-react-best-practices/rules/server-serialization.md create mode 100644 agent/skills/vitest/SKILL.md create mode 100644 agent/skills/vitest/references/assert-edge-cases.md create mode 100644 agent/skills/vitest/references/assert-expect-assertions.md create mode 100644 agent/skills/vitest/references/assert-one-assertion-concept.md create mode 100644 agent/skills/vitest/references/assert-specific-matchers.md create mode 100644 agent/skills/vitest/references/assert-toequal-vs-tobe.md create mode 100644 agent/skills/vitest/references/async-act-wrapper.md create mode 100644 agent/skills/vitest/references/async-await-assertions.md create mode 100644 agent/skills/vitest/references/async-concurrent-expect.md create mode 100644 agent/skills/vitest/references/async-error-handling.md create mode 100644 agent/skills/vitest/references/async-fake-timers.md create mode 100644 agent/skills/vitest/references/async-return-promises.md create mode 100644 agent/skills/vitest/references/async-waitfor-polling.md create mode 100644 agent/skills/vitest/references/env-browser-api-mocking.md create mode 100644 agent/skills/vitest/references/env-globals-config.md create mode 100644 agent/skills/vitest/references/env-per-file-override.md create mode 100644 agent/skills/vitest/references/env-setup-files.md create mode 100644 agent/skills/vitest/references/mock-avoid-overmocking.md create mode 100644 agent/skills/vitest/references/mock-clear-between-tests.md create mode 100644 agent/skills/vitest/references/mock-implementation-not-value.md create mode 100644 agent/skills/vitest/references/mock-msw-network.md create mode 100644 agent/skills/vitest/references/mock-spyon-vs-mock.md create mode 100644 agent/skills/vitest/references/mock-type-safety.md create mode 100644 agent/skills/vitest/references/mock-vi-mock-hoisting.md create mode 100644 agent/skills/vitest/references/org-describe-nesting.md create mode 100644 agent/skills/vitest/references/org-file-colocation.md create mode 100644 agent/skills/vitest/references/org-test-naming.md create mode 100644 agent/skills/vitest/references/org-test-skip-only.md create mode 100644 agent/skills/vitest/references/perf-bail-fast-fail.md create mode 100644 agent/skills/vitest/references/perf-bench-test-context.md create mode 100644 agent/skills/vitest/references/perf-disable-isolation.md create mode 100644 agent/skills/vitest/references/perf-happy-dom.md create mode 100644 agent/skills/vitest/references/perf-pool-selection.md create mode 100644 agent/skills/vitest/references/perf-run-mode-ci.md create mode 100644 agent/skills/vitest/references/perf-sharding.md create mode 100644 agent/skills/vitest/references/setup-avoid-shared-state.md create mode 100644 agent/skills/vitest/references/setup-beforeall-expensive.md create mode 100644 agent/skills/vitest/references/setup-beforeeach-cleanup.md create mode 100644 agent/skills/vitest/references/setup-reset-modules.md create mode 100644 agent/skills/vitest/references/setup-restore-mocks.md create mode 100644 agent/skills/vitest/references/setup-test-factories.md create mode 100644 agent/skills/vitest/references/setup-vitest5-migration.md create mode 100644 agent/skills/vitest/references/snap-avoid-large.md create mode 100644 agent/skills/vitest/references/snap-describe-intent.md create mode 100644 agent/skills/vitest/references/snap-inline-over-file.md create mode 100644 agent/skills/vitest/references/snap-review-updates.md create mode 100644 agent/skills/vitest/references/snap-stable-serialization.md create mode 100644 agent/skills/web-design-guidelines/SKILL.md create mode 100644 agent/skills/zod/SKILL.md create mode 100644 agent/skills/zod/references/compose-intersection.md create mode 100644 agent/skills/zod/references/compose-lazy-recursive.md create mode 100644 agent/skills/zod/references/compose-pipe.md create mode 100644 agent/skills/zod/references/compose-preprocess.md create mode 100644 agent/skills/zod/references/compose-shared-schemas.md create mode 100644 agent/skills/zod/references/error-avoid-throwing-in-refine.md create mode 100644 agent/skills/zod/references/error-custom-messages.md create mode 100644 agent/skills/zod/references/error-i18n.md create mode 100644 agent/skills/zod/references/error-path-for-nested.md create mode 100644 agent/skills/zod/references/error-use-flatten.md create mode 100644 agent/skills/zod/references/object-discriminated-unions.md create mode 100644 agent/skills/zod/references/object-extend-for-composition.md create mode 100644 agent/skills/zod/references/object-optional-vs-nullable.md create mode 100644 agent/skills/zod/references/object-partial-for-updates.md create mode 100644 agent/skills/zod/references/object-pick-omit.md create mode 100644 agent/skills/zod/references/object-strict-vs-strip.md create mode 100644 agent/skills/zod/references/parse-async-for-async-refinements.md create mode 100644 agent/skills/zod/references/parse-avoid-double-validation.md create mode 100644 agent/skills/zod/references/parse-handle-all-issues.md create mode 100644 agent/skills/zod/references/parse-never-trust-json.md create mode 100644 agent/skills/zod/references/parse-use-safeparse.md create mode 100644 agent/skills/zod/references/parse-validate-early.md create mode 100644 agent/skills/zod/references/parse-validate-for-boolean-checks.md create mode 100644 agent/skills/zod/references/perf-arrays.md create mode 100644 agent/skills/zod/references/perf-avoid-dynamic-creation.md create mode 100644 agent/skills/zod/references/perf-cache-schemas.md create mode 100644 agent/skills/zod/references/perf-compile-schemas.md create mode 100644 agent/skills/zod/references/perf-lazy-loading.md create mode 100644 agent/skills/zod/references/perf-zod-mini.md create mode 100644 agent/skills/zod/references/refine-add-path.md create mode 100644 agent/skills/zod/references/refine-catch.md create mode 100644 agent/skills/zod/references/refine-defaults.md create mode 100644 agent/skills/zod/references/refine-transform-coerce.md create mode 100644 agent/skills/zod/references/refine-use-codec.md create mode 100644 agent/skills/zod/references/refine-vs-superrefine.md create mode 100644 agent/skills/zod/references/schema-avoid-optional-abuse.md create mode 100644 agent/skills/zod/references/schema-coercion-for-form-data.md create mode 100644 agent/skills/zod/references/schema-string-validations.md create mode 100644 agent/skills/zod/references/schema-use-enums.md create mode 100644 agent/skills/zod/references/schema-use-primitives-correctly.md create mode 100644 agent/skills/zod/references/schema-use-unknown-not-any.md create mode 100644 agent/skills/zod/references/type-branded-types.md create mode 100644 agent/skills/zod/references/type-enable-strict-mode.md create mode 100644 agent/skills/zod/references/type-export-schemas-and-types.md create mode 100644 agent/skills/zod/references/type-input-vs-output.md create mode 100644 agent/skills/zod/references/type-use-z-infer.md create mode 100644 certs/.gitignore create mode 100644 compose.dbs.yaml create mode 100644 compose.yaml create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/DESIGN.md create mode 100644 docs/MIGRATION.md create mode 100644 docs/OPERATIONS.md create mode 100644 docs/PRODUCT.md create mode 100644 docs/README_PL.md create mode 100644 docs/ROADMAP.md create mode 100644 docs/SECURITY.md rename BackupService_MapaMysli.png => docs/diagrams/BackupService_MapaMysli.png (100%) rename ServiceLogicProject.drawio => docs/diagrams/ServiceLogicProject.drawio (100%) rename ServiceLogicProject_v1.0_Drawio.jpg => docs/diagrams/ServiceLogicProject_v1.0_Drawio.jpg (100%) rename ServiceLogicProject_v1.2_Drawio.png => docs/diagrams/ServiceLogicProject_v1.2_Drawio.png (100%) create mode 100644 global.json create mode 100644 scripts/check-compose.mjs create mode 100644 scripts/dev.mjs create mode 100644 skills-lock.json diff --git a/.agents/skills/feature-arch/SKILL.md b/.agents/skills/feature-arch/SKILL.md new file mode 100644 index 0000000..f9552bc --- /dev/null +++ b/.agents/skills/feature-arch/SKILL.md @@ -0,0 +1,110 @@ +--- +name: feature-arch +description: Feature-based React folder structure and module boundaries. +--- + +# Feature-Based Architecture Best Practices + +Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 42 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions). + +## When to Apply + +Reference these guidelines when: +- Creating new features or modules +- Organizing project directory structure +- Setting up import rules and boundaries +- Implementing data fetching patterns +- Composing components from multiple features +- Reviewing code for architecture violations + +## Rule Categories by Priority + +| Priority | Category | Impact | Prefix | +|----------|----------|--------|--------| +| 1 | Directory Structure | CRITICAL | `struct-` | +| 2 | Import & Dependencies | CRITICAL | `import-` | +| 3 | Module Boundaries | HIGH | `bound-` | +| 4 | Data Fetching | HIGH | `fquery-` | +| 5 | Component Organization | MEDIUM-HIGH | `fcomp-` | +| 6 | State Management | MEDIUM | `fstate-` | +| 7 | Testing Strategy | MEDIUM | `test-` | +| 8 | Naming Conventions | LOW | `name-` | + +## Quick Reference + +### 1. Directory Structure (CRITICAL) + +- `struct-feature-folders` - Organize by feature, not technical type +- `struct-feature-self-contained` - Make features self-contained +- `struct-shared-layer` - Use shared layer for truly generic code only +- `struct-flat-hierarchy` - Keep directory hierarchy flat +- `struct-optional-segments` - Include only necessary segments +- `struct-app-layer` - Separate app layer from features + +### 2. Import & Dependencies (CRITICAL) + +- `import-unidirectional-flow` - Enforce unidirectional import flow +- `import-no-cross-feature` - Prohibit cross-feature imports +- `import-public-api` - Export through public API only +- `import-avoid-barrel-files` - Avoid deep barrel file re-exports +- `import-path-aliases` - Use consistent path aliases +- `import-type-only` - Use type-only imports for types + +### 3. Module Boundaries (HIGH) + +- `bound-feature-isolation` - Enforce feature isolation +- `bound-interface-contracts` - Define explicit interface contracts +- `bound-feature-scoped-routing` - Scope routing to feature concerns +- `bound-minimize-shared-state` - Minimize shared state between features +- `bound-event-based-communication` - Use events for cross-feature communication +- `bound-feature-size` - Keep features appropriately sized + +### 4. Data Fetching (HIGH) + +- `fquery-single-responsibility` - Keep query functions single-purpose +- `fquery-colocate-with-feature` - Colocate data fetching with features +- `fquery-parallel-fetching` - Fetch independent data in parallel +- `fquery-avoid-n-plus-one` - Avoid N+1 query patterns +- `fquery-feature-scoped-keys` - Use feature-scoped query keys +- `fquery-server-component-fetching` - Fetch at server component level + +### 5. Component Organization (MEDIUM-HIGH) + +- `fcomp-single-responsibility` - Apply single responsibility to components +- `fcomp-composition-over-props` - Prefer composition over prop drilling +- `fcomp-container-presentational` - Separate container and presentational concerns +- `fcomp-props-as-data-boundary` - Use props as feature boundaries +- `fcomp-colocate-styles` - Colocate styles with components +- `fcomp-error-boundaries` - Use feature-level error boundaries + +### 6. State Management (MEDIUM) + +- `fstate-feature-scoped-stores` - Scope state stores to features +- `fstate-server-state-separation` - Separate server state from client state +- `fstate-lift-minimally` - Lift state only as high as necessary +- `fstate-context-sparingly` - Use context sparingly for feature state +- `fstate-reset-on-unmount` - Reset feature state on unmount + +### 7. Testing Strategy (MEDIUM) + +- `test-colocate-with-feature` - Colocate tests with features +- `test-feature-isolation` - Test features in isolation +- `test-shared-utilities` - Create feature-specific test utilities +- `test-integration-at-app-layer` - Write integration tests at app layer + +### 8. Naming Conventions (LOW) + +- `name-feature-naming` - Use domain-driven feature names +- `name-file-conventions` - Use consistent file naming conventions +- `name-descriptive-exports` - Use descriptive export names + +## How to Use + +Read `references/.md` for each rule above that matches the task: why it matters, then incorrect vs. correct code. + +The layering and boundary rules align with Feature-Sliced Design (FSD), the most widely adopted React architecture standard; see [feature-sliced.design](https://feature-sliced.design/) for the full methodology. + +## Related Skills + +- For data fetching, see `tanstack-query` skill +- For React component patterns, see `react` skill diff --git a/.agents/skills/feature-arch/references/bound-event-based-communication.md b/.agents/skills/feature-arch/references/bound-event-based-communication.md new file mode 100644 index 0000000..9fc72ed --- /dev/null +++ b/.agents/skills/feature-arch/references/bound-event-based-communication.md @@ -0,0 +1,84 @@ +--- +title: Use Events for Cross-Feature Communication +impact: MEDIUM-HIGH +impactDescription: Decouples features at runtime; enables loose coupling without direct imports +tags: bound, events, communication, decoupling +--- + +## Use Events for Cross-Feature Communication + +When features must communicate without direct dependencies, use an event-based approach. This keeps features loosely coupled while allowing them to react to each other's actions. + +**Incorrect (direct coupling):** + +```typescript +// src/features/order/hooks/useOrder.ts +import { clearCart } from '@/features/cart/stores/cartStore'; +import { showNotification } from '@/features/notification/stores/notificationStore'; +import { sendAnalytics } from '@/features/analytics/utils/analytics'; + +export function useOrder() { + async function submitOrder(data: OrderData) { + const order = await createOrder(data); + + // Directly calling into other features + clearCart(); + showNotification({ type: 'success', message: 'Order placed!' }); + sendAnalytics('order_completed', { orderId: order.id }); + } +} +``` + +**Correct (event-based communication):** + +```typescript +// src/shared/events/eventBus.ts +type EventMap = { + 'order:completed': { orderId: string; total: number }; + 'order:failed': { error: string }; + 'user:logged-in': { userId: string }; + 'user:logged-out': void; +}; + +export const eventBus = createEventBus(); + +// src/features/order/hooks/useOrder.ts +import { eventBus } from '@/shared/events/eventBus'; + +export function useOrder() { + async function submitOrder(data: OrderData) { + const order = await createOrder(data); + eventBus.emit('order:completed', { orderId: order.id, total: order.total }); + } +} + +// src/features/cart/hooks/useCartSync.ts +import { eventBus } from '@/shared/events/eventBus'; +import { useCartStore } from '../stores/cartStore'; + +export function useCartSync() { + useEffect(() => { + return eventBus.on('order:completed', () => { + useCartStore.getState().clearCart(); + }); + }, []); +} + +// src/features/notification/hooks/useOrderNotifications.ts +import { eventBus } from '@/shared/events/eventBus'; + +export function useOrderNotifications() { + useEffect(() => { + return eventBus.on('order:completed', ({ orderId }) => { + showNotification({ type: 'success', message: `Order ${orderId} placed!` }); + }); + }, []); +} +``` + +**Benefits:** +- Order feature doesn't know about cart, notifications, or analytics +- New features can subscribe to events without modifying order +- Easy to test each feature in isolation + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/bound-feature-isolation.md b/.agents/skills/feature-arch/references/bound-feature-isolation.md new file mode 100644 index 0000000..74182c0 --- /dev/null +++ b/.agents/skills/feature-arch/references/bound-feature-isolation.md @@ -0,0 +1,88 @@ +--- +title: Enforce Feature Isolation +impact: HIGH +impactDescription: Changes in one feature have zero impact on others; enables fearless refactoring +tags: bound, isolation, coupling, independence +--- + +## Enforce Feature Isolation + +Each feature should be modifiable, testable, and deployable without affecting other features. When features are isolated, refactoring is safe and localized. When they're coupled, every change risks cascading failures. + +**Incorrect (coupled features):** + +```typescript +// src/features/order/hooks/useOrder.ts +import { useCart } from '@/features/cart/hooks/useCart'; +import { useUser } from '@/features/user/hooks/useUser'; +import { usePayment } from '@/features/payment/hooks/usePayment'; + +export function useOrder() { + const cart = useCart(); + const user = useUser(); + const payment = usePayment(); + + // Tightly coupled to 3 other features + // Change in any feature can break orders + async function submitOrder() { + const order = { + items: cart.items, + userId: user.id, + paymentMethod: payment.selectedMethod, + }; + // ... + } +} +``` + +**Correct (isolated with dependency injection):** + +```typescript +// src/features/order/hooks/useOrder.ts +interface OrderDependencies { + items: CartItem[]; + userId: string; + paymentMethod: PaymentMethod; +} + +export function useOrder() { + async function submitOrder(deps: OrderDependencies) { + const order = { + items: deps.items, + userId: deps.userId, + paymentMethod: deps.paymentMethod, + }; + // ... + } + + return { submitOrder }; +} + +// src/app/pages/CheckoutPage.tsx - composition at app layer +import { useCart } from '@/features/cart'; +import { useUser } from '@/features/user'; +import { usePayment } from '@/features/payment'; +import { useOrder } from '@/features/order'; + +export function CheckoutPage() { + const cart = useCart(); + const user = useUser(); + const payment = usePayment(); + const order = useOrder(); + + const handleSubmit = () => { + order.submitOrder({ + items: cart.items, + userId: user.id, + paymentMethod: payment.selectedMethod, + }); + }; +} +``` + +**Benefits:** +- Order feature can be tested with mock dependencies +- Cart, user, and payment can change without breaking orders +- Clear contract between features + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/bound-feature-scoped-routing.md b/.agents/skills/feature-arch/references/bound-feature-scoped-routing.md new file mode 100644 index 0000000..69e00bb --- /dev/null +++ b/.agents/skills/feature-arch/references/bound-feature-scoped-routing.md @@ -0,0 +1,76 @@ +--- +title: Scope Routing to Feature Concerns +impact: HIGH +impactDescription: Enables feature-level code splitting; prevents routing configuration sprawl +tags: bound, routing, scope, navigation +--- + +## Scope Routing to Feature Concerns + +Route definitions belong in the app layer, but route parameters and navigation logic relevant to a feature can be encapsulated within that feature. This keeps routing concerns organized while maintaining the app layer's ownership of the route tree. + +**Incorrect (routing logic scattered):** + +```typescript +// src/features/user/components/UserProfile.tsx +import { useNavigate, useParams } from 'react-router-dom'; + +export function UserProfile() { + const navigate = useNavigate(); + const { userId } = useParams(); // Feature assumes route structure + + const goToSettings = () => { + navigate(`/users/${userId}/settings`); // Hardcoded route + }; +} +``` + +**Correct (feature owns its route utilities):** + +```typescript +// src/features/user/routes.ts +export const userRoutes = { + profile: (userId: string) => `/users/${userId}`, + settings: (userId: string) => `/users/${userId}/settings`, + orders: (userId: string) => `/users/${userId}/orders`, +} as const; + +// src/features/user/hooks/useUserParams.ts +import { useParams } from 'react-router-dom'; + +export function useUserParams() { + const { userId } = useParams<{ userId: string }>(); + if (!userId) throw new Error('userId is required'); + return { userId }; +} + +// src/features/user/components/UserProfile.tsx +import { useNavigate } from 'react-router-dom'; +import { userRoutes } from '../routes'; +import { useUserParams } from '../hooks/useUserParams'; + +export function UserProfile() { + const navigate = useNavigate(); + const { userId } = useUserParams(); + + const goToSettings = () => { + navigate(userRoutes.settings(userId)); // Uses feature's route builder + }; +} + +// src/app/routes/index.tsx +import { userRoutes } from '@/features/user'; +import { UserProfile, UserSettings } from '@/features/user'; + +export const routes = [ + { path: userRoutes.profile(':userId'), element: }, + { path: userRoutes.settings(':userId'), element: }, +]; +``` + +**Benefits:** +- Route paths are centralized per feature +- Refactoring routes only requires changes in one place +- Type-safe route parameters + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/bound-feature-size.md b/.agents/skills/feature-arch/references/bound-feature-size.md new file mode 100644 index 0000000..c8895fe --- /dev/null +++ b/.agents/skills/feature-arch/references/bound-feature-size.md @@ -0,0 +1,74 @@ +--- +title: Keep Features Appropriately Sized +impact: MEDIUM +impactDescription: Right-sized features balance cohesion and manageability +tags: bound, size, cohesion, splitting +--- + +## Keep Features Appropriately Sized + +Features should be large enough to be meaningful but small enough to be maintainable. A feature that's too small creates unnecessary fragmentation; one that's too large becomes a mini-monolith. + +**Incorrect (too granular):** + +``` +src/features/ +├── user-avatar/ # Too small - just one component +├── user-name/ # Too small +├── user-email/ # Too small +├── user-profile/ # Could contain all of these +└── user-settings/ +``` + +**Incorrect (too large):** + +``` +src/features/ +└── user/ + ├── components/ + │ ├── UserAvatar.tsx + │ ├── UserProfile.tsx + │ ├── UserSettings.tsx + │ ├── UserOrders.tsx # Orders is a separate domain + │ ├── UserPayments.tsx # Payments is a separate domain + │ ├── UserSubscription.tsx # Subscription is a separate domain + │ └── ... 30 more files + └── hooks/ + └── ... 20 hooks +``` + +**Correct (cohesive features):** + +``` +src/features/ +├── user/ # Core user identity +│ ├── components/ +│ │ ├── UserAvatar.tsx +│ │ ├── UserProfile.tsx +│ │ └── UserSettings.tsx +│ └── hooks/ +│ └── useUser.ts +├── orders/ # Separate domain +│ ├── components/ +│ │ ├── OrderList.tsx +│ │ └── OrderDetail.tsx +│ └── hooks/ +│ └── useOrders.ts +├── payments/ # Separate domain +│ └── ... +└── subscription/ # Separate domain + └── ... +``` + +**Sizing guidelines:** +- 5-15 components per feature is typical +- If a feature has 20+ files, consider splitting +- If a feature has only 1-2 files, consider merging +- Features should map to business domains, not UI components + +**Signs a feature is too large:** +- Multiple developers frequently conflict in the same feature +- Parts of the feature change at different rates +- Some parts are used independently of others + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/bound-interface-contracts.md b/.agents/skills/feature-arch/references/bound-interface-contracts.md new file mode 100644 index 0000000..ac07bd4 --- /dev/null +++ b/.agents/skills/feature-arch/references/bound-interface-contracts.md @@ -0,0 +1,83 @@ +--- +title: Define Explicit Interface Contracts +impact: HIGH +impactDescription: Prevents implicit dependencies; enables parallel feature development +tags: bound, interfaces, contracts, types +--- + +## Define Explicit Interface Contracts + +When features need to interact, define explicit interfaces that describe the contract. This makes dependencies visible and allows features to be developed in parallel against the contract. + +**Incorrect (implicit interface):** + +```typescript +// src/features/checkout/components/CheckoutForm.tsx +export function CheckoutForm({ onSuccess }) { + // What shape does onSuccess expect? + // What data should be passed? + const handleSubmit = () => { + onSuccess(someData); // Caller must guess the shape + }; +} +``` + +**Correct (explicit contract):** + +```typescript +// src/features/checkout/types.ts +export interface CheckoutResult { + orderId: string; + total: number; + items: Array<{ id: string; quantity: number }>; +} + +export interface CheckoutFormProps { + userId: string; + cartItems: CartItem[]; + onSuccess: (result: CheckoutResult) => void; + onError: (error: CheckoutError) => void; +} + +// src/features/checkout/components/CheckoutForm.tsx +export function CheckoutForm({ userId, cartItems, onSuccess, onError }: CheckoutFormProps) { + const handleSubmit = async () => { + try { + const result = await processCheckout(userId, cartItems); + onSuccess({ + orderId: result.id, + total: result.total, + items: result.items.map(i => ({ id: i.id, quantity: i.qty })), + }); + } catch (err) { + onError(normalizeError(err)); + } + }; +} +``` + +**Contract patterns:** + +```typescript +// Render prop contract +interface UserListProps { + renderUser: (user: User) => ReactNode; + renderEmpty?: () => ReactNode; +} + +// Slot contract +interface DashboardProps { + header: ReactNode; + sidebar: ReactNode; + content: ReactNode; +} + +// Data contract +interface AnalyticsEvent { + name: string; + properties: Record; + timestamp: number; +} +``` + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/bound-minimize-shared-state.md b/.agents/skills/feature-arch/references/bound-minimize-shared-state.md new file mode 100644 index 0000000..2ec1e12 --- /dev/null +++ b/.agents/skills/feature-arch/references/bound-minimize-shared-state.md @@ -0,0 +1,73 @@ +--- +title: Minimize Shared State Between Features +impact: HIGH +impactDescription: Reduces coupling surface area; prevents state synchronization bugs +tags: bound, state, coupling, shared +--- + +## Minimize Shared State Between Features + +When multiple features share state, they become implicitly coupled. Changes to that state affect all dependent features. Prefer passing data as props or using feature-local state with explicit synchronization points. + +**Incorrect (shared global state):** + +```typescript +// src/stores/globalStore.ts +export const globalStore = create((set) => ({ + user: null, + cart: { items: [] }, + notifications: [], + theme: 'light', + // Every feature reaches into this store +})); + +// src/features/checkout/components/CheckoutForm.tsx +import { globalStore } from '@/stores/globalStore'; + +export function CheckoutForm() { + const cart = globalStore(s => s.cart); + const user = globalStore(s => s.user); + // Checkout is now coupled to global store shape +} +``` + +**Correct (feature-scoped state with explicit boundaries):** + +```typescript +// src/features/cart/stores/cartStore.ts +export const useCartStore = create((set) => ({ + items: [], + addItem: (item) => set(s => ({ items: [...s.items, item] })), + removeItem: (id) => set(s => ({ items: s.items.filter(i => i.id !== id) })), +})); + +// src/features/cart/index.ts +export { useCartStore } from './stores/cartStore'; +export type { CartItem } from './types'; + +// src/app/pages/CheckoutPage.tsx +import { useCartStore } from '@/features/cart'; +import { CheckoutForm } from '@/features/checkout'; + +export function CheckoutPage() { + const items = useCartStore(s => s.items); + // App layer reads cart and passes to checkout + return ; +} + +// src/features/checkout/components/CheckoutForm.tsx +interface CheckoutFormProps { + items: CartItem[]; // Receives data via props, not global state +} + +export function CheckoutForm({ items }: CheckoutFormProps) { + // No knowledge of cart store +} +``` + +**When shared state is acceptable:** +- Auth state (current user) - rarely changes, many features need it +- Theme/locale - application-wide concerns +- Feature flags - read-only, system-level + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/fcomp-colocate-styles.md b/.agents/skills/feature-arch/references/fcomp-colocate-styles.md new file mode 100644 index 0000000..c078fc0 --- /dev/null +++ b/.agents/skills/feature-arch/references/fcomp-colocate-styles.md @@ -0,0 +1,88 @@ +--- +title: Colocate Styles with Components +impact: MEDIUM +impactDescription: Enables complete component portability; prevents orphaned styles +tags: comp, styles, colocation, css +--- + +## Colocate Styles with Components + +Keep component styles in the same location as the component. When styles are centralized or in a global stylesheet, components lose independence and style changes become risky. + +**Incorrect (centralized styles):** + +``` +src/ +├── styles/ +│ ├── components/ +│ │ ├── UserCard.css +│ │ ├── PostList.css +│ │ └── CommentSection.css +│ └── global.css +└── features/ + └── user/ + └── components/ + └── UserCard.tsx # Imports from ../../styles/components/ +``` + +**Correct (colocated styles):** + +``` +src/features/user/ +├── components/ +│ ├── UserCard.tsx +│ ├── UserCard.module.css # CSS Modules +│ └── UserAvatar.tsx +└── ... +``` + +```typescript +// src/features/user/components/UserCard.tsx +import styles from './UserCard.module.css'; + +export function UserCard({ user }: { user: User }) { + return ( +
+ +

{user.name}

+
+ ); +} +``` + +**With Tailwind (styles in component):** + +```typescript +// src/features/user/components/UserCard.tsx +export function UserCard({ user }: { user: User }) { + return ( +
+ +

{user.name}

+
+ ); +} +``` + +**Shared styles belong in shared:** + +``` +src/shared/ +├── styles/ +│ ├── reset.css # Global reset +│ └── variables.css # Design tokens +└── components/ + ├── Button/ + │ ├── Button.tsx + │ └── Button.module.css + └── Input/ + ├── Input.tsx + └── Input.module.css +``` + +**Benefits:** +- Moving a component moves its styles +- Deleting a component deletes its styles +- No orphaned CSS + +Reference: [CSS Modules Documentation](https://github.com/css-modules/css-modules) diff --git a/.agents/skills/feature-arch/references/fcomp-composition-over-props.md b/.agents/skills/feature-arch/references/fcomp-composition-over-props.md new file mode 100644 index 0000000..7d7b2f7 --- /dev/null +++ b/.agents/skills/feature-arch/references/fcomp-composition-over-props.md @@ -0,0 +1,100 @@ +--- +title: Prefer Composition Over Prop Drilling +impact: MEDIUM-HIGH +impactDescription: Eliminates prop drilling; enables flexible slot-based component design +tags: comp, composition, children, slots +--- + +## Prefer Composition Over Prop Drilling + +When components need to render content from different features, use composition (children, render props, slots) instead of passing data down through multiple layers. This keeps components decoupled and flexible. + +**Incorrect (prop drilling):** + +```typescript +// Props must pass through every layer +function Page({ user, cart, notifications }) { + return ; +} + +function Layout({ user, cart, notifications }) { + return ( +
+
+ +
+ ); +} + +function Header({ user, cart, notifications }) { + return ( +
+ + + +
+ ); +} +``` + +**Correct (composition with slots):** + +```typescript +// Layout accepts composed children +interface LayoutProps { + header: ReactNode; + children: ReactNode; +} + +function Layout({ header, children }: LayoutProps) { + return ( +
+
{header}
+
{children}
+
+ ); +} + +// Page composes features at the top level +function Page() { + return ( + + {/* Feature handles its own data */} + {/* Feature handles its own data */} + {/* Feature handles its own data */} + + } + > + + + ); +} +``` + +**Render props for flexible rendering:** + +```typescript +interface DataTableProps { + data: T[]; + renderRow: (item: T) => ReactNode; + renderEmpty?: () => ReactNode; +} + +function DataTable({ data, renderRow, renderEmpty }: DataTableProps) { + if (data.length === 0) { + return renderEmpty?.() ?? ; + } + return {data.map(renderRow)}
; +} + +// Usage - feature controls rendering + } + renderEmpty={() => } +/> +``` + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/fcomp-container-presentational.md b/.agents/skills/feature-arch/references/fcomp-container-presentational.md new file mode 100644 index 0000000..8749881 --- /dev/null +++ b/.agents/skills/feature-arch/references/fcomp-container-presentational.md @@ -0,0 +1,99 @@ +--- +title: Separate Container and Presentational Concerns +impact: MEDIUM +impactDescription: Enables design system reuse; keeps business logic testable +tags: comp, container, presentational, separation +--- + +## Separate Container and Presentational Concerns + +Distinguish between components that manage data/state (containers) and components that render UI (presentational). Presentational components are reusable and easy to test; containers coordinate business logic. + +**Incorrect (mixed concerns):** + +```typescript +// Component does everything - hard to reuse or test +function UserCard() { + const [user, setUser] = useState(null); + const [isEditing, setIsEditing] = useState(false); + + useEffect(() => { + fetchUser(userId).then(setUser); + }, [userId]); + + const handleSave = async (data: UserData) => { + await updateUser(userId, data); + setUser({ ...user, ...data }); + setIsEditing(false); + }; + + if (!user) return ; + + return ( +
+ {isEditing ? ( + + ) : ( + <> + +

{user.name}

+

{user.email}

+ + + )} +
+ ); +} +``` + +**Correct (separated concerns):** + +```typescript +// Presentational - pure rendering, easy to test and reuse +interface UserCardProps { + user: User; + onEdit: () => void; +} + +function UserCard({ user, onEdit }: UserCardProps) { + return ( +
+ +

{user.name}

+

{user.email}

+ +
+ ); +} + +// Container - manages data and state +function UserCardContainer({ userId }: { userId: string }) { + const { data: user, isLoading } = useUser(userId); + const [isEditing, setIsEditing] = useState(false); + const updateMutation = useUpdateUser(); + + if (isLoading) return ; + + if (isEditing) { + return ( + { + updateMutation.mutate({ userId, data }); + setIsEditing(false); + }} + onCancel={() => setIsEditing(false)} + /> + ); + } + + return setIsEditing(true)} />; +} +``` + +**Benefits:** +- UserCard can be used in Storybook, tests, anywhere +- Business logic is concentrated in container +- Presentational components are pure functions of props + +Reference: [React Patterns - Container/Presentational](https://reactpatterns.com/) diff --git a/.agents/skills/feature-arch/references/fcomp-error-boundaries.md b/.agents/skills/feature-arch/references/fcomp-error-boundaries.md new file mode 100644 index 0000000..ea84b65 --- /dev/null +++ b/.agents/skills/feature-arch/references/fcomp-error-boundaries.md @@ -0,0 +1,99 @@ +--- +title: Use Feature-Level Error Boundaries +impact: MEDIUM +impactDescription: Isolates failures to single features; prevents full-page crashes +tags: comp, error-boundary, resilience, isolation +--- + +## Use Feature-Level Error Boundaries + +Wrap each feature's root component in an error boundary. When a feature fails, only that feature shows an error state while the rest of the page remains functional. + +**Incorrect (single app-level boundary):** + +```typescript +// Single error boundary - any feature crash takes down entire app +function App() { + return ( + }> + + + ); +} + +function Dashboard() { + return ( +
+ {/* Crash here = full page error */} + + +
+ ); +} +``` + +**Correct (feature-level boundaries):** + +```typescript +// src/shared/components/FeatureErrorBoundary.tsx +interface FeatureErrorBoundaryProps { + feature: string; + children: ReactNode; + fallback?: ReactNode; +} + +export function FeatureErrorBoundary({ + feature, + children, + fallback, +}: FeatureErrorBoundaryProps) { + return ( + } + onError={(error) => logError(error, { feature })} + > + {children} + + ); +} + +// src/app/pages/DashboardPage.tsx +function Dashboard() { + return ( +
+ + {/* Crash here = only this section shows error */} + + + + {/* Still works even if UserProfile crashed */} + + + + {/* Still works */} + +
+ ); +} +``` + +**Graceful fallback UI:** + +```typescript +function FeatureErrorFallback({ feature }: { feature: string }) { + return ( +
+

+ Unable to load {feature}. +

+
+ ); +} +``` + +**Benefits:** +- One feature failing doesn't crash the page +- Errors are attributed to specific features +- Users can continue using working features + +Reference: [React Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) diff --git a/.agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md b/.agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md new file mode 100644 index 0000000..5f38bc1 --- /dev/null +++ b/.agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md @@ -0,0 +1,88 @@ +--- +title: Use Props as Feature Boundaries +impact: MEDIUM-HIGH +impactDescription: Creates clear interfaces between features; enables feature composition +tags: comp, props, interface, boundary +--- + +## Use Props as Feature Boundaries + +When features interact, use props to define the interface. The receiving component should not know about the providing feature's internals. This creates a clear boundary that allows either side to change independently. + +**Incorrect (feature internals exposed):** + +```typescript +// Checkout component knows about Cart's internal structure +import { useCartStore } from '@/features/cart/stores/cartStore'; + +function CheckoutSummary() { + // Directly accessing cart's internal state structure + const items = useCartStore(s => s.items); + const appliedCoupons = useCartStore(s => s.coupons); + const shippingMethod = useCartStore(s => s.shipping.method); + + // If cart store changes structure, this breaks + return
...
; +} +``` + +**Correct (props as boundary):** + +```typescript +// Define explicit interface for what checkout needs +interface CheckoutSummaryProps { + items: Array<{ + id: string; + name: string; + price: number; + quantity: number; + }>; + subtotal: number; + discount: number; + shipping: number; + total: number; +} + +function CheckoutSummary({ items, subtotal, discount, shipping, total }: CheckoutSummaryProps) { + // Component only knows about its props, not cart internals + return ( +
+ {items.map(item => ( + + ))} + + {discount > 0 && } + + +
+ ); +} + +// App layer transforms cart state to checkout props +function CheckoutPage() { + const cart = useCartStore(); + + // Transformation happens at composition point + const summaryProps = { + items: cart.items.map(i => ({ + id: i.id, + name: i.product.name, + price: i.product.price, + quantity: i.quantity, + })), + subtotal: cart.getSubtotal(), + discount: cart.getDiscount(), + shipping: cart.getShippingCost(), + total: cart.getTotal(), + }; + + return ; +} +``` + +**Benefits:** +- CheckoutSummary doesn't import from cart feature +- Cart can restructure without breaking checkout +- CheckoutSummary is easily testable with mock props + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/fcomp-single-responsibility.md b/.agents/skills/feature-arch/references/fcomp-single-responsibility.md new file mode 100644 index 0000000..5c48826 --- /dev/null +++ b/.agents/skills/feature-arch/references/fcomp-single-responsibility.md @@ -0,0 +1,99 @@ +--- +title: Apply Single Responsibility to Components +impact: MEDIUM-HIGH +impactDescription: Enables parallel development and isolated testing; reduces component complexity +tags: comp, single-responsibility, separation, focused +--- + +## Apply Single Responsibility to Components + +Each component should do one thing well. When a component handles multiple concerns (rendering, data fetching, business logic), it becomes hard to test, reuse, and maintain. Split into focused components. + +**Incorrect (multiple responsibilities):** + +```typescript +// src/features/post/components/Post.tsx +export function Post({ postId }: { postId: string }) { + // Data fetching + const [post, setPost] = useState(null); + const [comments, setComments] = useState([]); + + useEffect(() => { + fetchPost(postId).then(setPost); + fetchComments(postId).then(setComments); + }, [postId]); + + // Business logic + const handleLike = async () => { ... }; + const handleComment = async () => { ... }; + + // Rendering post AND comments AND forms + return ( +
+

{post?.title}

+

{post?.content}

+ +
    + {comments.map(c =>
  • {c.text}
  • )} +
+ +
+ ); +} +``` + +**Correct (single responsibility each):** + +```typescript +// src/features/post/components/PostContent.tsx +interface PostContentProps { + post: Post; + onLike: () => void; +} + +export function PostContent({ post, onLike }: PostContentProps) { + return ( +
+

{post.title}

+

{post.content}

+ +
+ ); +} + +// src/features/comment/components/CommentList.tsx +interface CommentListProps { + comments: Comment[]; +} + +export function CommentList({ comments }: CommentListProps) { + return ( +
    + {comments.map(c => )} +
+ ); +} + +// src/app/posts/[id]/page.tsx (composition at app layer) +export async function PostPage({ postId }: { postId: string }) { + const [post, comments] = await Promise.all([ + getPost(postId), + getComments(postId), + ]); + + return ( + <> + likePost(postId)} /> + + + + ); +} +``` + +**Benefits:** +- PostContent can be tested without comments +- CommentList can be reused elsewhere +- Each component is ~20-50 lines, easy to understand + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md b/.agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md new file mode 100644 index 0000000..7928481 --- /dev/null +++ b/.agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md @@ -0,0 +1,80 @@ +--- +title: Avoid N+1 Query Patterns +impact: HIGH +impactDescription: Prevents request count from scaling with data size; eliminates O(N) network calls +tags: query, n-plus-one, performance, batching +--- + +## Avoid N+1 Query Patterns + +N+1 queries occur when you fetch a list and then individually fetch related data for each item. This creates N+1 requests instead of 2, causing performance to degrade with data growth. + +**Incorrect (N+1 pattern):** + +```typescript +// 1 request for posts + N requests for authors = N+1 total +export async function PostList() { + const posts = await getPosts(); // 1 request + + // N additional requests! + const postsWithAuthors = await Promise.all( + posts.map(async (post) => ({ + ...post, + author: await getUser(post.authorId), // 1 request per post + })) + ); + + return postsWithAuthors.map(post => ); +} +``` + +**Correct (batched query):** + +```typescript +// src/features/user/api/get-users-by-ids.ts +export async function getUsersByIds(ids: string[]) { + return prisma.user.findMany({ + where: { id: { in: ids } }, + }); +} + +// 2 requests total regardless of post count +export async function PostList() { + const posts = await getPosts(); // 1 request + + const authorIds = [...new Set(posts.map(p => p.authorId))]; + const authors = await getUsersByIds(authorIds); // 1 request + const authorsById = new Map(authors.map(a => [a.id, a])); + + const postsWithAuthors = posts.map(post => ({ + ...post, + author: authorsById.get(post.authorId), + })); + + return postsWithAuthors.map(post => ); +} +``` + +**Alternative: Lazy load where appropriate:** + +```typescript +// If authors are rarely viewed, lazy load on demand +export function PostCard({ post }: { post: Post }) { + const [showAuthor, setShowAuthor] = useState(false); + + return ( +
+

{post.title}

+ + {showAuthor && } +
+ ); +} +``` + +**When to accept N+1:** +- N is always small (< 5 items) +- Data is heavily cached and cache hits are near 100% +- Lazy loading is appropriate (user rarely views related data) + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/fquery-colocate-with-feature.md b/.agents/skills/feature-arch/references/fquery-colocate-with-feature.md new file mode 100644 index 0000000..300527d --- /dev/null +++ b/.agents/skills/feature-arch/references/fquery-colocate-with-feature.md @@ -0,0 +1,70 @@ +--- +title: Colocate Data Fetching with Features +impact: HIGH +impactDescription: Makes features self-contained; enables independent API evolution +tags: query, colocation, data-fetching, feature +--- + +## Colocate Data Fetching with Features + +Data fetching logic belongs within the feature that owns the data. When API calls are scattered in a central api/ folder, features lose independence and changes require coordinating across multiple locations. + +**Incorrect (centralized API layer):** + +``` +src/ +├── api/ +│ ├── users.ts # All user API calls +│ ├── posts.ts # All post API calls +│ ├── comments.ts # All comment API calls +│ └── orders.ts # All order API calls +└── features/ + ├── user/ + │ └── components/ # Components import from ../../../api/users + └── post/ + └── components/ # Components import from ../../../api/posts +``` + +**Correct (colocated with features):** + +``` +src/features/ +├── user/ +│ ├── api/ +│ │ ├── get-user.ts +│ │ ├── update-user.ts +│ │ └── delete-user.ts +│ ├── components/ +│ │ └── UserProfile.tsx +│ └── hooks/ +│ └── useUser.ts +└── post/ + ├── api/ + │ ├── get-post.ts + │ ├── get-posts.ts + │ └── create-post.ts + ├── components/ + │ └── PostList.tsx + └── hooks/ + └── usePosts.ts +``` + +```typescript +// src/features/user/hooks/useUser.ts +import { getUser } from '../api/get-user'; + +export function useUser(userId: string) { + return useQuery({ + queryKey: ['user', userId], + queryFn: () => getUser(userId), + }); +} +``` + +**Benefits:** +- Adding a feature includes its API calls +- Removing a feature removes its API calls +- Feature can evolve its API independently +- Related code is always together + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/fquery-feature-scoped-keys.md b/.agents/skills/feature-arch/references/fquery-feature-scoped-keys.md new file mode 100644 index 0000000..fa45890 --- /dev/null +++ b/.agents/skills/feature-arch/references/fquery-feature-scoped-keys.md @@ -0,0 +1,72 @@ +--- +title: Use Feature-Scoped Query Keys +impact: MEDIUM-HIGH +impactDescription: Enables targeted cache invalidation; prevents accidental cache collisions +tags: query, cache, keys, tanstack-query +--- + +## Use Feature-Scoped Query Keys + +Query keys should be hierarchical with the feature name as the root. This enables precise cache invalidation and prevents key collisions between features. + +**Incorrect (flat, collision-prone keys):** + +```typescript +// src/features/user/hooks/useUser.ts +useQuery({ queryKey: ['user', userId], ... }); + +// src/features/admin/hooks/useUser.ts +useQuery({ queryKey: ['user', userId], ... }); // Collides with above! + +// Hard to invalidate all user queries +queryClient.invalidateQueries({ queryKey: ['user'] }); // Might affect admin too +``` + +**Correct (feature-scoped key factory):** + +```typescript +// src/features/user/query-keys.ts +export const userKeys = { + all: ['user'] as const, + lists: () => [...userKeys.all, 'list'] as const, + list: (filters: UserFilters) => [...userKeys.lists(), filters] as const, + details: () => [...userKeys.all, 'detail'] as const, + detail: (id: string) => [...userKeys.details(), id] as const, +}; + +// src/features/user/hooks/useUser.ts +import { userKeys } from '../query-keys'; + +export function useUser(userId: string) { + return useQuery({ + queryKey: userKeys.detail(userId), + queryFn: () => getUser(userId), + }); +} + +// src/features/admin/query-keys.ts +export const adminUserKeys = { + all: ['admin', 'user'] as const, + detail: (id: string) => [...adminUserKeys.all, 'detail', id] as const, +}; +``` + +**Invalidation patterns:** + +```typescript +// Invalidate all user data +queryClient.invalidateQueries({ queryKey: userKeys.all }); + +// Invalidate only user lists (not details) +queryClient.invalidateQueries({ queryKey: userKeys.lists() }); + +// Invalidate specific user +queryClient.invalidateQueries({ queryKey: userKeys.detail(userId) }); +``` + +**Benefits:** +- Clear ownership of cache keys +- Predictable invalidation scope +- No accidental cross-feature cache interference + +Reference: [TanStack Query - Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) diff --git a/.agents/skills/feature-arch/references/fquery-parallel-fetching.md b/.agents/skills/feature-arch/references/fquery-parallel-fetching.md new file mode 100644 index 0000000..045c755 --- /dev/null +++ b/.agents/skills/feature-arch/references/fquery-parallel-fetching.md @@ -0,0 +1,71 @@ +--- +title: Fetch Independent Data in Parallel +impact: HIGH +impactDescription: Reduces total load time by ~50% for pages with multiple data sources +tags: query, parallel, performance, waterfall +--- + +## Fetch Independent Data in Parallel + +When a component needs multiple pieces of unrelated data, fetch them in parallel using Promise.all(). Sequential fetching creates waterfalls where total time equals the sum of all requests. + +**Incorrect (sequential waterfall):** + +```typescript +// Each request waits for the previous one +// Total time: 200ms + 150ms + 100ms = 450ms +export async function DashboardPage() { + const user = await getUser(userId); // 200ms + const orders = await getOrders(userId); // 150ms + const notifications = await getNotifications(userId); // 100ms + + return ; +} +``` + +**Correct (parallel fetching):** + +```typescript +// All requests start simultaneously +// Total time: max(200ms, 150ms, 100ms) = 200ms +export async function DashboardPage() { + const [user, orders, notifications] = await Promise.all([ + getUser(userId), // 200ms + getOrders(userId), // 150ms + getNotifications(userId), // 100ms + ]); + + return ; +} +``` + +**With React Query:** + +```typescript +// src/app/pages/DashboardPage.tsx +export function DashboardPage({ userId }: { userId: string }) { + // These queries run in parallel automatically + const userQuery = useUser(userId); + const ordersQuery = useOrders(userId); + const notificationsQuery = useNotifications(userId); + + if (userQuery.isLoading || ordersQuery.isLoading || notificationsQuery.isLoading) { + return ; + } + + return ( + + ); +} +``` + +**When sequential is necessary:** +- Second request depends on first request's result +- Rate limiting requires throttled requests +- User must complete a step before seeing next data + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/fquery-server-component-fetching.md b/.agents/skills/feature-arch/references/fquery-server-component-fetching.md new file mode 100644 index 0000000..e71c562 --- /dev/null +++ b/.agents/skills/feature-arch/references/fquery-server-component-fetching.md @@ -0,0 +1,88 @@ +--- +title: Fetch at Server Component Level +impact: MEDIUM-HIGH +impactDescription: Eliminates client-server waterfalls; reduces bundle size by keeping fetch logic on server +tags: query, server-components, rsc, next.js +--- + +## Fetch at Server Component Level + +In React Server Component architectures, fetch data in server components and pass to client components as props. This eliminates client-server waterfalls and keeps data fetching off the client bundle. + +**Incorrect (client component fetching):** + +```typescript +// src/features/post/components/PostPage.tsx +'use client'; + +export function PostPage({ postId }: { postId: string }) { + const [post, setPost] = useState(null); + + useEffect(() => { + fetch(`/api/posts/${postId}`) // Client-server waterfall + .then(res => res.json()) + .then(setPost); + }, [postId]); + + if (!post) return ; + return ; +} +``` + +**Correct (server component fetching):** + +```typescript +// src/features/post/components/PostPage.tsx (Server Component) +import { getPost } from '../api/get-post'; +import { PostContent } from './PostContent'; // Client component + +export async function PostPage({ postId }: { postId: string }) { + const post = await getPost(postId); // Fetches on server + + return ; +} + +// src/features/post/components/PostContent.tsx +'use client'; + +interface PostContentProps { + post: Post; // Receives data as props, no fetching +} + +export function PostContent({ post }: PostContentProps) { + const [likes, setLikes] = useState(post.likes); + + return ( +
+

{post.title}

+

{post.content}

+ setLikes(l => l + 1)} /> +
+ ); +} +``` + +**Composition pattern:** + +```typescript +// src/app/posts/[id]/page.tsx (Server Component) +import { PostPage } from '@/features/post'; +import { Comments } from '@/features/comment'; + +export default async function Page({ params }: { params: { id: string } }) { + // Parallel fetch at app layer + const [post, comments] = await Promise.all([ + getPost(params.id), + getComments(params.id), + ]); + + return ( + <> + + + + ); +} +``` + +Reference: [Next.js - Data Fetching](https://nextjs.org/docs/app/building-your-application/data-fetching) diff --git a/.agents/skills/feature-arch/references/fquery-single-responsibility.md b/.agents/skills/feature-arch/references/fquery-single-responsibility.md new file mode 100644 index 0000000..6705133 --- /dev/null +++ b/.agents/skills/feature-arch/references/fquery-single-responsibility.md @@ -0,0 +1,66 @@ +--- +title: Keep Query Functions Single-Purpose +impact: HIGH +impactDescription: Prevents query permutation explosion as features grow +tags: query, single-responsibility, data-fetching, api +--- + +## Keep Query Functions Single-Purpose + +Each query function should fetch one type of data. Avoid creating variations that combine multiple concerns. When features need combined data, fetch separately and compose at the component level. + +**Incorrect (query permutations):** + +```typescript +// src/features/post/api/queries.ts + +// Creates combinatorial explosion as requirements grow +export async function getPost(id: string) { ... } +export async function getPostWithComments(id: string) { ... } +export async function getPostWithAuthor(id: string) { ... } +export async function getPostWithCommentsAndAuthor(id: string) { ... } +export async function getPostWithCommentsAndAuthorAndLikes(id: string) { ... } +// N relations = 2^N possible combinations +``` + +**Correct (single-purpose queries):** + +```typescript +// src/features/post/api/get-post.ts +export async function getPost(id: string) { + return prisma.post.findUnique({ where: { id } }); +} + +// src/features/comment/api/get-comments.ts +export async function getComments(postId: string) { + return prisma.comment.findMany({ where: { postId } }); +} + +// src/features/user/api/get-user.ts +export async function getUser(id: string) { + return prisma.user.findUnique({ where: { id } }); +} + +// Component composes what it needs +export async function PostPage({ postId }: { postId: string }) { + const [post, comments] = await Promise.all([ + getPost(postId), + getComments(postId), + ]); + + return ( +
+ + +
+ ); +} +``` + +**Benefits:** +- Linear growth: N relations = N query functions +- Each query is independently cacheable +- Parallel fetching via Promise.all() +- Each feature owns its own data fetching + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/fstate-context-sparingly.md b/.agents/skills/feature-arch/references/fstate-context-sparingly.md new file mode 100644 index 0000000..024db1b --- /dev/null +++ b/.agents/skills/feature-arch/references/fstate-context-sparingly.md @@ -0,0 +1,73 @@ +--- +title: Use Context Sparingly for Feature State +impact: MEDIUM +impactDescription: Prevents context re-render cascades; keeps features portable +tags: state, context, provider, scope +--- + +## Use Context Sparingly for Feature State + +Context is useful for dependency injection and app-wide configuration, but causes re-render cascades when used for frequently-changing state. Prefer feature stores or local state for dynamic data. + +**Incorrect (frequently changing data in context):** + +```typescript +// Every context consumer re-renders on any cart change +const CartContext = createContext(null); + +function CartProvider({ children }) { + const [items, setItems] = useState([]); + const [total, setTotal] = useState(0); + + const addItem = (item) => { + setItems([...items, item]); // Re-renders all consumers + setTotal(total + item.price); + }; + + return ( + + {children} {/* Every consumer re-renders */} + + ); +} + +// Components re-render even if they only use `total` +function CartIcon() { + const { total } = useContext(CartContext); // Re-renders when items change + return {total}; +} +``` + +**Correct (store with selectors):** + +```typescript +// src/features/cart/stores/cartStore.ts +export const useCartStore = create((set, get) => ({ + items: [], + addItem: (item) => set(s => ({ items: [...s.items, item] })), + getTotal: () => get().items.reduce((sum, i) => sum + i.price, 0), +})); + +// Only re-renders when selected state changes +function CartIcon() { + const total = useCartStore(s => s.items.reduce((sum, i) => sum + i.price, 0)); + return {total}; +} + +function CartItemCount() { + const count = useCartStore(s => s.items.length); // Only re-renders when count changes + return {count}; +} +``` + +**When context is appropriate:** +- Dependency injection (API client, auth) +- Theme/locale (changes rarely) +- Feature flags (read-only) + +**When to use stores:** +- Frequently updating state +- Multiple components need different slices +- Need fine-grained subscriptions + +Reference: [Zustand Documentation](https://zustand-demo.pmnd.rs/) diff --git a/.agents/skills/feature-arch/references/fstate-feature-scoped-stores.md b/.agents/skills/feature-arch/references/fstate-feature-scoped-stores.md new file mode 100644 index 0000000..e03fd9f --- /dev/null +++ b/.agents/skills/feature-arch/references/fstate-feature-scoped-stores.md @@ -0,0 +1,79 @@ +--- +title: Scope State Stores to Features +impact: MEDIUM +impactDescription: Prevents global state coupling; enables feature-level state reset and testing +tags: state, stores, scope, feature +--- + +## Scope State Stores to Features + +Each feature should own its state store. When state is global, features become coupled through shared state, making them impossible to develop, test, or remove independently. + +**Incorrect (global monolithic store):** + +```typescript +// src/stores/store.ts +export const useStore = create((set) => ({ + // User feature state + user: null, + userLoading: false, + setUser: (user) => set({ user }), + + // Cart feature state + cartItems: [], + addToCart: (item) => set(s => ({ cartItems: [...s.cartItems, item] })), + + // Notification feature state + notifications: [], + addNotification: (n) => set(s => ({ notifications: [...s.notifications, n] })), + + // Everything mixed together - impossible to isolate +})); +``` + +**Correct (feature-scoped stores):** + +```typescript +// src/features/user/stores/userStore.ts +export const useUserStore = create((set) => ({ + user: null, + isLoading: false, + setUser: (user) => set({ user }), + clearUser: () => set({ user: null }), +})); + +// src/features/cart/stores/cartStore.ts +export const useCartStore = create((set) => ({ + items: [], + addItem: (item) => set(s => ({ items: [...s.items, item] })), + removeItem: (id) => set(s => ({ items: s.items.filter(i => i.id !== id) })), + clearCart: () => set({ items: [] }), +})); + +// src/features/notification/stores/notificationStore.ts +export const useNotificationStore = create((set) => ({ + notifications: [], + add: (n) => set(s => ({ notifications: [...s.notifications, n] })), + dismiss: (id) => set(s => ({ + notifications: s.notifications.filter(n => n.id !== id), + })), +})); +``` + +**Feature exposes store via public API:** + +```typescript +// src/features/cart/index.ts +export { useCartStore } from './stores/cartStore'; +export type { CartItem } from './types'; + +// Other features use the exported store +import { useCartStore } from '@/features/cart'; +``` + +**Benefits:** +- Feature can be removed along with its store +- Tests can reset feature state independently +- Clear ownership of state + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/fstate-lift-minimally.md b/.agents/skills/feature-arch/references/fstate-lift-minimally.md new file mode 100644 index 0000000..d78ab16 --- /dev/null +++ b/.agents/skills/feature-arch/references/fstate-lift-minimally.md @@ -0,0 +1,85 @@ +--- +title: Lift State Only as High as Necessary +impact: MEDIUM +impactDescription: Reduces re-renders; keeps state close to where it's used +tags: state, lifting, locality, performance +--- + +## Lift State Only as High as Necessary + +State should live in the lowest common ancestor of components that need it. Lifting state too high causes unnecessary re-renders and makes the state's purpose unclear. + +**Incorrect (state lifted too high):** + +```typescript +// State in app root - causes full tree re-render on every keystroke +function App() { + const [searchQuery, setSearchQuery] = useState(''); + const [sortOrder, setSortOrder] = useState('asc'); + const [selectedTab, setSelectedTab] = useState('all'); + + return ( +
+
+ + +
{/* Re-renders on every search keystroke */} +
+ ); +} +``` + +**Correct (state at lowest necessary level):** + +```typescript +function App() { + return ( +
+
+ +
{/* Never re-renders due to search/sort */} +
+ ); +} + +function MainContent() { + const [selectedTab, setSelectedTab] = useState('all'); + + return ( + <> + + + + ); +} + +function ProductList({ selectedTab }: { selectedTab: string }) { + // Search and sort state only affects ProductList subtree + const [searchQuery, setSearchQuery] = useState(''); + const [sortOrder, setSortOrder] = useState('asc'); + + return ( +
+ + + +
+ ); +} +``` + +**Decision guide:** + +| Situation | Where to put state | +|-----------|-------------------| +| Single component uses it | In that component | +| Sibling components share it | In parent | +| Distant components share it | Context or store | +| Server data | Query library | + +Reference: [React Docs - Sharing State](https://react.dev/learn/sharing-state-between-components) diff --git a/.agents/skills/feature-arch/references/fstate-reset-on-unmount.md b/.agents/skills/feature-arch/references/fstate-reset-on-unmount.md new file mode 100644 index 0000000..b0b9e67 --- /dev/null +++ b/.agents/skills/feature-arch/references/fstate-reset-on-unmount.md @@ -0,0 +1,89 @@ +--- +title: Reset Feature State on Unmount +impact: MEDIUM +impactDescription: Prevents stale state bugs; ensures clean feature initialization +tags: state, reset, cleanup, unmount +--- + +## Reset Feature State on Unmount + +When a feature unmounts, reset its state to prevent stale data from appearing when the feature remounts. Persistent stores can cause bugs when users navigate away and back. + +**Incorrect (stale state persists):** + +```typescript +// User views checkout, abandons, browses, returns to checkout +// Sees old form data from previous session +const useCheckoutStore = create((set) => ({ + shippingAddress: null, + paymentMethod: null, + setShipping: (addr) => set({ shippingAddress: addr }), +})); + +function CheckoutPage() { + const { shippingAddress } = useCheckoutStore(); + // shippingAddress still has old data from previous visit + return ; +} +``` + +**Correct (reset on unmount):** + +```typescript +// src/features/checkout/stores/checkoutStore.ts +const initialState = { + shippingAddress: null, + paymentMethod: null, + step: 1, +}; + +export const useCheckoutStore = create((set) => ({ + ...initialState, + setShipping: (addr) => set({ shippingAddress: addr }), + setPayment: (method) => set({ paymentMethod: method }), + nextStep: () => set(s => ({ step: s.step + 1 })), + reset: () => set(initialState), +})); + +// src/features/checkout/components/CheckoutPage.tsx +function CheckoutPage() { + const reset = useCheckoutStore(s => s.reset); + + useEffect(() => { + // Reset when leaving checkout + return () => reset(); + }, [reset]); + + return ; +} +``` + +**Alternative: Feature-scoped store instance:** + +```typescript +// src/features/checkout/CheckoutProvider.tsx +const CheckoutContext = createContext(null); + +export function CheckoutProvider({ children }) { + // New store instance created each mount + const storeRef = useRef(); + if (!storeRef.current) { + storeRef.current = createCheckoutStore(); + } + + return ( + + {children} + + ); +} + +// Store is automatically fresh on each mount +``` + +**When NOT to reset:** +- User preferences (theme, language) +- Draft content (auto-saved forms) +- Explicitly preserved state (shopping cart) + +Reference: [Zustand - Resetting State](https://zustand-demo.pmnd.rs/) diff --git a/.agents/skills/feature-arch/references/fstate-server-state-separation.md b/.agents/skills/feature-arch/references/fstate-server-state-separation.md new file mode 100644 index 0000000..87ebceb --- /dev/null +++ b/.agents/skills/feature-arch/references/fstate-server-state-separation.md @@ -0,0 +1,93 @@ +--- +title: Separate Server State from Client State +impact: MEDIUM +impactDescription: Eliminates manual cache sync; leverages query library optimizations +tags: state, server-state, client-state, tanstack-query +--- + +## Separate Server State from Client State + +Server state (data from API) and client state (UI state, form state) have different characteristics. Server state should be managed by a query library; client state by local state or stores. Mixing them leads to stale data and sync bugs. + +**Incorrect (server state in client store):** + +```typescript +// src/stores/userStore.ts +export const useUserStore = create((set) => ({ + users: [], + isLoading: false, + + // Manual fetching logic + fetchUsers: async () => { + set({ isLoading: true }); + const users = await api.getUsers(); + set({ users, isLoading: false }); + }, + + // Manual cache invalidation + invalidate: () => { + // How do we know when to refetch? + // What about stale data? + // What about deduplication? + }, +})); +``` + +**Correct (server state in query library):** + +```typescript +// src/features/user/hooks/useUsers.ts +// Server state - managed by TanStack Query +export function useUsers(filters: UserFilters) { + return useQuery({ + queryKey: userKeys.list(filters), + queryFn: () => getUsers(filters), + staleTime: 60_000, // Built-in cache management + }); +} + +// src/features/user/stores/userUIStore.ts +// Client state - UI-only concerns +export const useUserUIStore = create((set) => ({ + selectedUserId: null, + filterPanelOpen: false, + sortOrder: 'asc' as const, + + selectUser: (id) => set({ selectedUserId: id }), + toggleFilterPanel: () => set(s => ({ filterPanelOpen: !s.filterPanelOpen })), + setSortOrder: (order) => set({ sortOrder: order }), +})); +``` + +**Usage:** + +```typescript +function UserListPage() { + // Server state + const { data: users, isLoading } = useUsers({ active: true }); + + // Client state + const { selectedUserId, selectUser, sortOrder } = useUserUIStore(); + + const sortedUsers = useMemo(() => + [...(users ?? [])].sort((a, b) => + sortOrder === 'asc' ? a.name.localeCompare(b.name) : b.name.localeCompare(a.name) + ), + [users, sortOrder] + ); + + return ; +} +``` + +**Server state characteristics:** +- Fetched from external source +- Can become stale +- Needs refetching, deduplication, caching + +**Client state characteristics:** +- Created locally +- Never stale (source of truth is client) +- No network concerns + +Reference: [TanStack Query - Overview](https://tanstack.com/query/latest/docs/framework/react/overview) diff --git a/.agents/skills/feature-arch/references/import-avoid-barrel-files.md b/.agents/skills/feature-arch/references/import-avoid-barrel-files.md new file mode 100644 index 0000000..9f4b49d --- /dev/null +++ b/.agents/skills/feature-arch/references/import-avoid-barrel-files.md @@ -0,0 +1,63 @@ +--- +title: Avoid Deep Barrel File Re-exports +impact: HIGH +impactDescription: Prevents tree-shaking failures; reduces bundle size by avoiding unused code +tags: import, barrel-files, tree-shaking, bundle-size +--- + +## Avoid Deep Barrel File Re-exports + +While feature index.ts files are useful for public APIs, avoid creating nested barrel files that re-export everything. Deep barrel chains prevent bundlers from tree-shaking unused code and can cause performance issues in development. + +**Incorrect (barrel chain):** + +```typescript +// src/features/user/components/index.ts +export * from './UserProfile'; +export * from './UserSettings'; +export * from './UserAvatar'; +export * from './UserBadge'; +// ... 20 more exports + +// src/features/user/index.ts +export * from './components'; // Re-exports everything +export * from './hooks'; +export * from './utils'; + +// Consumer imports one component but bundles all +import { UserAvatar } from '@/features/user'; +``` + +**Correct (explicit exports):** + +```typescript +// src/features/user/index.ts +// Explicit, named exports - bundler knows exactly what's used +export { UserProfile } from './components/UserProfile'; +export { UserSettings } from './components/UserSettings'; +export { UserAvatar } from './components/UserAvatar'; +export { useUser } from './hooks/useUser'; +export type { User } from './types'; + +// Consumer +import { UserAvatar } from '@/features/user'; // Only UserAvatar bundled +``` + +**Alternative for large features:** + +```typescript +// Direct imports for specific needs +import { UserAvatar } from '@/features/user/components/UserAvatar'; + +// This is acceptable when: +// 1. Feature has 15+ exports +// 2. Consumer only needs one specific item +// 3. Bundle size is critical +``` + +**When barrel files are OK:** +- Feature public API (index.ts) with explicit exports +- Small features with < 10 exports +- Type-only exports (no runtime impact) + +Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md) diff --git a/.agents/skills/feature-arch/references/import-no-cross-feature.md b/.agents/skills/feature-arch/references/import-no-cross-feature.md new file mode 100644 index 0000000..4d13027 --- /dev/null +++ b/.agents/skills/feature-arch/references/import-no-cross-feature.md @@ -0,0 +1,84 @@ +--- +title: Prohibit Cross-Feature Imports +impact: CRITICAL +impactDescription: Prevents feature coupling; enables independent feature development +tags: import, cross-feature, coupling, isolation +--- + +## Prohibit Cross-Feature Imports + +Features must not import directly from other features. When features need to interact, compose them at the app layer. Direct cross-feature imports create hidden dependencies that make features impossible to modify independently. + +**Incorrect (cross-feature imports):** + +```typescript +// src/features/checkout/components/CheckoutSummary.tsx +import { ProductCard } from '@/features/product/components/ProductCard'; // WRONG +import { useCart } from '@/features/cart/hooks/useCart'; // WRONG +import { UserAddress } from '@/features/user/components/UserAddress'; // WRONG + +export function CheckoutSummary() { + const cart = useCart(); + return ( +
+ {cart.items.map(item => )} + +
+ ); +} +``` + +**Correct (composition at app layer):** + +```typescript +// src/features/checkout/components/CheckoutSummary.tsx +interface CheckoutSummaryProps { + items: CartItem[]; + renderProduct: (item: CartItem) => ReactNode; + addressSection: ReactNode; +} + +export function CheckoutSummary({ items, renderProduct, addressSection }: CheckoutSummaryProps) { + return ( +
+ {items.map(renderProduct)} + {addressSection} +
+ ); +} + +// src/app/pages/CheckoutPage.tsx +import { CheckoutSummary } from '@/features/checkout'; +import { ProductCard } from '@/features/product'; +import { UserAddress } from '@/features/user'; +import { useCart } from '@/features/cart'; + +export function CheckoutPage() { + const cart = useCart(); + return ( + } + addressSection={} + /> + ); +} +``` + +**ESLint enforcement per feature:** + +```javascript +// .eslintrc.js +rules: { + 'import/no-restricted-paths': ['error', { + zones: [ + { target: './src/features/checkout', from: './src/features/product' }, + { target: './src/features/checkout', from: './src/features/cart' }, + { target: './src/features/checkout', from: './src/features/user' }, + // Add for each feature combination + ], + }], +} +``` + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/import-path-aliases.md b/.agents/skills/feature-arch/references/import-path-aliases.md new file mode 100644 index 0000000..3711c99 --- /dev/null +++ b/.agents/skills/feature-arch/references/import-path-aliases.md @@ -0,0 +1,64 @@ +--- +title: Use Consistent Path Aliases +impact: HIGH +impactDescription: Eliminates ../../../ chains; makes imports self-documenting +tags: import, aliases, paths, navigation +--- + +## Use Consistent Path Aliases + +Configure path aliases to avoid relative import chains. Aliases make imports self-documenting by showing feature ownership clearly and survive file relocations within the same feature. + +**Incorrect (deep relative paths):** + +```typescript +// src/features/checkout/components/PaymentForm.tsx +import { Button } from '../../../shared/components/Button'; +import { useAuth } from '../../../features/auth/hooks/useAuth'; // Also wrong: cross-feature +import { formatCurrency } from '../../../shared/utils/formatCurrency'; +import { useCheckout } from '../hooks/useCheckout'; +``` + +**Correct (path aliases):** + +```typescript +// src/features/checkout/components/PaymentForm.tsx +import { Button } from '@/shared/components/Button'; +import { formatCurrency } from '@/shared/utils/formatCurrency'; +import { useCheckout } from '../hooks/useCheckout'; // Same feature = relative OK +``` + +**tsconfig.json:** + +```json +{ + "compilerOptions": { + "paths": { + "@/*": ["./src/*"], + "@/shared/*": ["./src/shared/*"], + "@/features/*": ["./src/features/*"], + "@/app/*": ["./src/app/*"] + } + } +} +``` + +**Guidelines:** +- Use `@/` prefix for absolute imports from src +- Use relative imports (`./`, `../`) within the same feature +- Relative imports within a feature make the feature more portable + +**Vite configuration:** + +```typescript +// vite.config.ts +export default defineConfig({ + resolve: { + alias: { + '@': path.resolve(__dirname, './src'), + }, + }, +}); +``` + +Reference: [Robin Wieruch - React Folder Structure](https://www.robinwieruch.de/react-folder-structure/) diff --git a/.agents/skills/feature-arch/references/import-public-api.md b/.agents/skills/feature-arch/references/import-public-api.md new file mode 100644 index 0000000..766d3e9 --- /dev/null +++ b/.agents/skills/feature-arch/references/import-public-api.md @@ -0,0 +1,67 @@ +--- +title: Export Through Public API Only +impact: CRITICAL +impactDescription: Prevents deep imports; enables internal refactoring without breaking consumers +tags: import, public-api, encapsulation, index +--- + +## Export Through Public API Only + +Each feature should have a single entry point (index.ts) that exports its public API. External code should never import internal files directly. This allows internal restructuring without affecting consumers. + +**Incorrect (deep imports into feature internals):** + +```typescript +// src/app/pages/UserPage.tsx +import { UserProfile } from '@/features/user/components/UserProfile'; +import { useUser } from '@/features/user/hooks/useUser'; +import { formatUserName } from '@/features/user/utils/formatters'; +import { User } from '@/features/user/types/user'; +``` + +**Correct (import from public API):** + +```typescript +// src/features/user/index.ts (public API) +export { UserProfile } from './components/UserProfile'; +export { UserSettings } from './components/UserSettings'; +export { useUser } from './hooks/useUser'; +export type { User, UserRole } from './types'; +// Note: formatUserName is NOT exported - it's internal + +// src/app/pages/UserPage.tsx +import { UserProfile, useUser } from '@/features/user'; +import type { User } from '@/features/user'; +``` + +**Internal file can import freely:** + +```typescript +// src/features/user/components/UserProfile.tsx +import { useUser } from '../hooks/useUser'; +import { formatUserName } from '../utils/formatters'; // Internal util +import type { User } from '../types'; +``` + +**ESLint enforcement:** + +```javascript +// .eslintrc.js +rules: { + 'no-restricted-imports': ['error', { + patterns: [ + { + group: ['@/features/*/components/*', '@/features/*/hooks/*', '@/features/*/utils/*'], + message: 'Import from feature index.ts instead', + }, + ], + }], +} +``` + +**Benefits:** +- Refactor internal structure without breaking external imports +- Clear contract of what a feature provides +- Smaller, focused public surface area + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/import-type-only.md b/.agents/skills/feature-arch/references/import-type-only.md new file mode 100644 index 0000000..2fed447 --- /dev/null +++ b/.agents/skills/feature-arch/references/import-type-only.md @@ -0,0 +1,81 @@ +--- +title: Use Type-Only Imports for Types +impact: MEDIUM +impactDescription: Enables cross-feature type sharing without runtime coupling +tags: import, types, typescript, type-only +--- + +## Use Type-Only Imports for Types + +Use `import type` syntax when importing only TypeScript types. This ensures types are stripped at compile time and allows sharing types across features without creating runtime dependencies. + +**Incorrect (mixing type and value imports):** + +```typescript +// src/features/checkout/components/CheckoutForm.tsx +import { User, useUser } from '@/features/user'; // Creates runtime dependency for type + +export function CheckoutForm({ userId }: { userId: string }) { + // We only need the User type, not useUser + const [user, setUser] = useState(null); +} +``` + +**Correct (separate type imports):** + +```typescript +// src/features/checkout/components/CheckoutForm.tsx +import type { User } from '@/features/user'; // Type-only, no runtime dependency + +export function CheckoutForm({ userId }: { userId: string }) { + const [user, setUser] = useState(null); +} +``` + +**Shared types for cross-feature contracts:** + +```typescript +// src/shared/types/entities.ts +export interface User { + id: string; + email: string; + name: string; +} + +export interface Product { + id: string; + name: string; + price: number; +} + +// Features import shared types +// src/features/checkout/types.ts +import type { User, Product } from '@/shared/types/entities'; + +export interface CheckoutItem { + product: Product; + quantity: number; +} + +export interface CheckoutSession { + user: User; + items: CheckoutItem[]; +} +``` + +**Benefits:** +- No runtime bundle impact for type-only imports +- Clear distinction between runtime and compile-time dependencies +- Enables type sharing without architectural coupling + +**TypeScript configuration:** + +```json +{ + "compilerOptions": { + "verbatimModuleSyntax": true // Enforces type-only imports + } +} +``` + +Reference: [TypeScript Handbook - Type-Only Imports](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export) diff --git a/.agents/skills/feature-arch/references/import-unidirectional-flow.md b/.agents/skills/feature-arch/references/import-unidirectional-flow.md new file mode 100644 index 0000000..e3fb5ef --- /dev/null +++ b/.agents/skills/feature-arch/references/import-unidirectional-flow.md @@ -0,0 +1,82 @@ +--- +title: Enforce Unidirectional Import Flow +impact: CRITICAL +impactDescription: Prevents circular dependencies; enables deterministic build order +tags: import, unidirectional, dependencies, architecture +--- + +## Enforce Unidirectional Import Flow + +Imports must flow in one direction: `shared → features → app`. Features can import from shared, and app can import from both, but never the reverse. This prevents circular dependencies that cause build failures and makes the dependency graph predictable. + +**Incorrect (bidirectional imports):** + +```typescript +// src/shared/utils/analytics.ts +import { useAuth } from '@/features/auth/hooks/useAuth'; // WRONG: shared → features + +export function trackEvent(event: string) { + const { user } = useAuth(); + // ... +} +``` + +```typescript +// src/features/user/components/UserProfile.tsx +import { AppLayout } from '@/app/layouts/AppLayout'; // WRONG: features → app + +export function UserProfile() { + return ...; +} +``` + +**Correct (unidirectional flow):** + +```typescript +// Dependency flow: shared → features → app + +// src/shared/utils/analytics.ts +export function trackEvent(event: string, userId?: string) { + // No feature imports - userId passed as parameter +} + +// src/features/user/components/UserProfile.tsx +import { formatDate } from '@/shared/utils/formatDate'; // OK: shared used by feature +import { trackEvent } from '@/shared/utils/analytics'; + +export function UserProfile({ user }) { + useEffect(() => { + trackEvent('profile_view', user.id); + }, []); + return
...
; +} + +// src/app/pages/UserPage.tsx +import { UserProfile } from '@/features/user'; // OK: app uses features +import { AppLayout } from '@/app/layouts/AppLayout'; + +export function UserPage() { + return ( + + + + ); +} +``` + +**ESLint enforcement:** + +```javascript +// .eslintrc.js +rules: { + 'import/no-restricted-paths': ['error', { + zones: [ + { target: './src/shared', from: './src/features' }, + { target: './src/shared', from: './src/app' }, + { target: './src/features', from: './src/app' }, + ], + }], +} +``` + +Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md) diff --git a/.agents/skills/feature-arch/references/name-descriptive-exports.md b/.agents/skills/feature-arch/references/name-descriptive-exports.md new file mode 100644 index 0000000..11e0aea --- /dev/null +++ b/.agents/skills/feature-arch/references/name-descriptive-exports.md @@ -0,0 +1,65 @@ +--- +title: Use Descriptive Export Names +impact: LOW +impactDescription: Enables IDE autocomplete; makes imports self-documenting +tags: name, exports, descriptive, clarity +--- + +## Use Descriptive Export Names + +Export names should be descriptive and unique across the codebase. Generic names like `Card`, `List`, or `Button` cause confusion when multiple features export similar components. + +**Incorrect (generic export names):** + +```typescript +// src/features/user/components/Card.tsx +export function Card({ user }) { ... } // Which card? + +// src/features/product/components/Card.tsx +export function Card({ product }) { ... } // Collision! + +// Import confusion +import { Card } from '@/features/user'; // UserCard? ProductCard? +import { Card as ProductCard } from '@/features/product'; // Requires alias +``` + +**Correct (descriptive export names):** + +```typescript +// src/features/user/components/UserCard.tsx +export function UserCard({ user }: { user: User }) { ... } + +// src/features/product/components/ProductCard.tsx +export function ProductCard({ product }: { product: Product }) { ... } + +// Clear imports +import { UserCard } from '@/features/user'; +import { ProductCard } from '@/features/product'; +``` + +**Naming patterns:** + +| Type | Pattern | Example | +|------|---------|---------| +| Feature component | `{Feature}{Component}` | `UserProfile`, `CartSummary` | +| Feature hook | `use{Feature}{Action}` | `useUserAuth`, `useCartItems` | +| Feature API | `{action}{Feature}` | `getUser`, `updateCart` | +| Feature store | `use{Feature}Store` | `useCartStore`, `useUserStore` | + +**Exception for shared components:** + +```typescript +// Shared components can use generic names - they're not feature-specific +// src/shared/components/Button.tsx +export function Button({ children, ...props }) { ... } + +// src/shared/components/Card.tsx +export function Card({ children, ...props }) { ... } +``` + +**Benefits:** +- IDE autocomplete shows meaningful options +- Imports are self-documenting +- No aliasing required + +Reference: [React Naming Conventions](https://react.dev/learn/thinking-in-react) diff --git a/.agents/skills/feature-arch/references/name-feature-naming.md b/.agents/skills/feature-arch/references/name-feature-naming.md new file mode 100644 index 0000000..dfcb6ce --- /dev/null +++ b/.agents/skills/feature-arch/references/name-feature-naming.md @@ -0,0 +1,60 @@ +--- +title: Use Domain-Driven Feature Names +impact: LOW +impactDescription: Improves discoverability; aligns code with business terminology +tags: name, features, domain, naming +--- + +## Use Domain-Driven Feature Names + +Name features after business domains, not technical implementations. This makes the codebase navigable for non-developers and ensures feature boundaries align with business boundaries. + +**Incorrect (technical naming):** + +```text +src/features/ +├── data-grid/ # What data? What domain? +├── form-handler/ # What form? What entity? +├── api-client/ # Generic technical concern +├── modal-manager/ # UI pattern, not domain +└── list-view/ # Generic view pattern +``` + +**Correct (domain naming):** + +```text +src/features/ +├── user/ # User management domain +├── product/ # Product catalog domain +├── cart/ # Shopping cart domain +├── checkout/ # Checkout/payment domain +├── order/ # Order management domain +├── notification/ # Notification domain +└── search/ # Search domain +``` + +**Naming guidelines:** + +| Domain | Good Name | Bad Name | +|--------|-----------|----------| +| User management | `user`, `account` | `profile-component` | +| Product catalog | `product`, `catalog` | `item-list` | +| Shopping | `cart`, `checkout` | `purchase-flow` | +| Authentication | `auth` | `login-system` | + +**Sub-features:** + +```text +src/features/ +├── user/ +│ ├── ... # Core user feature +├── user-preferences/ # Distinct sub-domain +└── user-notifications/ # Another sub-domain +``` + +**Ask these questions:** +- Would a product manager understand this name? +- Does this map to a business capability? +- Would this name make sense in a requirements document? + +Reference: [Bounded Context - Martin Fowler](https://martinfowler.com/bliki/BoundedContext.html) diff --git a/.agents/skills/feature-arch/references/name-file-conventions.md b/.agents/skills/feature-arch/references/name-file-conventions.md new file mode 100644 index 0000000..9325e0b --- /dev/null +++ b/.agents/skills/feature-arch/references/name-file-conventions.md @@ -0,0 +1,79 @@ +--- +title: Use Consistent File Naming Conventions +impact: LOW +impactDescription: Enables pattern-based tooling; reduces cognitive load +tags: name, files, conventions, consistency +--- + +## Use Consistent File Naming Conventions + +Establish and follow consistent file naming patterns. This enables automated tooling, makes files predictable, and reduces decision fatigue. + +**Incorrect (inconsistent naming):** + +``` +src/features/user/ +├── components/ +│ ├── UserProfile.tsx # PascalCase +│ ├── user-avatar.tsx # kebab-case +│ ├── userBadge.tsx # camelCase +│ └── User_Settings.tsx # Snake_Case +├── hooks/ +│ ├── useUser.ts # camelCase +│ └── use-auth.ts # kebab-case +└── api/ + ├── getUser.ts # camelCase + └── user-api.ts # kebab-case +``` + +**Correct (consistent conventions):** + +``` +src/features/user/ +├── components/ +│ ├── UserProfile.tsx # PascalCase for components +│ ├── UserAvatar.tsx +│ ├── UserBadge.tsx +│ └── UserSettings.tsx +├── hooks/ +│ ├── useUser.ts # camelCase with use prefix +│ └── useUserAuth.ts +├── api/ +│ ├── get-user.ts # kebab-case for non-components +│ ├── update-user.ts +│ └── delete-user.ts +├── stores/ +│ └── user-store.ts # kebab-case +├── types/ +│ └── index.ts +└── utils/ + └── format-user-name.ts # kebab-case +``` + +**Recommended conventions:** + +| File Type | Convention | Example | +|-----------|------------|---------| +| React components | PascalCase | `UserProfile.tsx` | +| Hooks | camelCase with use prefix | `useUser.ts` | +| API functions | kebab-case | `get-user.ts` | +| Stores | kebab-case | `user-store.ts` | +| Utilities | kebab-case | `format-date.ts` | +| Types | index.ts or kebab-case | `types/index.ts` | +| Tests | match source + .test | `UserProfile.test.tsx` | + +**ESLint enforcement:** + +```javascript +// .eslintrc.js +rules: { + 'unicorn/filename-case': ['error', { + cases: { + pascalCase: true, // For .tsx files + kebabCase: true, // For .ts files + }, + }], +} +``` + +Reference: [Airbnb React Style Guide](https://github.com/airbnb/javascript/tree/master/react) diff --git a/.agents/skills/feature-arch/references/struct-app-layer.md b/.agents/skills/feature-arch/references/struct-app-layer.md new file mode 100644 index 0000000..564304e --- /dev/null +++ b/.agents/skills/feature-arch/references/struct-app-layer.md @@ -0,0 +1,73 @@ +--- +title: Separate App Layer from Features +impact: HIGH +impactDescription: Isolates global concerns; enables feature modules to remain pure +tags: struct, app-layer, providers, routing +--- + +## Separate App Layer from Features + +The app layer handles global concerns: routing, providers, initialization, and global layouts. Features should not contain routing logic or provider setup. This separation allows features to be portable and testable in isolation. + +**Incorrect (routing and providers mixed with features):** + +``` +src/features/user/ +├── components/ +│ └── UserProfile.tsx +├── UserRoutes.tsx # Routing logic in feature +└── UserProvider.tsx # Provider in feature +``` + +```typescript +// src/features/user/UserRoutes.tsx +import { Routes, Route } from 'react-router-dom'; + +export function UserRoutes() { + return ( + + } /> + } /> + + ); +} +``` + +**Correct (app layer owns routing and providers):** + +``` +src/ +├── app/ +│ ├── providers/ +│ │ ├── AuthProvider.tsx +│ │ ├── QueryProvider.tsx +│ │ └── index.tsx +│ ├── routes/ +│ │ ├── index.tsx +│ │ └── protected-routes.tsx +│ └── App.tsx +└── features/ + └── user/ + ├── components/ + │ ├── UserProfile.tsx + │ └── UserSettings.tsx + └── index.ts +``` + +```typescript +// src/app/routes/index.tsx +import { UserProfile, UserSettings } from '@/features/user'; + +export const routes = [ + { path: '/profile', element: }, + { path: '/settings', element: }, +]; +``` + +**App layer responsibilities:** +- Route definitions and navigation +- Provider composition (Auth, Query, Theme) +- Global error boundaries +- Application initialization + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/struct-feature-folders.md b/.agents/skills/feature-arch/references/struct-feature-folders.md new file mode 100644 index 0000000..8740ce2 --- /dev/null +++ b/.agents/skills/feature-arch/references/struct-feature-folders.md @@ -0,0 +1,70 @@ +--- +title: Organize by Feature, Not Technical Type +impact: CRITICAL +impactDescription: Eliminates cross-file navigation; reduces onboarding time by 50%+ +tags: struct, organization, feature-folders, scalability +--- + +## Organize by Feature, Not Technical Type + +Technical grouping (components/, hooks/, utils/) forces developers to navigate multiple directories for single features. Feature-based organization colocates all related code, making features self-documenting and independently deployable. + +**Incorrect (technical grouping):** + +``` +src/ +├── components/ +│ ├── PostCard.tsx +│ ├── CommentList.tsx +│ └── UserAvatar.tsx +├── hooks/ +│ ├── usePost.ts +│ ├── useComments.ts +│ └── useUser.ts +├── api/ +│ ├── posts.ts +│ ├── comments.ts +│ └── users.ts +└── utils/ + ├── postHelpers.ts + └── commentHelpers.ts +``` + +**Correct (feature-based grouping):** + +``` +src/ +├── features/ +│ ├── post/ +│ │ ├── components/ +│ │ │ └── PostCard.tsx +│ │ ├── hooks/ +│ │ │ └── usePost.ts +│ │ ├── api/ +│ │ │ └── get-post.ts +│ │ └── utils/ +│ │ └── postHelpers.ts +│ ├── comment/ +│ │ ├── components/ +│ │ │ └── CommentList.tsx +│ │ ├── hooks/ +│ │ │ └── useComments.ts +│ │ └── api/ +│ │ └── get-comments.ts +│ └── user/ +│ ├── components/ +│ │ └── UserAvatar.tsx +│ └── hooks/ +│ └── useUser.ts +└── shared/ + └── components/ + └── Button.tsx +``` + +**Benefits:** +- Adding a feature = adding one folder +- Removing a feature = removing one folder +- Feature ownership is immediately clear +- Teams can work on different features without conflicts + +Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/) diff --git a/.agents/skills/feature-arch/references/struct-feature-self-contained.md b/.agents/skills/feature-arch/references/struct-feature-self-contained.md new file mode 100644 index 0000000..1a377b9 --- /dev/null +++ b/.agents/skills/feature-arch/references/struct-feature-self-contained.md @@ -0,0 +1,62 @@ +--- +title: Make Features Self-Contained +impact: CRITICAL +impactDescription: Enables independent deployment and parallel team development +tags: struct, isolation, self-contained, modularity +--- + +## Make Features Self-Contained + +Each feature folder should contain everything needed to implement that feature. When a feature requires code from multiple places, it becomes entangled with other features and cannot evolve independently. + +**Incorrect (scattered feature code):** + +```typescript +// src/components/checkout/CheckoutForm.tsx +import { useCart } from '../../hooks/useCart'; +import { validateCard } from '../../utils/validation'; +import { CartSummary } from '../cart/CartSummary'; +import { paymentApi } from '../../api/payment'; + +export function CheckoutForm() { + const cart = useCart(); + // Feature depends on 4 different locations +} +``` + +**Correct (self-contained feature):** + +```typescript +// src/features/checkout/components/CheckoutForm.tsx +import { useCart } from '../hooks/useCart'; +import { validateCard } from '../utils/validation'; +import { CartSummary } from '../components/CartSummary'; +import { submitPayment } from '../api/submit-payment'; + +export function CheckoutForm() { + const cart = useCart(); + // All imports are within the feature +} +``` + +**Feature folder structure:** + +``` +features/checkout/ +├── api/ +│ └── submit-payment.ts +├── components/ +│ ├── CheckoutForm.tsx +│ └── CartSummary.tsx +├── hooks/ +│ └── useCart.ts +├── utils/ +│ └── validation.ts +└── index.ts +``` + +**When NOT to use this pattern:** +- Truly generic utilities (date formatting, string helpers) belong in `shared/` +- UI primitives (Button, Input) belong in `shared/components/` + +Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md) diff --git a/.agents/skills/feature-arch/references/struct-flat-hierarchy.md b/.agents/skills/feature-arch/references/struct-flat-hierarchy.md new file mode 100644 index 0000000..4a21b00 --- /dev/null +++ b/.agents/skills/feature-arch/references/struct-flat-hierarchy.md @@ -0,0 +1,58 @@ +--- +title: Keep Directory Hierarchy Flat +impact: CRITICAL +impactDescription: Reduces cognitive load; prevents 5+ level deep import paths +tags: struct, nesting, hierarchy, navigation +--- + +## Keep Directory Hierarchy Flat + +Deep nesting creates long import paths, makes file relocation difficult, and obscures the overall structure. Limit nesting to 2-3 levels within features. + +**Incorrect (deep nesting):** + +``` +src/features/checkout/ +├── components/ +│ ├── form/ +│ │ ├── fields/ +│ │ │ ├── payment/ +│ │ │ │ └── CardInput.tsx +│ │ │ └── shipping/ +│ │ │ └── AddressInput.tsx +│ │ └── FormWrapper.tsx +│ └── summary/ +│ └── OrderSummary.tsx +``` + +```typescript +// Import path is 6 levels deep +import { CardInput } from '../../../components/form/fields/payment/CardInput'; +``` + +**Correct (flat hierarchy):** + +``` +src/features/checkout/ +├── components/ +│ ├── CardInput.tsx +│ ├── AddressInput.tsx +│ ├── FormWrapper.tsx +│ └── OrderSummary.tsx +``` + +```typescript +// Import path is 2 levels +import { CardInput } from '../components/CardInput'; +``` + +**When deeper nesting is acceptable:** +- Feature has 20+ components (consider splitting into sub-features) +- Clear categorical distinction (e.g., `forms/` vs `displays/`) + +**Guidelines:** +- Maximum 3 levels within a feature folder +- If you need deeper nesting, the feature is likely too large +- Prefer flat with clear naming over deep with vague naming + +Reference: [Robin Wieruch - React Folder Structure](https://www.robinwieruch.de/react-folder-structure/) diff --git a/.agents/skills/feature-arch/references/struct-optional-segments.md b/.agents/skills/feature-arch/references/struct-optional-segments.md new file mode 100644 index 0000000..419ed23 --- /dev/null +++ b/.agents/skills/feature-arch/references/struct-optional-segments.md @@ -0,0 +1,72 @@ +--- +title: Include Only Necessary Segments +impact: HIGH +impactDescription: Prevents empty folder clutter; keeps features minimal and focused +tags: struct, segments, minimal, pragmatic +--- + +## Include Only Necessary Segments + +Not every feature needs every segment (components/, hooks/, api/, utils/, types/). Start with only what the feature requires and add segments as complexity grows. Empty folders add noise and suggest over-engineering. + +**Incorrect (every segment even when unused):** + +``` +src/features/notification/ +├── api/ # Empty - notifications are client-side only +├── components/ +│ └── Toast.tsx +├── hooks/ +│ └── useNotification.ts +├── stores/ # Empty - using context instead +├── types/ +│ └── index.ts # Just re-exports one interface +└── utils/ # Empty +``` + +**Correct (only necessary segments):** + +``` +src/features/notification/ +├── components/ +│ └── Toast.tsx +├── hooks/ +│ └── useNotification.ts +└── types.ts # Single file, not a folder with one file +``` + +**Another example - simple feature:** + +``` +src/features/theme/ +├── ThemeProvider.tsx +├── useTheme.ts +└── index.ts +``` + +**Complex feature with all segments:** + +``` +src/features/checkout/ +├── api/ +│ ├── submit-order.ts +│ └── validate-address.ts +├── components/ +│ ├── CheckoutForm.tsx +│ ├── PaymentSection.tsx +│ └── ShippingSection.tsx +├── hooks/ +│ ├── useCheckout.ts +│ └── usePaymentMethods.ts +├── stores/ +│ └── checkout-store.ts +├── types/ +│ └── index.ts +├── utils/ +│ └── validation.ts +└── index.ts +``` + +**Guideline:** Add segments when you have 2+ files that would go there. + +Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md) diff --git a/.agents/skills/feature-arch/references/struct-shared-layer.md b/.agents/skills/feature-arch/references/struct-shared-layer.md new file mode 100644 index 0000000..9702454 --- /dev/null +++ b/.agents/skills/feature-arch/references/struct-shared-layer.md @@ -0,0 +1,68 @@ +--- +title: Use Shared Layer for Truly Generic Code Only +impact: CRITICAL +impactDescription: Prevents shared/ from becoming a dumping ground; maintains feature boundaries +tags: struct, shared, reusability, generic +--- + +## Use Shared Layer for Truly Generic Code Only + +The shared layer should contain only code with high reusability and minimal business logic. When business-specific code lands in shared/, it creates hidden dependencies and prevents features from being truly independent. + +**Incorrect (business logic in shared):** + +``` +src/shared/ +├── components/ +│ ├── Button.tsx # Generic - OK +│ ├── ProductCard.tsx # Business-specific - WRONG +│ └── UserBadge.tsx # Business-specific - WRONG +├── hooks/ +│ ├── useDebounce.ts # Generic - OK +│ └── useCheckout.ts # Business-specific - WRONG +└── utils/ + ├── formatDate.ts # Generic - OK + └── calculateTax.ts # Business-specific - WRONG +``` + +**Correct (shared is generic only):** + +``` +src/shared/ +├── components/ +│ ├── Button.tsx +│ ├── Input.tsx +│ ├── Modal.tsx +│ └── Tooltip.tsx +├── hooks/ +│ ├── useDebounce.ts +│ ├── useLocalStorage.ts +│ └── useMediaQuery.ts +└── utils/ + ├── formatDate.ts + ├── formatCurrency.ts + └── cn.ts +``` + +``` +src/features/product/ +├── components/ +│ └── ProductCard.tsx # Business component lives with feature +└── ... + +src/features/checkout/ +├── hooks/ +│ └── useCheckout.ts # Business hook lives with feature +├── utils/ +│ └── calculateTax.ts # Business util lives with feature +└── ... +``` + +**Litmus test for shared/:** +- Would this be useful in a completely different project? +- Does it contain zero business domain knowledge? +- Is it used by 3+ features? + +If any answer is "no", it belongs in a feature folder. + +Reference: [Feature-Sliced Design](https://feature-sliced.design/) diff --git a/.agents/skills/feature-arch/references/test-colocate-with-feature.md b/.agents/skills/feature-arch/references/test-colocate-with-feature.md new file mode 100644 index 0000000..20324b2 --- /dev/null +++ b/.agents/skills/feature-arch/references/test-colocate-with-feature.md @@ -0,0 +1,78 @@ +--- +title: Colocate Tests with Features +impact: MEDIUM +impactDescription: Makes test coverage visible; ensures tests move with features +tags: test, colocation, organization, feature +--- + +## Colocate Tests with Features + +Tests should live in the same feature folder as the code they test. When tests are in a separate tests/ folder, they become disconnected from the code, leading to missing coverage and orphaned tests. + +**Incorrect (centralized test folder):** + +``` +src/ +├── features/ +│ ├── user/ +│ │ └── components/ +│ │ └── UserProfile.tsx +│ └── cart/ +│ └── hooks/ +│ └── useCart.ts +└── tests/ # Disconnected from features + ├── user/ + │ └── UserProfile.test.tsx + └── cart/ + └── useCart.test.ts +``` + +**Correct (colocated tests):** + +``` +src/features/ +├── user/ +│ ├── components/ +│ │ ├── UserProfile.tsx +│ │ └── __tests__/ +│ │ └── UserProfile.test.tsx +│ └── hooks/ +│ ├── useUser.ts +│ └── __tests__/ +│ └── useUser.test.ts +└── cart/ + ├── hooks/ + │ ├── useCart.ts + │ └── __tests__/ + │ └── useCart.test.ts + └── api/ + ├── get-cart.ts + └── __tests__/ + └── get-cart.test.ts +``` + +**Alternative: Adjacent files:** + +``` +src/features/user/components/ +├── UserProfile.tsx +└── UserProfile.test.tsx # Same folder, no __tests__ subfolder +``` + +**Benefits:** +- Moving a feature moves its tests +- Deleting a feature deletes its tests +- Test coverage is visible in the feature folder +- Easy to see what's tested at a glance + +**vitest.config.ts:** + +```typescript +export default defineConfig({ + test: { + include: ['src/**/*.test.{ts,tsx}'], + }, +}); +``` + +Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md) diff --git a/.agents/skills/feature-arch/references/test-feature-isolation.md b/.agents/skills/feature-arch/references/test-feature-isolation.md new file mode 100644 index 0000000..7915afb --- /dev/null +++ b/.agents/skills/feature-arch/references/test-feature-isolation.md @@ -0,0 +1,88 @@ +--- +title: Test Features in Isolation +impact: MEDIUM +impactDescription: Enables faster tests; provides clear failure attribution +tags: test, isolation, mocking, independence +--- + +## Test Features in Isolation + +Feature tests should mock cross-feature dependencies. When tests use real implementations of other features, they become slow, flaky, and failures are hard to attribute. + +**Incorrect (integrated feature tests):** + +```typescript +// Testing checkout feature but using real cart and user features +describe('CheckoutForm', () => { + it('submits order', async () => { + // Test depends on cart and user working correctly + render( + + + + + + + + ); + + // If cart has a bug, checkout tests fail + // Slow because it's testing 3 features + }); +}); +``` + +**Correct (isolated feature tests):** + +```typescript +// src/features/checkout/components/__tests__/CheckoutForm.test.tsx +describe('CheckoutForm', () => { + const mockItems = [ + { id: '1', name: 'Product', price: 100, quantity: 2 }, + ]; + + it('submits order with provided items', async () => { + const onSubmit = vi.fn(); + + render( + + ); + + await userEvent.click(screen.getByRole('button', { name: /submit/i })); + + expect(onSubmit).toHaveBeenCalledWith({ + items: mockItems, + userId: 'user-123', + }); + }); + + it('shows empty state when no items', () => { + render(); + + expect(screen.getByText(/cart is empty/i)).toBeInTheDocument(); + }); +}); +``` + +**Mock cross-feature hooks:** + +```typescript +// Mock the cart feature's exported hook +vi.mock('@/features/cart', () => ({ + useCart: () => ({ + items: [{ id: '1', name: 'Test', price: 50, quantity: 1 }], + total: 50, + }), +})); +``` + +**Benefits:** +- Fast tests (no unnecessary dependencies) +- Clear failure attribution +- Tests document the feature's interface + +Reference: [Testing Library - Guiding Principles](https://testing-library.com/docs/guiding-principles) diff --git a/.agents/skills/feature-arch/references/test-integration-at-app-layer.md b/.agents/skills/feature-arch/references/test-integration-at-app-layer.md new file mode 100644 index 0000000..4ed73d5 --- /dev/null +++ b/.agents/skills/feature-arch/references/test-integration-at-app-layer.md @@ -0,0 +1,87 @@ +--- +title: Write Integration Tests at App Layer +impact: MEDIUM +impactDescription: Verifies feature composition; catches integration bugs +tags: test, integration, e2e, app-layer +--- + +## Write Integration Tests at App Layer + +While features should be tested in isolation, integration tests that verify features work together belong at the app layer. This matches the composition structure of the application. + +**Incorrect (integration tests inside features):** + +```typescript +// src/features/checkout/__tests__/checkout-integration.test.tsx +// WRONG: Integration test inside a feature folder +import { CartProvider } from '@/features/cart'; +import { UserProvider } from '@/features/user'; +import { CheckoutForm } from '../components/CheckoutForm'; + +describe('Checkout Integration', () => { + it('completes checkout with cart and user', async () => { + render( + + + + + + ); + // Feature test depends on other features + }); +}); +``` + +**Correct (integration tests at app layer):** + +```typescript +// src/app/__tests__/checkout-flow.test.tsx +// Correct: Integration test at app layer where features are composed +describe('Checkout Flow Integration', () => { + it('completes order from cart to confirmation', async () => { + render( + + + + ); + + // Add product to cart (cart feature) + await userEvent.click(screen.getByRole('button', { name: /add to cart/i })); + + // Navigate to checkout (routing) + await userEvent.click(screen.getByRole('link', { name: /checkout/i })); + + // Fill checkout form (checkout feature) + await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com'); + await userEvent.click(screen.getByRole('button', { name: /place order/i })); + + // Verify confirmation (order feature) + expect(await screen.findByText(/order confirmed/i)).toBeInTheDocument(); + }); +}); +``` + +**E2E tests for critical paths:** + +```typescript +// e2e/checkout.spec.ts +test('complete purchase flow', async ({ page }) => { + await page.goto('/products'); + await page.click('[data-testid="add-to-cart"]'); + await page.click('[data-testid="go-to-checkout"]'); + await page.fill('[name="email"]', 'test@example.com'); + await page.click('text=Place Order'); + await expect(page.locator('text=Order Confirmed')).toBeVisible(); +}); +``` + +**Test layer structure:** + +``` +tests/ +├── unit/ # Fast, isolated tests (run on every commit) +├── integration/ # Feature composition tests (run on PR) +└── e2e/ # Full user journeys (run before deploy) +``` + +Reference: [Testing Trophy - Kent C. Dodds](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications) diff --git a/.agents/skills/feature-arch/references/test-shared-utilities.md b/.agents/skills/feature-arch/references/test-shared-utilities.md new file mode 100644 index 0000000..ea4d93d --- /dev/null +++ b/.agents/skills/feature-arch/references/test-shared-utilities.md @@ -0,0 +1,94 @@ +--- +title: Create Feature-Specific Test Utilities +impact: MEDIUM +impactDescription: Reduces test boilerplate; ensures consistent test setup +tags: test, utilities, helpers, fixtures +--- + +## Create Feature-Specific Test Utilities + +Each feature should have its own test utilities: factories, fixtures, and render wrappers. Shared test utilities become coupled to all features and are hard to maintain. + +**Incorrect (global test utilities):** + +```typescript +// src/testing/utils.ts - One file for all features +export function createMockUser() { ... } +export function createMockProduct() { ... } +export function createMockOrder() { ... } +export function renderWithProviders(ui: ReactNode) { + return render(ui, { + wrapper: ({ children }) => ( + + + + + {children} + + + + + ), + }); +} +``` + +**Correct (feature-specific utilities):** + +```typescript +// src/features/user/testing/factories.ts +export function createUser(overrides?: Partial): User { + return { + id: faker.string.uuid(), + email: faker.internet.email(), + name: faker.person.fullName(), + ...overrides, + }; +} + +// src/features/user/testing/render.tsx +export function renderUserFeature(ui: ReactNode) { + const queryClient = new QueryClient({ + defaultOptions: { queries: { retry: false } }, + }); + + return render(ui, { + wrapper: ({ children }) => ( + + {children} + + ), + }); +} + +// src/features/user/testing/index.ts +export { createUser } from './factories'; +export { renderUserFeature } from './render'; + +// Usage in tests +import { createUser, renderUserFeature } from '../testing'; + +describe('UserProfile', () => { + it('displays user name', () => { + const user = createUser({ name: 'Jane Doe' }); + renderUserFeature(); + expect(screen.getByText('Jane Doe')).toBeInTheDocument(); + }); +}); +``` + +**Shared testing utilities (truly generic):** + +```typescript +// src/shared/testing/query-client.ts +export function createTestQueryClient() { + return new QueryClient({ + defaultOptions: { + queries: { retry: false }, + mutations: { retry: false }, + }, + }); +} +``` + +Reference: [Testing Library - Setup](https://testing-library.com/docs/react-testing-library/setup) diff --git a/.agents/skills/msw/SKILL.md b/.agents/skills/msw/SKILL.md new file mode 100644 index 0000000..9df0ca7 --- /dev/null +++ b/.agents/skills/msw/SKILL.md @@ -0,0 +1,121 @@ +--- +name: msw +description: MSW 2 API mocking for tests. +--- + +# MSW Best Practices + +Comprehensive API mocking guide for MSW v2 applications (current: MSW 2.15), designed for AI agents and LLMs. Contains 48 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation. + +## When to Apply + +Reference these guidelines when: +- Setting up MSW for testing or development +- Writing or organizing request handlers +- Configuring test environments with MSW +- Mocking REST or GraphQL APIs +- Debugging handler matching issues +- Testing error states and edge cases + +## Rule Categories by Priority + +| Priority | Category | Impact | Prefix | +|----------|----------|--------|--------| +| 1 | Setup & Initialization | CRITICAL | `setup-` | +| 2 | Handler Architecture | CRITICAL | `handler-` | +| 3 | Test Integration | HIGH | `test-` | +| 4 | Response Patterns | HIGH | `response-` | +| 5 | Request Matching | MEDIUM-HIGH | `match-` | +| 6 | GraphQL Mocking | MEDIUM | `graphql-` | +| 7 | Advanced Patterns | MEDIUM | `advanced-` | +| 8 | Debugging & Performance | LOW | `debug-` | + +## Quick Reference + +### 1. Setup & Initialization (CRITICAL) + +- `setup-server-node-entrypoint` - Use correct entrypoint for Node.js (msw/node) +- `setup-lifecycle-hooks` - Configure server lifecycle in test setup +- `setup-worker-script-commit` - Commit worker script to version control +- `setup-node-version` - Require Node.js 18+ for MSW v2 +- `setup-unhandled-requests` - Configure unhandled request behavior +- `setup-typescript-config` - Configure TypeScript for MSW v2 + +### 2. Handler Architecture (CRITICAL) + +- `handler-happy-path-first` - Define happy path handlers as baseline +- `handler-domain-grouping` - Group handlers by domain +- `handler-absolute-urls` - Use absolute URLs in handlers +- `handler-shared-resolvers` - Extract shared response logic into resolvers +- `handler-v2-response-syntax` - Use MSW v2 response syntax +- `handler-request-body-parsing` - Explicitly parse request bodies +- `handler-resolver-argument` - Destructure resolver arguments correctly +- `handler-reusability-environments` - Share handlers across environments + +### 3. Test Integration (HIGH) + +- `test-reset-handlers` - Reset handlers after each test +- `test-avoid-request-assertions` - Avoid direct request assertions +- `test-concurrent-boundary` - Use server.boundary() for concurrent tests +- `test-fake-timers-config` - Configure fake timers to preserve queueMicrotask +- `test-async-utilities` - Use async testing utilities for mock responses +- `test-clear-request-cache` - Clear request library caches between tests +- `test-jsdom-environment` - Use correct JSDOM environment for Jest + +### 4. Response Patterns (HIGH) + +- `response-http-response-helpers` - Use HttpResponse static methods +- `response-delay-realistic` - Add delays only for timing behavior under test +- `response-error-simulation` - Simulate error responses correctly +- `response-one-time-handlers` - Use one-time handlers for sequential scenarios +- `response-custom-headers` - Set response headers correctly +- `response-streaming` - Mock streaming responses with ReadableStream + +### 5. Request Matching (MEDIUM-HIGH) + +- `match-url-patterns` - Use URL path parameters correctly +- `match-query-params` - Access query parameters from request URL +- `match-custom-predicate` - Use custom predicates for complex matching +- `match-http-methods` - Match HTTP methods explicitly +- `match-handler-order` - Order handlers from specific to general + +### 6. GraphQL Mocking (MEDIUM) + +- `graphql-operation-handlers` - Use operation name for GraphQL matching +- `graphql-error-responses` - Return GraphQL errors in correct format +- `graphql-batched-queries` - Handle batched GraphQL queries +- `graphql-variables-access` - Access GraphQL variables correctly +- `graphql-schema-first` - Resolve operations against a GraphQL schema + +### 7. Advanced Patterns (MEDIUM) + +- `advanced-bypass-requests` - Use bypass() for passthrough requests +- `advanced-cookies-auth` - Handle cookies and authentication +- `advanced-dynamic-scenarios` - Implement dynamic mock scenarios +- `advanced-vitest-browser` - Configure MSW for Vitest browser mode +- `advanced-file-uploads` - Mock file upload endpoints +- `advanced-websocket-mocking` - Mock WebSocket connections with ws.link +- `advanced-playwright-integration` - Use defineNetworkFixture from @msw/playwright + +### 8. Debugging & Performance (LOW) + +- `debug-lifecycle-events` - Use lifecycle events for debugging +- `debug-verify-interception` - Verify request interception is working +- `debug-common-issues` - Know common MSW issues and fixes +- `debug-request-logging` - Log request details for debugging + +## How to Use + +Run in the project root first: + +```bash +npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions +npx -y @pymodel/react-frontend-skills scan --skill msw # deprecated APIs → rule IDs +``` + +Read `references/.md` for each rule above that matches the task and for each `scan` hit: why it matters, then incorrect vs. correct code. + +## Related Skills + +- For consuming mocked APIs, see `tanstack-query` skill +- For test framework patterns, see `vitest`; for methodology, see `tdd` diff --git a/.agents/skills/msw/references/advanced-bypass-requests.md b/.agents/skills/msw/references/advanced-bypass-requests.md new file mode 100644 index 0000000..85c5dda --- /dev/null +++ b/.agents/skills/msw/references/advanced-bypass-requests.md @@ -0,0 +1,81 @@ +--- +title: Use bypass() for Passthrough Requests +impact: MEDIUM +impactDescription: Enables mixing real and mocked APIs; supports hybrid testing +tags: advanced, bypass, passthrough, real-api, proxy +--- + +## Use bypass() for Passthrough Requests + +Use `bypass()` to mark requests that should skip MSW interception and hit the real server. This enables hybrid scenarios where some APIs are mocked and others are real. + +**Incorrect (request creates infinite loop):** + +```typescript +// Making a fetch inside a handler without bypass creates infinite recursion +http.get('/api/user', async () => { + // This request is intercepted by this same handler! + const realResponse = await fetch('/api/user') // Infinite loop + return realResponse +}) +``` + +**Correct (bypass MSW interception):** + +```typescript +import { http, HttpResponse, bypass } from 'msw' + +export const handlers = [ + // Proxy to real API and modify response + http.get('/api/user', async ({ request }) => { + // bypass() marks the request to skip MSW + const realResponse = await fetch(bypass(request)) + const realData = await realResponse.json() + + // Augment real data with mock data + return HttpResponse.json({ + ...realData, + mockField: 'added by MSW', + }) + }), + + // Conditional passthrough + http.get('/api/data', async ({ request }) => { + const url = new URL(request.url) + + // Only mock in test environment + if (url.searchParams.get('mock') !== 'true') { + return fetch(bypass(request)) + } + + return HttpResponse.json({ mocked: true }) + }), +] +``` + +**Using passthrough() for unconditional passthrough:** + +```typescript +import { http, passthrough } from 'msw' + +export const handlers = [ + // Always pass through to real API + http.get('/api/analytics/*', () => { + return passthrough() + }), + + // Pass through external APIs + http.all('https://external-service.com/*', () => { + return passthrough() + }), +] +``` + +**Difference between bypass and passthrough:** +- `bypass(request)`: Use inside a handler to make a real request +- `passthrough()`: Return from handler to let the original request through + +**When NOT to use this pattern:** +- Fully mocked environments should avoid real API calls + +Reference: [MSW bypass API](https://mswjs.io/docs/api/bypass) diff --git a/.agents/skills/msw/references/advanced-cookies-auth.md b/.agents/skills/msw/references/advanced-cookies-auth.md new file mode 100644 index 0000000..8ff09b5 --- /dev/null +++ b/.agents/skills/msw/references/advanced-cookies-auth.md @@ -0,0 +1,119 @@ +--- +title: Handle Cookies and Authentication +impact: MEDIUM +impactDescription: Enables session-based auth testing; validates auth flows +tags: advanced, cookies, authentication, session, auth +--- + +## Handle Cookies and Authentication + +Access cookies from the `cookies` object in resolvers and set cookies via response headers. This enables testing of session-based authentication flows. + +**Incorrect (ignoring authentication state):** + +```typescript +// Always returns user regardless of auth state +http.get('/api/user', () => { + return HttpResponse.json({ name: 'John' }) +}) +``` + +**Correct (cookie-based auth handling):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Login sets session cookie + http.post('/api/login', async ({ request }) => { + const { email, password } = await request.json() + + if (email === 'john@example.com' && password === 'password') { + return HttpResponse.json( + { user: { id: '1', email } }, + { + headers: { + 'Set-Cookie': 'session=abc123; Path=/; HttpOnly; SameSite=Strict', + }, + } + ) + } + + return HttpResponse.json( + { error: 'Invalid credentials' }, + { status: 401 } + ) + }), + + // Protected endpoint checks cookie + http.get('/api/user', ({ cookies }) => { + if (!cookies.session) { + return HttpResponse.json( + { error: 'Not authenticated' }, + { status: 401 } + ) + } + + // In real app, validate session token + return HttpResponse.json({ + id: '1', + name: 'John', + email: 'john@example.com', + }) + }), + + // Logout clears cookie + http.post('/api/logout', () => { + return new HttpResponse(null, { + status: 200, + headers: { + 'Set-Cookie': 'session=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT', + }, + }) + }), +] +``` + +**Bearer token authentication:** + +```typescript +http.get('/api/protected', ({ request }) => { + const authHeader = request.headers.get('Authorization') + + if (!authHeader?.startsWith('Bearer ')) { + return HttpResponse.json( + { error: 'Missing token' }, + { status: 401 } + ) + } + + const token = authHeader.slice(7) + + // Validate token (simplified) + if (token === 'valid-token') { + return HttpResponse.json({ data: 'protected content' }) + } + + return HttpResponse.json( + { error: 'Invalid token' }, + { status: 403 } + ) +}) +``` + +**Multiple cookies:** + +```typescript +http.get('/api/preferences', ({ cookies }) => { + return HttpResponse.json({ + theme: cookies.theme || 'light', + language: cookies.lang || 'en', + userId: cookies.session ? '1' : null, + }) +}) +``` + +**When NOT to use this pattern:** +- Public endpoints that don't require authentication + +Reference: [MSW Cookies](https://mswjs.io/docs/concepts/request-handler#cookies) diff --git a/.agents/skills/msw/references/advanced-dynamic-scenarios.md b/.agents/skills/msw/references/advanced-dynamic-scenarios.md new file mode 100644 index 0000000..ab894ed --- /dev/null +++ b/.agents/skills/msw/references/advanced-dynamic-scenarios.md @@ -0,0 +1,114 @@ +--- +title: Implement Dynamic Mock Scenarios +impact: MEDIUM +impactDescription: Enables runtime mock state changes; supports complex test flows +tags: advanced, dynamic, scenarios, state, runtime +--- + +## Implement Dynamic Mock Scenarios + +Use module-level state or scenario flags to switch between different mock behaviors at runtime. This enables testing different application states without restarting tests. + +**Incorrect (static handlers for all scenarios):** + +```typescript +// Can't test different user states without test setup changes +http.get('/api/user', () => { + return HttpResponse.json({ name: 'John', plan: 'free' }) +}) +``` + +**Correct (dynamic scenario switching):** + +```typescript +import { http, HttpResponse } from 'msw' + +// Scenario state +type Scenario = 'default' | 'premium' | 'expired' | 'error' +let currentScenario: Scenario = 'default' + +// Export function to change scenario +export function setScenario(scenario: Scenario) { + currentScenario = scenario +} + +export const handlers = [ + http.get('/api/user', () => { + switch (currentScenario) { + case 'premium': + return HttpResponse.json({ + name: 'John', + plan: 'premium', + features: ['feature1', 'feature2', 'feature3'], + }) + + case 'expired': + return HttpResponse.json({ + name: 'John', + plan: 'expired', + features: [], + message: 'Please renew your subscription', + }) + + case 'error': + return HttpResponse.json( + { error: 'Service unavailable' }, + { status: 503 } + ) + + default: + return HttpResponse.json({ + name: 'John', + plan: 'free', + features: ['feature1'], + }) + } + }), +] +``` + +**Usage in tests:** + +```typescript +import { setScenario } from '../mocks/handlers' + +describe('Subscription', () => { + afterEach(() => { + setScenario('default') // Reset after each test + }) + + it('shows premium features for premium users', async () => { + setScenario('premium') + render() + expect(await screen.findByText('Premium Features')).toBeInTheDocument() + }) + + it('shows renewal prompt for expired users', async () => { + setScenario('expired') + render() + expect(await screen.findByText('Please renew')).toBeInTheDocument() + }) +}) +``` + +**URL-based scenarios (for development):** + +```typescript +http.get('/api/user', ({ request }) => { + const url = new URL(request.url) + const scenario = url.searchParams.get('_scenario') + + if (scenario === 'error') { + return new HttpResponse(null, { status: 500 }) + } + + return HttpResponse.json({ name: 'John' }) +}) + +// In browser: /dashboard?_scenario=error +``` + +**When NOT to use this pattern:** +- Simple tests with single states don't need scenario complexity + +Reference: [Dynamic Mock Scenarios](https://mswjs.io/docs/best-practices/dynamic-mock-scenarios) diff --git a/.agents/skills/msw/references/advanced-file-uploads.md b/.agents/skills/msw/references/advanced-file-uploads.md new file mode 100644 index 0000000..28191fe --- /dev/null +++ b/.agents/skills/msw/references/advanced-file-uploads.md @@ -0,0 +1,109 @@ +--- +title: Mock File Upload Endpoints +impact: MEDIUM +impactDescription: Tests file upload forms and progress indicators +tags: advanced, upload, file, formdata, multipart +--- + +## Mock File Upload Endpoints + +Parse `FormData` from requests to mock file upload endpoints. Access uploaded files and other form fields through the standard `FormData` API. + +**Incorrect (ignoring multipart data):** + +```typescript +// Can't access uploaded file +http.post('/api/upload', () => { + return HttpResponse.json({ success: true }) +}) +``` + +**Correct (parsing FormData):** + +```typescript +import { http, HttpResponse, delay } from 'msw' + +export const handlers = [ + // Single file upload + http.post('/api/upload', async ({ request }) => { + const formData = await request.formData() + const file = formData.get('file') as File + + if (!file) { + return HttpResponse.json( + { error: 'No file provided' }, + { status: 400 } + ) + } + + // Simulate upload delay based on file size + await delay(Math.min(file.size / 1000, 2000)) + + return HttpResponse.json({ + id: crypto.randomUUID(), + filename: file.name, + size: file.size, + mimeType: file.type, + url: `https://cdn.example.com/uploads/${file.name}`, + }) + }), + + // Multiple files + http.post('/api/upload-multiple', async ({ request }) => { + const formData = await request.formData() + const files = formData.getAll('files') as File[] + + const results = files.map((file) => ({ + id: crypto.randomUUID(), + filename: file.name, + size: file.size, + })) + + return HttpResponse.json({ files: results }) + }), + + // File with additional form fields + http.post('/api/profile/avatar', async ({ request }) => { + const formData = await request.formData() + const avatar = formData.get('avatar') as File + const userId = formData.get('userId') as string + + if (!avatar || !userId) { + return HttpResponse.json( + { error: 'Missing required fields' }, + { status: 400 } + ) + } + + return HttpResponse.json({ + userId, + avatarUrl: `https://cdn.example.com/avatars/${userId}/${avatar.name}`, + }) + }), +] +``` + +**Validating file types:** + +```typescript +http.post('/api/upload/image', async ({ request }) => { + const formData = await request.formData() + const file = formData.get('image') as File + + const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'] + + if (!allowedTypes.includes(file.type)) { + return HttpResponse.json( + { error: 'Invalid file type. Allowed: JPEG, PNG, GIF' }, + { status: 415 } + ) + } + + return HttpResponse.json({ success: true, url: '/uploaded.jpg' }) +}) +``` + +**When NOT to use this pattern:** +- JSON-only APIs don't need FormData parsing + +Reference: [MSW file uploads](https://mswjs.io/docs/http/mocking-responses/file-uploads) diff --git a/.agents/skills/msw/references/advanced-playwright-integration.md b/.agents/skills/msw/references/advanced-playwright-integration.md new file mode 100644 index 0000000..40a9eb1 --- /dev/null +++ b/.agents/skills/msw/references/advanced-playwright-integration.md @@ -0,0 +1,78 @@ +--- +title: Use defineNetworkFixture from @msw/playwright +impact: MEDIUM +impactDescription: controls MSW network from Playwright tests without cross-process worker hacks +tags: msw, playwright, e2e, network, fixture +--- + +## Use defineNetworkFixture from @msw/playwright + +The official [`@msw/playwright`](https://github.com/mswjs/msw/tree/master/packages/playwright) binding lets Playwright tests use the familiar `setupWorker()` API (`use`, `resetHandlers`) directly from the Node.js test process. Without it, overriding handlers requires clunky `page.evaluate(() => window.msw.worker.use(...))` bridges because the worker lives in the browser process. + +**Incorrect (cross-process worker references):** + +```typescript +test('shows dashboard', async ({ page }) => { + // Requires exposing msw on window and serializing overrides + // across the test<->browser process boundary + await page.evaluate(() => { + const { worker, http } = window.msw + worker.use(http.get('/user', () => new Response('{}'))) + }) + await page.goto('/dashboard') +}) +``` + +**Correct (network fixture in the setup file):** + +```typescript +// playwright.setup.ts +import { test as testBase } from '@playwright/test' +import { type AnyHandler } from 'msw' +import { defineNetworkFixture, type NetworkFixture } from '@msw/playwright' +import { handlers } from '../mocks/handlers.js' + +interface Fixtures { + handlers: Array + network: NetworkFixture +} + +export const test = testBase.extend({ + // Initial list of the network handlers + handlers: [handlers, { option: true }], + + network: [ + async ({ context, handlers }, use) => { + const network = defineNetworkFixture({ context, handlers }) + await network.enable() + await use(network) + await network.disable() + }, + { auto: true }, + ], +}) +``` + +**Correct (override handlers from the test itself):** + +```typescript +import { http, HttpResponse } from 'msw' +import { test } from './playwright.setup.js' + +test('displays the user dashboard', async ({ network, page }) => { + network.use( + http.get('/user', () => + HttpResponse.json({ id: 'abc-123', firstName: 'John' }), + ), + ) + + await page.goto('/dashboard') +}) +``` + +**Notes:** + +- Install with `npm i msw @msw/playwright`; no worker script initialization is needed — the package provisions interception through Playwright's `page.route()` until cross-process interception ships. +- `page.route()` limitations apply (e.g., no request bodies for some redirects); treat the transport as an implementation detail. +- WebSocket links via `ws.link()` work, but relative WebSocket URLs resolve against the most recently created page in the context. +- For Vitest browser mode, do not use this package — use the plain browser integration with a test-context fixture instead (see [advanced-vitest-browser](advanced-vitest-browser.md)). diff --git a/.agents/skills/msw/references/advanced-vitest-browser.md b/.agents/skills/msw/references/advanced-vitest-browser.md new file mode 100644 index 0000000..59442a0 --- /dev/null +++ b/.agents/skills/msw/references/advanced-vitest-browser.md @@ -0,0 +1,100 @@ +--- +title: Configure MSW for Vitest Browser Mode +impact: MEDIUM +impactDescription: Enables browser-environment testing with proper worker setup +tags: advanced, vitest, browser, worker, testing +--- + +## Configure MSW for Vitest Browser Mode + +Extend Vitest's test context to include the MSW worker when testing in browser mode. This ensures proper worker lifecycle management per test. + +**Incorrect (global worker without test context):** + +```typescript +// Worker state leaks between tests +import { worker } from './mocks/browser' + +beforeAll(() => worker.start()) +afterAll(() => worker.stop()) + +// Tests can't override handlers safely +``` + +**Correct (extended test context):** + +```typescript +// test-extend.ts +import { test as testBase } from 'vitest' +import { worker } from './mocks/browser' + +export const test = testBase.extend({ + worker: [ + async ({}, use) => { + // Start worker before test + await worker.start({ + onUnhandledRequest: 'error', + }) + + // Provide worker to test + await use(worker) + + // Reset handlers after test + worker.resetHandlers() + }, + { + auto: true, // Automatically available to all tests + }, + ], +}) + +export { expect } from 'vitest' +``` + +```typescript +// user.test.ts +import { http, HttpResponse } from 'msw' +import { test, expect } from './test-extend' +import { Dashboard } from './components/Dashboard' + +test('displays user data', async ({ worker }) => { + // Worker is automatically started + render() + expect(await screen.findByText('John')).toBeInTheDocument() +}) + +test('handles error state', async ({ worker }) => { + // Override handlers for this test + worker.use( + http.get('/api/user', () => { + return new HttpResponse(null, { status: 500 }) + }) + ) + + render() + expect(await screen.findByText('Error loading')).toBeInTheDocument() +}) +``` + +**Vitest config for browser mode:** + +```typescript +// vitest.config.ts +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + test: { + browser: { + enabled: true, + name: 'chromium', + provider: 'playwright', + }, + setupFiles: ['./vitest.setup.ts'], + }, +}) +``` + +**When NOT to use this pattern:** +- Node.js tests should use `setupServer` instead + +Reference: [MSW Vitest Browser Mode](https://mswjs.io/docs/recipes/vitest-browser-mode) diff --git a/.agents/skills/msw/references/advanced-websocket-mocking.md b/.agents/skills/msw/references/advanced-websocket-mocking.md new file mode 100644 index 0000000..322fb66 --- /dev/null +++ b/.agents/skills/msw/references/advanced-websocket-mocking.md @@ -0,0 +1,87 @@ +--- +title: Mock WebSocket Connections with ws.link +impact: MEDIUM +impactDescription: tests realtime features (chat, live feeds) without a real server +tags: msw, websocket, ws, realtime, socket.io +--- + +## Mock WebSocket Connections with ws.link + +MSW 2.x intercepts WebSocket connections with the `ws` namespace. `ws.link(url)` creates a WebSocket link handler; its `connection` event gives you the `client` and `server` connection objects to mock a realtime session. + +**Incorrect (mocking WebSocket with ad-hoc stubs):** + +```typescript +// Replacing the global WebSocket with a hand-rolled fake +class FakeWebSocket { + send = vi.fn() + close = vi.fn() + addEventListener = vi.fn() +} +vi.stubGlobal('WebSocket', FakeWebSocket) +// Breaks on every real-world protocol nuance; skips MSW's +// handler model entirely, so no shared mock scenarios +``` + +**Correct (use a WebSocket link handler):** + +```typescript +import { ws } from 'msw' + +const chat = ws.link('wss://api.example.com/chat') + +export const handlers = [ + chat.addEventListener('connection', ({ client, server }) => { + // Greet the connected client immediately + client.send(JSON.stringify({ type: 'welcome' })) + + // Echo incoming client messages back + client.addEventListener('message', (event) => { + client.send(JSON.stringify({ type: 'ack', data: event.data })) + }) + }), +] +``` + +**Forward between client and actual server:** + +```typescript +chat.addEventListener('connection', ({ client, server }) => { + server.connect() + + // Pass client messages through to the real server + client.addEventListener('message', (event) => { + server.send(event.data) + }) + + // Observe server messages without changing them + server.addEventListener('message', (event) => { + client.send(event.data) + }) +}) +``` + +**Mock Socket.IO with the official binding:** + +```typescript +import { ws } from 'msw' +import { toSocketIo } from '@mswjs/socket.io-binding' + +const chat = ws.link('wss://chat.example.com') + +export const handlers = [ + chat.addEventListener('connection', (connection) => { + const io = toSocketIo(connection) + + io.client.on('hello', (username) => { + io.client.emit('message', `hello, ${username}!`) + }) + }), +] +``` + +**Notes:** + +- The connection listener arguments include `client`, `server`, `params` (path parameters from the link URL), and connection `info`. +- Call `server.connect()` only when you want to establish the actual underlying server connection; omit it for fully mocked sessions. +- WebSocket links go in the same `handlers` array as `http`/`graphql` handlers and work in browser, Node.js, and React Native integrations. diff --git a/.agents/skills/msw/references/debug-common-issues.md b/.agents/skills/msw/references/debug-common-issues.md new file mode 100644 index 0000000..56c3a2a --- /dev/null +++ b/.agents/skills/msw/references/debug-common-issues.md @@ -0,0 +1,79 @@ +--- +title: Know Common MSW Issues and Fixes +impact: LOW +impactDescription: Quick reference for frequent problems; reduces debugging time +tags: debug, troubleshooting, issues, fixes, reference +--- + +## Know Common MSW Issues and Fixes + +Reference this checklist when MSW behaves unexpectedly. Most issues fall into a few common categories that have well-known solutions. + +**Incorrect (handler not matching due to relative URL):** + +```typescript +// Node.js environment - handler never matches +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Relative URL doesn't match absolute request URLs + http.get('/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), +] + +// When fetch('http://localhost:3000/api/user') is called, +// the handler doesn't match because '/api/user' !== 'http://localhost:3000/api/user' +``` + +**Correct (handler matches with wildcard):** + +```typescript +// Node.js environment - handler matches any origin +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Wildcard matches any origin prefix + http.get('*/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), +] + +// Now fetch('http://localhost:3000/api/user') matches correctly +``` + +## Common Issues Quick Reference + +**Issue: "fetch is not defined"** +- Fix: Upgrade Node.js to 18+ (native fetch support) + +**Issue: Body parsing hangs with fake timers** +```typescript +// Fix: Exclude queueMicrotask from fake timers +vi.useFakeTimers({ + toFake: ['setTimeout', 'setInterval', 'Date'], + // queueMicrotask NOT faked +}) +``` + +**Issue: Stale responses from cache** +```typescript +// Fix: Clear request library cache between tests +afterEach(() => { + cache.clear() // SWR + queryClient.clear() // TanStack Query +}) +``` + +**Issue: MSW v1 code in v2 project** +```typescript +// v2 correct syntax: +http.get('/api/user', () => { + return HttpResponse.json({ name: 'John' }) +}) +``` + +**When NOT to use this pattern:** +- Reference only; not all issues apply to every project + +Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/) diff --git a/.agents/skills/msw/references/debug-lifecycle-events.md b/.agents/skills/msw/references/debug-lifecycle-events.md new file mode 100644 index 0000000..cb4fdee --- /dev/null +++ b/.agents/skills/msw/references/debug-lifecycle-events.md @@ -0,0 +1,88 @@ +--- +title: Use Lifecycle Events for Debugging +impact: LOW +impactDescription: Provides visibility into request interception; aids troubleshooting +tags: debug, lifecycle, events, logging, observability +--- + +## Use Lifecycle Events for Debugging + +Subscribe to lifecycle events to observe request interception, matching, and responses. This is invaluable for debugging why handlers aren't matching or responses aren't arriving. + +**Incorrect (guessing why requests fail):** + +```typescript +// No visibility into what MSW is doing +const server = setupServer(...handlers) +server.listen() + +// Tests fail mysteriously - is the handler matching? Is the response correct? +``` + +**Correct (lifecycle event logging):** + +```typescript +import { setupServer } from 'msw/node' +import { handlers } from './handlers' + +const server = setupServer(...handlers) + +// Log all intercepted requests +server.events.on('request:start', ({ request }) => { + console.log('MSW intercepted:', request.method, request.url) +}) + +// Log when a handler matches +server.events.on('request:match', ({ request }) => { + console.log('MSW matched:', request.method, request.url) +}) + +// Log completed responses +server.events.on('request:end', ({ request, response }) => { + console.log( + 'MSW responded:', + request.method, + request.url, + '→', + response.status + ) +}) + +// Log unhandled requests +server.events.on('request:unhandled', ({ request }) => { + console.warn('MSW unhandled:', request.method, request.url) +}) +``` + +**Conditional logging:** + +```typescript +// Only log in debug mode +if (process.env.DEBUG_MSW) { + server.events.on('request:start', ({ request }) => { + console.log('[MSW]', request.method, request.url) + }) +} +``` + +**Event types:** +- `request:start` - Request intercepted by MSW +- `request:match` - Handler found for request +- `request:unhandled` - No handler matched +- `request:end` - Response sent (mocked or passthrough) +- `response:mocked` - Mocked response sent +- `response:bypass` - Request passed through to network + +**Cleanup:** + +```typescript +// Remove event listeners when done +const unsubscribe = server.events.on('request:start', handler) +unsubscribe() // Remove listener +``` + +**When NOT to use this pattern:** +- Production builds should not include debug logging +- CI environments may want minimal logging for cleaner output + +Reference: [MSW Lifecycle Events](https://mswjs.io/docs/api/life-cycle-events) diff --git a/.agents/skills/msw/references/debug-request-logging.md b/.agents/skills/msw/references/debug-request-logging.md new file mode 100644 index 0000000..87f2a2a --- /dev/null +++ b/.agents/skills/msw/references/debug-request-logging.md @@ -0,0 +1,113 @@ +--- +title: Log Request Details for Debugging +impact: LOW +impactDescription: Provides detailed request inspection; identifies payload issues +tags: debug, logging, request, inspection, development +--- + +## Log Request Details for Debugging + +Create a debugging middleware handler to log full request details. This helps identify issues with request payloads, headers, and authentication. + +**Incorrect (no request visibility):** + +```typescript +// Can't see what's being sent to handlers +http.post('/api/user', async ({ request }) => { + const body = await request.json() + // body is unexpected - but why? + return HttpResponse.json({ error: 'Invalid data' }, { status: 400 }) +}) +``` + +**Correct (detailed request logging):** + +```typescript +import { http, HttpResponse } from 'msw' + +// Debug middleware - add as first handler +const debugHandler = http.all('*', async ({ request }) => { + const url = new URL(request.url) + const clone = request.clone() + + console.group(`[MSW] ${request.method} ${url.pathname}`) + console.log('Full URL:', request.url) + console.log('Headers:', Object.fromEntries(request.headers.entries())) + + // Log body for non-GET requests + if (request.method !== 'GET' && request.method !== 'HEAD') { + const contentType = request.headers.get('Content-Type') + + if (contentType?.includes('application/json')) { + console.log('Body (JSON):', await clone.json()) + } else if (contentType?.includes('multipart/form-data')) { + const formData = await clone.formData() + console.log('Body (FormData):', Object.fromEntries(formData.entries())) + } else { + console.log('Body (Text):', await clone.text()) + } + } + + console.groupEnd() + + // Don't return - let next handler process the request +}) + +export const handlers = [ + debugHandler, // Must be first + // ... other handlers +] +``` + +**Conditional debug mode:** + +```typescript +const DEBUG = process.env.DEBUG_MSW === 'true' + +export const handlers = [ + ...(DEBUG ? [debugHandler] : []), + // ... other handlers +] +``` + +**Response logging:** + +```typescript +// Log responses using lifecycle events +server.events.on('request:end', async ({ request, response }) => { + if (!response) return + + const clone = response.clone() + const contentType = response.headers.get('Content-Type') + + console.log(`[MSW Response] ${request.method} ${request.url}`) + console.log('Status:', response.status) + + if (contentType?.includes('application/json')) { + console.log('Body:', await clone.json()) + } +}) +``` + +**Development browser logging:** + +```typescript +// mocks/browser.ts +import { setupWorker } from 'msw/browser' +import { handlers } from './handlers' + +export const worker = setupWorker(...handlers) + +// Enable detailed logging in development +if (process.env.NODE_ENV === 'development') { + worker.start({ + onUnhandledRequest: 'warn', + }) +} +``` + +**When NOT to use this pattern:** +- Remove debug logging before committing/production +- CI should use minimal logging for cleaner output + +Reference: [MSW Lifecycle Events](https://mswjs.io/docs/api/life-cycle-events) diff --git a/.agents/skills/msw/references/debug-verify-interception.md b/.agents/skills/msw/references/debug-verify-interception.md new file mode 100644 index 0000000..2b618c1 --- /dev/null +++ b/.agents/skills/msw/references/debug-verify-interception.md @@ -0,0 +1,95 @@ +--- +title: Verify Request Interception is Working +impact: LOW +impactDescription: Confirms MSW is active; identifies setup failures early +tags: debug, verification, setup, troubleshooting, runbook +--- + +## Verify Request Interception is Working + +Add a verification step to confirm MSW is intercepting requests. This catches configuration issues before they cause mysterious test failures. + +**Incorrect (assuming MSW is working):** + +```typescript +// No verification - tests fail with confusing errors +beforeAll(() => server.listen()) + +it('fetches user', async () => { + // If MSW isn't working, this hits real API or fails silently + const response = await fetch('/api/user') +}) +``` + +**Correct (verify interception):** + +```typescript +import { setupServer } from 'msw/node' +import { handlers } from './handlers' + +const server = setupServer(...handlers) + +beforeAll(() => { + server.listen() + + // Verify MSW is intercepting + server.events.on('request:start', ({ request }) => { + console.log('✓ MSW intercepted:', request.method, request.url) + }) +}) + +// Or create a verification test +describe('MSW Setup', () => { + it('intercepts requests', async () => { + let intercepted = false + + server.events.on('request:start', () => { + intercepted = true + }) + + await fetch('/api/health') + + expect(intercepted).toBe(true) + }) +}) +``` + +**Debugging checklist when handlers don't match:** + +```typescript +// Step 1: Verify interception is happening +server.events.on('request:start', ({ request }) => { + console.log('Intercepted URL:', request.url) // Check if URL is absolute + console.log('Intercepted method:', request.method) +}) + +// Step 2: Add console.log inside handler +http.get('/api/user', () => { + console.log('Handler matched!') // If this doesn't log, handler isn't matching + return HttpResponse.json({ name: 'John' }) +}) + +// Step 3: Check handler URL vs request URL +// Common issues: +// - Handler: '/api/user' but request goes to 'http://localhost:3000/api/user' +// - Environment variable in URL is undefined +// - Typo in URL path +``` + +**Browser verification:** + +```typescript +// In browser console +const { worker } = await import('./mocks/browser') +await worker.start() + +// Check if worker script is accessible +fetch('/mockServiceWorker.js') + .then((r) => r.ok ? 'Worker script found' : 'Worker script missing') + .then(console.log) +``` + +**When NOT to use this pattern:** +- Stable test suites don't need verification in every run + +Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/) diff --git a/.agents/skills/msw/references/graphql-batched-queries.md b/.agents/skills/msw/references/graphql-batched-queries.md new file mode 100644 index 0000000..257d624 --- /dev/null +++ b/.agents/skills/msw/references/graphql-batched-queries.md @@ -0,0 +1,93 @@ +--- +title: Handle Batched GraphQL Queries +impact: MEDIUM +impactDescription: Supports Apollo batching; prevents unhandled batch requests +tags: graphql, batching, apollo, performance, advanced +--- + +## Handle Batched GraphQL Queries + +Create a custom handler for batched GraphQL queries when using Apollo Client's batch link or similar. Batched requests send multiple operations in a single HTTP request. + +**Incorrect (individual handlers don't match batches):** + +```typescript +// These won't match a batched request containing both queries +graphql.query('GetUser', () => { + return HttpResponse.json({ data: { user: { name: 'John' } } }) +}) + +graphql.query('GetPosts', () => { + return HttpResponse.json({ data: { posts: [] } }) +}) + +// Batched request is unhandled! +``` + +**Correct (batch handler with individual resolution):** + +```typescript +import { http, HttpResponse, getResponse, bypass } from 'msw' + +export function batchedGraphQLQuery(url: string, handlers: RequestHandler[]) { + return http.post(url, async ({ request }) => { + const requestClone = request.clone() + const payload = await request.json() + + // Ignore non-batched requests + if (!Array.isArray(payload)) { + return + } + + // Resolve each query in the batch + const responses = await Promise.all( + payload.map(async (operation) => { + const queryRequest = new Request(requestClone.url, { + method: 'POST', + headers: requestClone.headers, + body: JSON.stringify(operation), + }) + + const response = await getResponse(handlers, queryRequest) + return response || fetch(bypass(queryRequest)) + }) + ) + + // Combine responses into batch format + const results = await Promise.all( + responses.map((response) => response?.json()) + ) + + return HttpResponse.json(results) + }) +} +``` + +```typescript +// Usage +import { graphql, HttpResponse } from 'msw' +import { batchedGraphQLQuery } from './batchedGraphQLQuery' + +const graphqlHandlers = [ + graphql.query('GetUser', () => { + return HttpResponse.json({ + data: { user: { id: '1', name: 'John' } }, + }) + }), + graphql.query('GetPosts', () => { + return HttpResponse.json({ + data: { posts: [{ id: '1', title: 'Post 1' }] }, + }) + }), +] + +export const handlers = [ + batchedGraphQLQuery('/graphql', graphqlHandlers), + ...graphqlHandlers, // Also handle non-batched requests +] +``` + +**When NOT to use this pattern:** +- Apps not using query batching don't need batch handlers + +Reference: [MSW GraphQL Query Batching](https://mswjs.io/docs/graphql/mocking-responses/query-batching) diff --git a/.agents/skills/msw/references/graphql-error-responses.md b/.agents/skills/msw/references/graphql-error-responses.md new file mode 100644 index 0000000..36f6bc2 --- /dev/null +++ b/.agents/skills/msw/references/graphql-error-responses.md @@ -0,0 +1,119 @@ +--- +title: Return GraphQL Errors in Correct Format +impact: MEDIUM +impactDescription: Ensures GraphQL clients parse errors correctly; tests error handling +tags: graphql, errors, format, validation, response +--- + +## Return GraphQL Errors in Correct Format + +Return GraphQL errors in the standard `errors` array format. GraphQL errors are different from HTTP errors - they use status 200 with an `errors` field in the response body. + +**Incorrect (HTTP-style error response):** + +```typescript +// GraphQL clients won't recognize this as a GraphQL error +graphql.query('GetUser', () => { + return HttpResponse.json( + { error: 'User not found' }, + { status: 404 } + ) +}) +``` + +**Correct (GraphQL error format):** + +```typescript +import { graphql, HttpResponse } from 'msw' + +export const handlers = [ + // Single error + graphql.query('GetUser', () => { + return HttpResponse.json({ + data: null, + errors: [ + { + message: 'User not found', + extensions: { + code: 'NOT_FOUND', + }, + }, + ], + }) + }), + + // Validation errors with paths + graphql.mutation('CreateUser', () => { + return HttpResponse.json({ + data: null, + errors: [ + { + message: 'Invalid email format', + path: ['createUser', 'email'], + extensions: { + code: 'VALIDATION_ERROR', + field: 'email', + }, + }, + { + message: 'Name is required', + path: ['createUser', 'name'], + extensions: { + code: 'VALIDATION_ERROR', + field: 'name', + }, + }, + ], + }) + }), + + // Partial success with errors + graphql.query('GetUsers', () => { + return HttpResponse.json({ + data: { + users: [ + { id: '1', name: 'John' }, + null, // This user failed to load + { id: '3', name: 'Jane' }, + ], + }, + errors: [ + { + message: 'Failed to load user', + path: ['users', 1], + extensions: { code: 'INTERNAL_ERROR' }, + }, + ], + }) + }), + + // Authentication error + graphql.query('GetPrivateData', () => { + return HttpResponse.json({ + data: null, + errors: [ + { + message: 'Not authenticated', + extensions: { + code: 'UNAUTHENTICATED', + }, + }, + ], + }) + }), +] +``` + +**Network-level errors (rare):** + +```typescript +// For complete request failures, use HTTP error +graphql.query('GetUser', () => { + return HttpResponse.error() // Network failure +}) +``` + +**When NOT to use this pattern:** +- True network failures (DNS, connection) use `HttpResponse.error()` + +Reference: [GraphQL Spec - Errors](https://spec.graphql.org/October2021/#sec-Errors) diff --git a/.agents/skills/msw/references/graphql-operation-handlers.md b/.agents/skills/msw/references/graphql-operation-handlers.md new file mode 100644 index 0000000..398067e --- /dev/null +++ b/.agents/skills/msw/references/graphql-operation-handlers.md @@ -0,0 +1,101 @@ +--- +title: Use Operation Name for GraphQL Matching +impact: MEDIUM +impactDescription: Enables precise operation targeting; prevents query/mutation conflicts +tags: graphql, operation, query, mutation, matching +--- + +## Use Operation Name for GraphQL Matching + +Match GraphQL operations by their operation name, not by URL. All GraphQL requests typically go to the same endpoint (`/graphql`), so operation name is the discriminator. + +**Incorrect (URL-based matching for GraphQL):** + +```typescript +// All GraphQL requests go to /graphql - this catches everything! +http.post('/graphql', () => { + return HttpResponse.json({ data: { user: { name: 'John' } } }) +}) +``` + +**Correct (operation-based matching):** + +```typescript +import { graphql, HttpResponse } from 'msw' + +export const handlers = [ + // Match query by operation name + graphql.query('GetUser', () => { + return HttpResponse.json({ + data: { + user: { + id: '1', + name: 'John', + email: 'john@example.com', + }, + }, + }) + }), + + // Match mutation by operation name + graphql.mutation('CreateUser', async ({ variables }) => { + return HttpResponse.json({ + data: { + createUser: { + id: crypto.randomUUID(), + name: variables.name, + email: variables.email, + }, + }, + }) + }), + + // Separate handlers for different queries + graphql.query('GetUsers', () => { + return HttpResponse.json({ + data: { + users: [ + { id: '1', name: 'John' }, + { id: '2', name: 'Jane' }, + ], + }, + }) + }), +] +``` + +**Access operation variables:** + +```typescript +graphql.query('GetUser', ({ variables }) => { + // variables matches your GraphQL query variables + return HttpResponse.json({ + data: { + user: { + id: variables.id, + name: 'John', + }, + }, + }) +}) + +// Query from client: +// query GetUser($id: ID!) { user(id: $id) { id name } } +// variables: { id: "123" } +``` + +**Custom GraphQL endpoint:** + +```typescript +// If your GraphQL endpoint isn't /graphql +graphql.link('https://api.example.com/gql').query('GetUser', () => { + return HttpResponse.json({ + data: { user: { name: 'John' } }, + }) +}) +``` + +**When NOT to use this pattern:** +- REST APIs should use `http.*` handlers, not GraphQL handlers + +Reference: [MSW GraphQL API](https://mswjs.io/docs/api/graphql) diff --git a/.agents/skills/msw/references/graphql-schema-first.md b/.agents/skills/msw/references/graphql-schema-first.md new file mode 100644 index 0000000..2979951 --- /dev/null +++ b/.agents/skills/msw/references/graphql-schema-first.md @@ -0,0 +1,76 @@ +--- +title: Resolve Operations Against a GraphQL Schema +impact: MEDIUM +impactDescription: schema-accurate mocks without hand-writing response shapes +tags: msw, graphql, schema, operation +--- + +## Resolve Operations Against a GraphQL Schema + +Instead of hand-writing every mocked GraphQL response, execute intercepted operations against a real schema with the `graphql` package inside a `graphql.operation()` catch-all handler. Responses stay schema-valid as operations evolve, and resolvers live in one place. + +**Incorrect (hand-maintained response shapes per operation):** + +```typescript +// Every handler duplicates the response shape; a schema change +// silently leaves stale mocks that no longer match production +export const handlers = [ + graphql.query('GetUser', () => + HttpResponse.json({ data: { user: { id: '1', firstName: 'John' } } }), + ), + graphql.query('GetUserWithPosts', () => + HttpResponse.json({ + data: { user: { id: '1', firstName: 'John', posts: [] } }, + }), + ), +] +``` + +**Correct (schema-first resolution):** + +```typescript +import { graphql, HttpResponse } from 'msw' +import { graphql as executeGraphql, buildSchema } from 'graphql' + +const schema = buildSchema(` + type User { + id: ID! + firstName: String! + } + + type Query { + user(id: ID!): User + } +`) + +const data = { + users: [ + { id: '1', name: 'John' }, + { id: '2', name: 'Kate' }, + ], +} + +export const handlers = [ + graphql.operation(async ({ query, variables }) => { + const { data, errors } = await executeGraphql({ + schema, + source: query, + variableValues: variables, + rootValue: { + user(args) { + return data.users.find((user) => user.id === args.id) + }, + }, + }) + + return HttpResponse.json({ data, errors }) + }), +] +``` + +**Notes:** + +- `graphql.operation()` matches every operation; place more specific named-operation handlers above it when you need per-test overrides. +- The `graphql` package (`buildSchema`, `graphql()`) is a peer dependency you install alongside MSW. +- Because resolution runs against the schema, invalid client queries surface real GraphQL `errors` in the mocked response — useful for testing error UI. +- Pair with [graphql-operation-handlers](graphql-operation-handlers.md) for targeted overrides and [graphql-error-responses](graphql-error-responses.md) for error-shape rules. diff --git a/.agents/skills/msw/references/graphql-variables-access.md b/.agents/skills/msw/references/graphql-variables-access.md new file mode 100644 index 0000000..9853b9b --- /dev/null +++ b/.agents/skills/msw/references/graphql-variables-access.md @@ -0,0 +1,123 @@ +--- +title: Access GraphQL Variables Correctly +impact: MEDIUM +impactDescription: Enables dynamic mock responses based on query input +tags: graphql, variables, dynamic, input, resolver +--- + +## Access GraphQL Variables Correctly + +Access GraphQL variables through the `variables` property in the resolver argument. Use them to return dynamic responses based on query input. + +**Incorrect (ignoring variables):** + +```typescript +// Returns same user regardless of which ID is requested +graphql.query('GetUser', () => { + return HttpResponse.json({ + data: { + user: { id: '1', name: 'John' }, + }, + }) +}) +``` + +**Correct (using variables for dynamic responses):** + +```typescript +import { graphql, HttpResponse } from 'msw' + +// Mock data store +const users = new Map([ + ['1', { id: '1', name: 'John', email: 'john@example.com' }], + ['2', { id: '2', name: 'Jane', email: 'jane@example.com' }], +]) + +export const handlers = [ + graphql.query('GetUser', ({ variables }) => { + const user = users.get(variables.id) + + if (!user) { + return HttpResponse.json({ + data: null, + errors: [{ message: 'User not found' }], + }) + } + + return HttpResponse.json({ + data: { user }, + }) + }), + + // Mutation with input variables + graphql.mutation('UpdateUser', ({ variables }) => { + const { id, input } = variables + const existingUser = users.get(id) + + if (!existingUser) { + return HttpResponse.json({ + data: null, + errors: [{ message: 'User not found' }], + }) + } + + const updatedUser = { ...existingUser, ...input } + users.set(id, updatedUser) + + return HttpResponse.json({ + data: { updateUser: updatedUser }, + }) + }), + + // Pagination with variables + graphql.query('GetUsers', ({ variables }) => { + const { first = 10, after } = variables + const allUsers = Array.from(users.values()) + + let startIndex = 0 + if (after) { + startIndex = allUsers.findIndex((u) => u.id === after) + 1 + } + + const pageUsers = allUsers.slice(startIndex, startIndex + first) + const hasNextPage = startIndex + first < allUsers.length + + return HttpResponse.json({ + data: { + users: { + edges: pageUsers.map((user) => ({ + node: user, + cursor: user.id, + })), + pageInfo: { + hasNextPage, + endCursor: pageUsers[pageUsers.length - 1]?.id, + }, + }, + }, + }) + }), +] +``` + +**Type-safe variables:** + +```typescript +type GetUserVariables = { + id: string +} + +graphql.query('GetUser', ({ variables }) => { + // variables.id is typed as string + return HttpResponse.json({ + data: { + user: { id: variables.id, name: 'John' }, + }, + }) +}) +``` + +**When NOT to use this pattern:** +- Queries without variables don't need variable access + +Reference: [MSW GraphQL Intercepting Operations](https://mswjs.io/docs/graphql/intercepting-operations) diff --git a/.agents/skills/msw/references/handler-absolute-urls.md b/.agents/skills/msw/references/handler-absolute-urls.md new file mode 100644 index 0000000..5f6b8fd --- /dev/null +++ b/.agents/skills/msw/references/handler-absolute-urls.md @@ -0,0 +1,70 @@ +--- +title: Use Absolute URLs in Handlers +impact: CRITICAL +impactDescription: Prevents URL mismatch failures; required for Node.js environments +tags: handler, url, absolute, node, matching +--- + +## Use Absolute URLs in Handlers + +Use absolute URLs or URL patterns in request handlers. Node.js environments require absolute URLs for proper matching, and relative URLs cause silent handler failures. + +**Incorrect (relative URLs in Node.js context):** + +```typescript +// mocks/handlers.ts +export const handlers = [ + // Relative URL - may not match in Node.js tests + http.get('/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), +] + +// Test makes request to full URL +await fetch('http://localhost:3000/api/user') +// Handler doesn't match - request goes unhandled +``` + +**Correct (absolute URLs or wildcards):** + +```typescript +// mocks/handlers.ts +export const handlers = [ + // Absolute URL - matches reliably + http.get('http://localhost:3000/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), +] +``` + +**Better (wildcard for any origin):** + +```typescript +// mocks/handlers.ts +export const handlers = [ + // Wildcard matches any origin - most flexible + http.get('*/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), + + // Or use path patterns that MSW resolves against baseURL + http.get('/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), +] +``` + +**Environment variable pitfall:** + +```typescript +// AVOID: Environment variable not set in tests +const API_URL = process.env.API_URL // undefined in tests! + +http.get(`${API_URL}/user`, () => { /* ... */ }) +// Results in: http.get('undefined/user', ...) - never matches +``` + +**When NOT to use this pattern:** +- Browser environments with properly configured base URLs may use relative paths + +Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/) diff --git a/.agents/skills/msw/references/handler-domain-grouping.md b/.agents/skills/msw/references/handler-domain-grouping.md new file mode 100644 index 0000000..0302e5d --- /dev/null +++ b/.agents/skills/msw/references/handler-domain-grouping.md @@ -0,0 +1,81 @@ +--- +title: Group Handlers by Domain +impact: CRITICAL +impactDescription: Reduces maintenance overhead; scales to large APIs without N×M complexity +tags: handler, organization, domain, modules, scalability +--- + +## Group Handlers by Domain + +Split handlers into separate files organized by domain or feature area. This prevents a single handlers file from becoming unmanageable and enables selective handler composition for different test scenarios. + +**Incorrect (monolithic handler file):** + +```typescript +// mocks/handlers.ts - 500+ lines, unmaintainable +export const handlers = [ + // User endpoints + http.get('/api/user', () => { /* ... */ }), + http.post('/api/user', () => { /* ... */ }), + http.delete('/api/user/:id', () => { /* ... */ }), + // Auth endpoints + http.post('/api/login', () => { /* ... */ }), + http.post('/api/logout', () => { /* ... */ }), + // Product endpoints + http.get('/api/products', () => { /* ... */ }), + // ... 50 more endpoints mixed together +] +``` + +**Correct (domain-organized handlers):** + +```typescript +// mocks/handlers/user.ts +import { http, HttpResponse } from 'msw' + +export const userHandlers = [ + http.get('/api/user', () => { + return HttpResponse.json({ id: '1', name: 'John' }) + }), + http.post('/api/user', async ({ request }) => { + const user = await request.json() + return HttpResponse.json(user, { status: 201 }) + }), + http.delete('/api/user/:id', ({ params }) => { + return new HttpResponse(null, { status: 204 }) + }), +] +``` + +```typescript +// mocks/handlers/auth.ts +import { http, HttpResponse } from 'msw' + +export const authHandlers = [ + http.post('/api/login', async ({ request }) => { + const { email, password } = await request.json() + return HttpResponse.json({ token: 'jwt-token' }) + }), + http.post('/api/logout', () => { + return new HttpResponse(null, { status: 200 }) + }), +] +``` + +```typescript +// mocks/handlers/index.ts - compose all handlers +import { userHandlers } from './user' +import { authHandlers } from './auth' +import { productHandlers } from './products' + +export const handlers = [ + ...userHandlers, + ...authHandlers, + ...productHandlers, +] +``` + +**When NOT to use this pattern:** +- Small projects with fewer than 10 endpoints may use a single file + +Reference: [Structuring Handlers - Group by Domain](https://mswjs.io/docs/best-practices/structuring-handlers) diff --git a/.agents/skills/msw/references/handler-happy-path-first.md b/.agents/skills/msw/references/handler-happy-path-first.md new file mode 100644 index 0000000..f214391 --- /dev/null +++ b/.agents/skills/msw/references/handler-happy-path-first.md @@ -0,0 +1,60 @@ +--- +title: Define Happy Path Handlers as Baseline +impact: CRITICAL +impactDescription: Establishes reliable baseline; enables clean runtime overrides +tags: handler, structure, happy-path, baseline, organization +--- + +## Define Happy Path Handlers as Baseline + +Define success-state handlers in a central `handlers.ts` file as your baseline. This establishes a reliable foundation that runtime overrides can modify for error scenarios, keeping test-specific edge cases separate from normal behavior. + +**Incorrect (mixing success and error states):** + +```typescript +// mocks/handlers.ts - cluttered with all scenarios +export const handlers = [ + http.get('/user', () => HttpResponse.json({ name: 'John' })), + http.get('/user', () => new HttpResponse(null, { status: 401 })), + http.get('/user', () => new HttpResponse(null, { status: 500 })), + http.get('/user', () => HttpResponse.error()), + // Confusing: which handler runs? Last one wins but intent unclear +] +``` + +**Correct (happy path baseline with runtime overrides):** + +```typescript +// mocks/handlers.ts - clean success states only +import { http, HttpResponse } from 'msw' + +export const handlers = [ + http.get('/api/user', () => { + return HttpResponse.json({ id: '1', name: 'John Maverick' }) + }), + http.post('/api/login', async ({ request }) => { + const { email } = await request.json() + return HttpResponse.json({ token: 'mock-jwt-token', email }) + }), +] +``` + +```typescript +// user.test.ts - override for specific scenarios +import { http, HttpResponse } from 'msw' +import { server } from '../mocks/node' + +it('handles authentication error', () => { + server.use( + http.get('/api/user', () => { + return new HttpResponse(null, { status: 401 }) + }) + ) + // Test error handling... +}) +``` + +**When NOT to use this pattern:** +- Single-use test utilities that will never need runtime overrides + +Reference: [Structuring Handlers](https://mswjs.io/docs/best-practices/structuring-handlers) diff --git a/.agents/skills/msw/references/handler-request-body-parsing.md b/.agents/skills/msw/references/handler-request-body-parsing.md new file mode 100644 index 0000000..25f3235 --- /dev/null +++ b/.agents/skills/msw/references/handler-request-body-parsing.md @@ -0,0 +1,76 @@ +--- +title: Explicitly Parse Request Bodies +impact: CRITICAL +impactDescription: v2 no longer auto-parses bodies; missing parsing returns undefined +tags: handler, request, body, parsing, json +--- + +## Explicitly Parse Request Bodies + +MSW v2 does not automatically parse request bodies based on Content-Type. You must explicitly call `.json()`, `.text()`, `.formData()`, or `.arrayBuffer()` on the request object. + +**Incorrect (assuming auto-parsed body):** + +```typescript +// MSW v1 pattern - body was auto-parsed +http.post('/api/user', ({ request }) => { + const body = request.body // a ReadableStream in v2, not parsed data + return HttpResponse.json({ id: '1', ...body }) +}) +``` + +**Correct (explicit body parsing):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // JSON body + http.post('/api/user', async ({ request }) => { + const body = await request.json() + return HttpResponse.json({ id: '1', ...body }, { status: 201 }) + }), + + // Text body + http.post('/api/text', async ({ request }) => { + const text = await request.text() + return HttpResponse.text(`Received: ${text}`) + }), + + // Form data + http.post('/api/upload', async ({ request }) => { + const formData = await request.formData() + const file = formData.get('file') + return HttpResponse.json({ filename: file?.name }) + }), + + // ArrayBuffer for binary + http.post('/api/binary', async ({ request }) => { + const buffer = await request.arrayBuffer() + return HttpResponse.json({ bytes: buffer.byteLength }) + }), +] +``` + +**Typed body parsing:** + +```typescript +interface CreateUserRequest { + name: string + email: string +} + +http.post('/api/user', async ({ request }) => { + const body = await request.json() as CreateUserRequest + return HttpResponse.json({ + id: crypto.randomUUID(), + name: body.name, + email: body.email, + }) +}) +``` + +**When NOT to use this pattern:** +- GET requests typically don't have bodies and don't need parsing + +Reference: [MSW v2 Migration - Request Changes](https://mswjs.io/docs/migrations/1.x-to-2.x/) diff --git a/.agents/skills/msw/references/handler-resolver-argument.md b/.agents/skills/msw/references/handler-resolver-argument.md new file mode 100644 index 0000000..9794299 --- /dev/null +++ b/.agents/skills/msw/references/handler-resolver-argument.md @@ -0,0 +1,86 @@ +--- +title: Destructure Resolver Arguments Correctly +impact: CRITICAL +impactDescription: Wrong destructuring pattern causes undefined values; silent failures +tags: handler, resolver, params, cookies, request, destructuring +--- + +## Destructure Resolver Arguments Correctly + +MSW v2 passes a single object argument to resolvers containing `request`, `params`, `cookies`, and other properties. Destructure from this object instead of using multiple arguments. + +**Incorrect (v1 multiple arguments pattern):** + +```typescript +// MSW v1 pattern - does not work in v2 +http.get('/api/user/:id', (req, res, ctx) => { + const userId = req.params.id // undefined! + return res(ctx.json({ id: userId })) +}) +``` + +**Correct (v2 single object argument):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Destructure from single argument object + http.get('/api/user/:id', ({ request, params, cookies }) => { + return HttpResponse.json({ + id: params.id, + sessionId: cookies.sessionId, + userAgent: request.headers.get('User-Agent'), + }) + }), +] +``` + +**Available resolver properties:** + +```typescript +http.post('/api/data', async (info) => { + // Full request object + const { request } = info + + // URL path parameters + const { params } = info // { id: '123' } for /api/data/:id + + // Parsed cookies from Cookie header + const { cookies } = info // { session: 'abc', token: 'xyz' } + + // Request URL as string (not URL object) + const url = new URL(request.url) + + // Request method + const method = request.method + + // Request headers + const authHeader = request.headers.get('Authorization') + + // Request body (must await) + const body = await request.json() + + return HttpResponse.json({ success: true }) +}) +``` + +**Type-safe params:** + +```typescript +// Define params type for better type safety +type UserParams = { + id: string + orgId: string +} + +http.get('/api/org/:orgId/user/:id', ({ params }) => { + // params.id and params.orgId are typed as string + return HttpResponse.json({ userId: params.id, orgId: params.orgId }) +}) +``` + +**When NOT to use this pattern:** +- This is the only pattern in MSW v2; no alternatives + +Reference: [MSW v2 Migration - Resolver Changes](https://mswjs.io/docs/migrations/1.x-to-2.x/) diff --git a/.agents/skills/msw/references/handler-reusability-environments.md b/.agents/skills/msw/references/handler-reusability-environments.md new file mode 100644 index 0000000..17db61e --- /dev/null +++ b/.agents/skills/msw/references/handler-reusability-environments.md @@ -0,0 +1,80 @@ +--- +title: Share Handlers Across Environments +impact: CRITICAL +impactDescription: Single source of truth; eliminates mock drift between dev/test +tags: handler, reuse, environment, browser, node, integration +--- + +## Share Handlers Across Environments + +Define handlers once and reuse them across browser (development) and Node.js (testing) environments. This ensures mock behavior is consistent and prevents drift between development and test mocks. + +**Incorrect (duplicate handlers per environment):** + +```typescript +// mocks/browser-handlers.ts - browser development +export const browserHandlers = [ + http.get('/api/user', () => HttpResponse.json({ name: 'Dev User' })), +] + +// mocks/test-handlers.ts - tests (different implementation!) +export const testHandlers = [ + http.get('/api/user', () => HttpResponse.json({ name: 'Test User' })), +] +// Mock behavior differs between environments - bugs hide until production +``` + +**Correct (shared handlers, environment-specific setup):** + +```typescript +// mocks/handlers.ts - single source of truth +import { http, HttpResponse } from 'msw' + +export const handlers = [ + http.get('/api/user', () => { + return HttpResponse.json({ id: '1', name: 'John Maverick' }) + }), + http.get('/api/posts', () => { + return HttpResponse.json([ + { id: '1', title: 'First Post' }, + { id: '2', title: 'Second Post' }, + ]) + }), +] +``` + +```typescript +// mocks/browser.ts - browser setup +import { setupWorker } from 'msw/browser' +import { handlers } from './handlers' + +export const worker = setupWorker(...handlers) +``` + +```typescript +// mocks/node.ts - Node.js setup +import { setupServer } from 'msw/node' +import { handlers } from './handlers' + +export const server = setupServer(...handlers) +``` + +```typescript +// src/index.tsx - conditional browser activation +async function enableMocking() { + if (process.env.NODE_ENV !== 'development') { + return + } + const { worker } = await import('./mocks/browser') + return worker.start() +} + +enableMocking().then(() => { + ReactDOM.createRoot(document.getElementById('root')!).render() +}) +``` + +**When NOT to use this pattern:** +- Environment-specific handlers (e.g., browser-only features) can be added via separate arrays + +Reference: [MSW Comparison - Reusability](https://mswjs.io/docs/comparison) diff --git a/.agents/skills/msw/references/handler-shared-resolvers.md b/.agents/skills/msw/references/handler-shared-resolvers.md new file mode 100644 index 0000000..80bccb6 --- /dev/null +++ b/.agents/skills/msw/references/handler-shared-resolvers.md @@ -0,0 +1,99 @@ +--- +title: Extract Shared Response Logic into Resolvers +impact: CRITICAL +impactDescription: Eliminates duplication; ensures consistent mock responses across tests +tags: handler, resolver, reuse, abstraction, dry +--- + +## Extract Shared Response Logic into Resolvers + +Extract repetitive response logic into reusable resolver functions. This ensures consistency across handlers and reduces maintenance when response shapes change. + +**Incorrect (duplicated response logic):** + +```typescript +// mocks/handlers.ts +export const handlers = [ + http.get('/api/user/:id', ({ params }) => { + return HttpResponse.json({ + id: params.id, + name: 'John', + email: 'john@example.com', + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString(), + }) + }), + http.get('/api/users', () => { + return HttpResponse.json([ + { + id: '1', + name: 'John', + email: 'john@example.com', + createdAt: new Date().toISOString(), // Duplicated shape + updatedAt: new Date().toISOString(), + }, + // ... more users with same structure + ]) + }), +] +``` + +**Correct (shared resolver factories):** + +```typescript +// mocks/factories/user.ts +import { faker } from '@faker-js/faker' + +export function createMockUser(overrides: Partial = {}): User { + return { + id: faker.string.uuid(), + name: faker.person.fullName(), + email: faker.internet.email(), + createdAt: faker.date.past().toISOString(), + updatedAt: faker.date.recent().toISOString(), + ...overrides, + } +} +``` + +```typescript +// mocks/handlers/user.ts +import { http, HttpResponse } from 'msw' +import { createMockUser } from '../factories/user' + +export const userHandlers = [ + http.get('/api/user/:id', ({ params }) => { + return HttpResponse.json(createMockUser({ id: params.id as string })) + }), + http.get('/api/users', () => { + return HttpResponse.json([ + createMockUser(), + createMockUser(), + createMockUser(), + ]) + }), +] +``` + +**Higher-order handler for cross-cutting concerns:** + +```typescript +// mocks/utils/withAuth.ts +import { HttpResponse } from 'msw' +import type { HttpResponseResolver } from 'msw' + +export function withAuth(resolver: HttpResponseResolver): HttpResponseResolver { + return ({ request, ...rest }) => { + const authHeader = request.headers.get('Authorization') + if (!authHeader?.startsWith('Bearer ')) { + return new HttpResponse(null, { status: 401 }) + } + return resolver({ request, ...rest }) + } +} +``` + +**When NOT to use this pattern:** +- One-off handlers for specific test scenarios don't need abstraction + +Reference: [Structuring Handlers](https://mswjs.io/docs/best-practices/structuring-handlers) diff --git a/.agents/skills/msw/references/handler-v2-response-syntax.md b/.agents/skills/msw/references/handler-v2-response-syntax.md new file mode 100644 index 0000000..bc5d190 --- /dev/null +++ b/.agents/skills/msw/references/handler-v2-response-syntax.md @@ -0,0 +1,94 @@ +--- +title: Use MSW v2 Response Syntax +impact: CRITICAL +impactDescription: v1 syntax breaks in v2; causes complete handler failure +tags: handler, response, v2, HttpResponse, migration +--- + +## Use MSW v2 Response Syntax + +MSW v2 replaces the composition-based `res(ctx.json())` syntax with native `Response` and `HttpResponse`. Using v1 syntax in v2 causes handlers to fail silently. + +**Incorrect (v1 composition syntax):** + +```typescript +// MSW v1 syntax - does not work in v2 +import { rest } from 'msw' + +export const handlers = [ + rest.get('/api/user', (req, res, ctx) => { + return res( + ctx.status(200), + ctx.json({ name: 'John' }), + ctx.delay(100) + ) + }), +] +``` + +**Correct (v2 HttpResponse syntax):** + +```typescript +// MSW v2 syntax +import { http, HttpResponse, delay } from 'msw' + +export const handlers = [ + http.get('/api/user', async () => { + await delay(100) + return HttpResponse.json( + { name: 'John' }, + { status: 200 } + ) + }), +] +``` + +**Common v2 response patterns:** + +```typescript +import { http, HttpResponse, delay } from 'msw' + +export const handlers = [ + // JSON response + http.get('/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), + + // Text response + http.get('/api/text', () => { + return HttpResponse.text('Hello, World!') + }), + + // XML response + http.get('/api/xml', () => { + return HttpResponse.xml('John') + }), + + // Empty response with status + http.delete('/api/user/:id', () => { + return new HttpResponse(null, { status: 204 }) + }), + + // Custom headers + http.get('/api/data', () => { + return HttpResponse.json( + { data: 'value' }, + { + headers: { + 'X-Custom-Header': 'custom-value', + }, + } + ) + }), + + // Network error + http.get('/api/error', () => { + return HttpResponse.error() + }), +] +``` + +**When NOT to use this pattern:** +- Projects still on MSW v1 should use the v1 syntax until migration + +Reference: [MSW v2 Migration Guide](https://mswjs.io/docs/migrations/1.x-to-2.x/) diff --git a/.agents/skills/msw/references/match-custom-predicate.md b/.agents/skills/msw/references/match-custom-predicate.md new file mode 100644 index 0000000..f537d4c --- /dev/null +++ b/.agents/skills/msw/references/match-custom-predicate.md @@ -0,0 +1,99 @@ +--- +title: Use Custom Predicates for Complex Matching +impact: MEDIUM-HIGH +impactDescription: Enables header-based, body-based, and conditional request matching +tags: match, predicate, custom, conditional, advanced +--- + +## Use Custom Predicates for Complex Matching + +Use a predicate function instead of a URL string for complex matching logic. This enables matching based on headers, request body, cookies, or any combination of request properties. + +**Incorrect (multiple handlers for same URL):** + +```typescript +// Awkward - two handlers for same URL with different behavior +http.get('/api/data', () => { + return HttpResponse.json({ public: true }) +}) + +// How to handle authenticated vs unauthenticated? +``` + +**Correct (predicate-based matching):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Match based on header presence + http.get('/api/data', ({ request }) => { + const authHeader = request.headers.get('Authorization') + + if (authHeader?.startsWith('Bearer ')) { + return HttpResponse.json({ data: 'authenticated content' }) + } + + return HttpResponse.json( + { error: 'Unauthorized' }, + { status: 401 } + ) + }), +] +``` + +**Predicate function syntax:** + +```typescript +// Match by custom criteria +http.all( + ({ request }) => { + // Return true to match this request + return request.url.includes('/api/') && + request.headers.get('X-Custom-Header') === 'special' + }, + () => { + return HttpResponse.json({ matched: true }) + } +) +``` + +**Match by request body content:** + +```typescript +http.post( + '/api/action', + async ({ request }) => { + const body = await request.clone().json() + + // Different response based on action type + if (body.action === 'create') { + return HttpResponse.json({ id: '1', created: true }) + } + if (body.action === 'delete') { + return new HttpResponse(null, { status: 204 }) + } + + return HttpResponse.json( + { error: 'Unknown action' }, + { status: 400 } + ) + } +) +``` + +**Match by cookie value:** + +```typescript +http.get('/api/user', ({ cookies }) => { + if (cookies.role === 'admin') { + return HttpResponse.json({ permissions: ['read', 'write', 'delete'] }) + } + return HttpResponse.json({ permissions: ['read'] }) +}) +``` + +**When NOT to use this pattern:** +- Simple URL-based matching is clearer when sufficient + +Reference: [MSW Custom Request Predicate](https://mswjs.io/docs/best-practices/custom-request-predicate) diff --git a/.agents/skills/msw/references/match-handler-order.md b/.agents/skills/msw/references/match-handler-order.md new file mode 100644 index 0000000..6f7b804 --- /dev/null +++ b/.agents/skills/msw/references/match-handler-order.md @@ -0,0 +1,93 @@ +--- +title: Order Handlers from Specific to General +impact: MEDIUM-HIGH +impactDescription: Prevents general handlers from shadowing specific ones +tags: match, order, priority, specific, general +--- + +## Order Handlers from Specific to General + +Place more specific handlers before general ones in the handlers array. MSW matches handlers in order, and the first match wins. A wildcard handler placed first will shadow all subsequent handlers. + +**Incorrect (general handler shadows specific):** + +```typescript +export const handlers = [ + // Wildcard matches first - specific handlers never reached! + http.get('/api/*', () => { + return HttpResponse.json({ fallback: true }) + }), + + // Never matches because /api/* already caught it + http.get('/api/user/:id', ({ params }) => { + return HttpResponse.json({ id: params.id, name: 'John' }) + }), +] +``` + +**Correct (specific before general):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Most specific handlers first + http.get('/api/user/:id/settings', ({ params }) => { + return HttpResponse.json({ userId: params.id, theme: 'dark' }) + }), + + http.get('/api/user/:id', ({ params }) => { + return HttpResponse.json({ id: params.id, name: 'John' }) + }), + + http.get('/api/users', () => { + return HttpResponse.json([{ id: '1' }, { id: '2' }]) + }), + + // General fallback last + http.get('/api/*', () => { + return HttpResponse.json( + { error: 'Not found' }, + { status: 404 } + ) + }), +] +``` + +**Middleware with passthrough:** + +```typescript +export const handlers = [ + // Middleware runs first but doesn't return - passes through + http.all('*', async () => { + await delay(50) // Add delay to all requests + // No return = continue to next handler + }), + + // Specific handlers still match + http.get('/api/user', () => { + return HttpResponse.json({ name: 'John' }) + }), +] +``` + +**Runtime handler precedence:** + +```typescript +// Initial handlers +const server = setupServer( + http.get('/api/user', () => HttpResponse.json({ name: 'John' })) +) + +// Runtime handlers are PREPENDED (take precedence) +server.use( + http.get('/api/user', () => HttpResponse.json({ name: 'Jane' })) +) + +// Request to /api/user returns { name: 'Jane' } +``` + +**When NOT to use this pattern:** +- Single handlers don't have ordering concerns + +Reference: [MSW Handler Precedence](https://mswjs.io/docs/concepts/request-handler) diff --git a/.agents/skills/msw/references/match-http-methods.md b/.agents/skills/msw/references/match-http-methods.md new file mode 100644 index 0000000..04d7f6d --- /dev/null +++ b/.agents/skills/msw/references/match-http-methods.md @@ -0,0 +1,98 @@ +--- +title: Match HTTP Methods Explicitly +impact: MEDIUM-HIGH +impactDescription: Prevents cross-method interference; models REST APIs correctly +tags: match, methods, http, get, post, put, delete +--- + +## Match HTTP Methods Explicitly + +Use method-specific handlers (`http.get`, `http.post`, etc.) instead of `http.all`. This prevents a GET handler from accidentally matching POST requests and ensures correct REST API simulation. + +**Incorrect (catching unintended methods):** + +```typescript +// Matches ALL methods - GET, POST, PUT, DELETE, etc. +http.all('/api/user', () => { + return HttpResponse.json({ name: 'John' }) +}) + +// POST /api/user also returns user JSON instead of creating +``` + +**Correct (method-specific handlers):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // GET - retrieve resource + http.get('/api/user/:id', ({ params }) => { + return HttpResponse.json({ id: params.id, name: 'John' }) + }), + + // POST - create resource + http.post('/api/user', async ({ request }) => { + const body = await request.json() + return HttpResponse.json( + { id: crypto.randomUUID(), ...body }, + { status: 201 } + ) + }), + + // PUT - replace resource + http.put('/api/user/:id', async ({ params, request }) => { + const body = await request.json() + return HttpResponse.json({ id: params.id, ...body }) + }), + + // PATCH - partial update + http.patch('/api/user/:id', async ({ params, request }) => { + const updates = await request.json() + return HttpResponse.json({ id: params.id, name: 'John', ...updates }) + }), + + // DELETE - remove resource + http.delete('/api/user/:id', () => { + return new HttpResponse(null, { status: 204 }) + }), + + // HEAD - metadata only + http.head('/api/user/:id', () => { + return new HttpResponse(null, { + headers: { 'X-User-Exists': 'true' }, + }) + }), + + // OPTIONS - CORS preflight + http.options('/api/*', () => { + return new HttpResponse(null, { + headers: { + 'Access-Control-Allow-Origin': '*', + 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE', + }, + }) + }), +] +``` + +**When to use http.all:** + +```typescript +// Global middleware (logging, delay) +http.all('*', async () => { + await delay(50) + // No return - continues to next handler +}) + +// Catch-all fallback for testing +http.all('/api/*', () => { + console.warn('Unhandled API request') + return new HttpResponse(null, { status: 404 }) +}) +``` + +**When NOT to use this pattern:** +- Middleware handlers that should apply to all methods can use `http.all` + +Reference: [MSW HTTP Handlers](https://mswjs.io/docs/api/http) diff --git a/.agents/skills/msw/references/match-query-params.md b/.agents/skills/msw/references/match-query-params.md new file mode 100644 index 0000000..8e9bb12 --- /dev/null +++ b/.agents/skills/msw/references/match-query-params.md @@ -0,0 +1,89 @@ +--- +title: Access Query Parameters from Request URL +impact: MEDIUM-HIGH +impactDescription: Enables filtering, pagination, and search mocking +tags: match, query, search-params, url, filtering +--- + +## Access Query Parameters from Request URL + +Parse query parameters from `request.url` using the `URL` constructor. MSW does not automatically parse query strings, so you must extract them manually. + +**Incorrect (assuming params includes query string):** + +```typescript +http.get('/api/users', ({ params }) => { + // params does NOT contain query parameters! + const page = params.page // undefined + return HttpResponse.json([]) +}) +``` + +**Correct (parse from request.url):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + http.get('/api/users', ({ request }) => { + const url = new URL(request.url) + const page = url.searchParams.get('page') || '1' + const limit = url.searchParams.get('limit') || '10' + const search = url.searchParams.get('search') + + // Mock paginated response + const pageNum = parseInt(page, 10) + const limitNum = parseInt(limit, 10) + + return HttpResponse.json({ + data: mockUsers.slice((pageNum - 1) * limitNum, pageNum * limitNum), + meta: { + page: pageNum, + limit: limitNum, + total: mockUsers.length, + }, + }) + }), + + // Filtering by query params + http.get('/api/products', ({ request }) => { + const url = new URL(request.url) + const category = url.searchParams.get('category') + const minPrice = url.searchParams.get('minPrice') + const maxPrice = url.searchParams.get('maxPrice') + + let products = [...mockProducts] + + if (category) { + products = products.filter((p) => p.category === category) + } + if (minPrice) { + products = products.filter((p) => p.price >= Number(minPrice)) + } + if (maxPrice) { + products = products.filter((p) => p.price <= Number(maxPrice)) + } + + return HttpResponse.json(products) + }), +] +``` + +**Multiple values for same parameter:** + +```typescript +http.get('/api/items', ({ request }) => { + const url = new URL(request.url) + // /api/items?tag=red&tag=blue&tag=green + const tags = url.searchParams.getAll('tag') // ['red', 'blue', 'green'] + + return HttpResponse.json( + mockItems.filter((item) => tags.some((tag) => item.tags.includes(tag))) + ) +}) +``` + +**When NOT to use this pattern:** +- Endpoints that don't use query parameters + +Reference: [MSW query parameters](https://mswjs.io/docs/http/intercepting-requests/query-parameters) diff --git a/.agents/skills/msw/references/match-url-patterns.md b/.agents/skills/msw/references/match-url-patterns.md new file mode 100644 index 0000000..ef096cb --- /dev/null +++ b/.agents/skills/msw/references/match-url-patterns.md @@ -0,0 +1,87 @@ +--- +title: Use URL Path Parameters Correctly +impact: MEDIUM-HIGH +impactDescription: Prevents silent handler mismatches; enables dynamic URL matching +tags: match, url, params, path-parameters, dynamic +--- + +## Use URL Path Parameters Correctly + +Use `:paramName` syntax for dynamic path segments. Parameters are available in the resolver's `params` object. Incorrect patterns cause handlers to never match. + +**Incorrect (literal URL instead of pattern):** + +```typescript +// Only matches exact string "/api/user/123" +http.get('/api/user/123', () => { + return HttpResponse.json({ name: 'John' }) +}) + +// Request to /api/user/456 is unhandled +``` + +**Correct (parameterized URL):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Matches /api/user/123, /api/user/abc, etc. + http.get('/api/user/:id', ({ params }) => { + return HttpResponse.json({ id: params.id, name: 'John' }) + }), + + // Multiple parameters + http.get('/api/org/:orgId/user/:userId', ({ params }) => { + return HttpResponse.json({ + orgId: params.orgId, + userId: params.userId, + }) + }), + + // Optional parameters (use separate handlers) + http.get('/api/posts', () => { + return HttpResponse.json([{ id: '1' }, { id: '2' }]) + }), + http.get('/api/posts/:postId', ({ params }) => { + return HttpResponse.json({ id: params.postId }) + }), +] +``` + +**Wildcard patterns:** + +```typescript +// Match any path starting with /api/ +http.get('/api/*', () => { + return HttpResponse.json({ fallback: true }) +}) + +// Match any origin with specific path +http.get('*/api/user', () => { + return HttpResponse.json({ name: 'John' }) +}) + +// Match all requests of a method +http.get('*', () => { + return HttpResponse.json({ catchAll: true }) +}) +``` + +**Type-safe parameters:** + +```typescript +type UserParams = { + userId: string +} + +http.get('/api/user/:userId', ({ params }) => { + // params.userId is typed as string + return HttpResponse.json({ id: params.userId }) +}) +``` + +**When NOT to use this pattern:** +- Exact URL matching for specific endpoints that never vary + +Reference: [MSW Request Matching](https://mswjs.io/docs/http/intercepting-requests) diff --git a/.agents/skills/msw/references/response-custom-headers.md b/.agents/skills/msw/references/response-custom-headers.md new file mode 100644 index 0000000..e59b273 --- /dev/null +++ b/.agents/skills/msw/references/response-custom-headers.md @@ -0,0 +1,125 @@ +--- +title: Set Response Headers Correctly +impact: HIGH +impactDescription: Ensures CORS, caching, and authentication headers work as expected +tags: response, headers, cors, cache-control, authentication +--- + +## Set Response Headers Correctly + +Set appropriate response headers to simulate real API behavior. Headers like `Set-Cookie`, `Cache-Control`, and CORS headers affect how your application handles responses. + +**Incorrect (missing important headers):** + +```typescript +http.post('/api/login', () => { + // Missing Set-Cookie header - authentication won't work + return HttpResponse.json({ user: { id: '1' } }) +}) + +http.get('/api/data', () => { + // Missing caching headers - can't test cache behavior + return HttpResponse.json({ data: 'value' }) +}) +``` + +**Correct (explicit headers):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // Authentication with cookies + http.post('/api/login', () => { + return HttpResponse.json( + { user: { id: '1', name: 'John' } }, + { + headers: { + 'Set-Cookie': 'session=abc123; Path=/; HttpOnly', + }, + } + ) + }), + + // Caching headers + http.get('/api/static-data', () => { + return HttpResponse.json( + { version: '1.0' }, + { + headers: { + 'Cache-Control': 'public, max-age=3600', + 'ETag': '"abc123"', + }, + } + ) + }), + + // No-cache for dynamic data + http.get('/api/user', () => { + return HttpResponse.json( + { name: 'John' }, + { + headers: { + 'Cache-Control': 'no-store', + }, + } + ) + }), + + // Pagination headers + http.get('/api/users', () => { + return HttpResponse.json( + [{ id: '1' }, { id: '2' }], + { + headers: { + 'X-Total-Count': '100', + 'X-Page': '1', + 'X-Per-Page': '10', + 'Link': '; rel="next"', + }, + } + ) + }), + + // Rate limiting headers + http.get('/api/limited', () => { + return HttpResponse.json( + { data: 'value' }, + { + headers: { + 'X-RateLimit-Limit': '100', + 'X-RateLimit-Remaining': '99', + 'X-RateLimit-Reset': String(Date.now() + 3600000), + }, + } + ) + }), +] +``` + +**Testing rate limit handling:** + +```typescript +it('shows rate limit warning when approaching limit', async () => { + server.use( + http.get('/api/data', () => { + return HttpResponse.json( + { data: 'value' }, + { + headers: { + 'X-RateLimit-Remaining': '5', + }, + } + ) + }) + ) + + render() + expect(await screen.findByText('Rate limit warning')).toBeInTheDocument() +}) +``` + +**When NOT to use this pattern:** +- Tests not concerned with header-specific behavior can omit custom headers + +Reference: [MSW HttpResponse Options](https://mswjs.io/docs/api/http-response) diff --git a/.agents/skills/msw/references/response-delay-realistic.md b/.agents/skills/msw/references/response-delay-realistic.md new file mode 100644 index 0000000..df3bb83 --- /dev/null +++ b/.agents/skills/msw/references/response-delay-realistic.md @@ -0,0 +1,92 @@ +--- +title: Add Delays Only for Timing Behavior Under Test +impact: HIGH +impactDescription: exercises loading, timeout, cancellation, and race behavior without slowing every test +tags: response, delay, async, loading, timing +--- + +## Add Delays Only for Timing Behavior Under Test + +Keep baseline handlers deterministic and fast. Add `delay()` in the specific test or development scenario whose contract includes a loading state, timeout, cancellation, race, or hung request. A random global delay makes tests slower and less reproducible. + +**Correct (deterministic baseline handlers):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + http.get('/api/user', () => + HttpResponse.json({ name: 'John' }) + ), +] +``` + +Override timing in the test that needs it: + +```typescript +import { delay, http, HttpResponse } from 'msw' + +it('shows loading while the request is pending', async () => { + server.use( + http.get('/api/user', async () => { + await delay(100) + return HttpResponse.json({ name: 'John' }) + }) + ) + + render() + + expect(screen.getByText('Loading…')).toBeInTheDocument() + expect(await screen.findByText('John')).toBeInTheDocument() +}) +``` + +**Delay modes:** + +```typescript +// Explicit, reproducible delay - use this when a test needs visible pending time +await delay(200) + +// 'real' / bare delay(): randomized 100-400ms in the browser, +// but a fixed 5ms under Node, so it will not make a loading state observable there +await delay('real') + +// Infinite delay - simulates a hung request. Under Node this is setTimeout's +// max int with .unref(), so it will not keep the process alive +await delay('infinite') +``` + +Use `delay('infinite')` only when the test controls cancellation or timeout. + +**Incorrect (a global delay applied to every handler):** + +```typescript +import { http, delay } from 'msw' + +export const handlers = [ + // Slows every test in the suite to buy timing realism no assertion depends on + http.all('*', async () => { + await delay(100) + // No return = continue to the next matching handler + }), + + http.get('/api/user', () => HttpResponse.json({ name: 'John' })), +] +``` + +Do not use arbitrary delay values to wait in the test itself: + +```typescript +render() +await new Promise((resolve) => setTimeout(resolve, 200)) +expect(screen.getByText('John')).toBeInTheDocument() +``` + +Assert observable state with the testing framework's async utilities instead: + +```typescript +render() +expect(await screen.findByText('John')).toBeInTheDocument() +``` + +Reference: [MSW delay API](https://mswjs.io/docs/api/delay) diff --git a/.agents/skills/msw/references/response-error-simulation.md b/.agents/skills/msw/references/response-error-simulation.md new file mode 100644 index 0000000..8d42124 --- /dev/null +++ b/.agents/skills/msw/references/response-error-simulation.md @@ -0,0 +1,110 @@ +--- +title: Simulate Error Responses Correctly +impact: HIGH +impactDescription: Validates error handling; catches missing error states in UI +tags: response, error, status, network-error, HttpResponse +--- + +## Simulate Error Responses Correctly + +Use proper HTTP status codes and `HttpResponse.error()` for network errors. Different error types require different handling in your application, and correct simulation ensures your error handling works. + +**Incorrect (ambiguous error responses):** + +```typescript +// Unclear what type of error this represents +http.get('/api/user', () => { + return HttpResponse.json({ error: 'Something went wrong' }) +}) + +// Missing status code - defaults to 200! +http.get('/api/user', () => { + return new HttpResponse('Error occurred') +}) +``` + +**Correct (explicit error types):** + +```typescript +import { http, HttpResponse } from 'msw' + +// HTTP 4xx - Client errors +http.get('/api/user/:id', () => { + return HttpResponse.json( + { error: 'User not found' }, + { status: 404 } + ) +}) + +http.post('/api/user', () => { + return HttpResponse.json( + { error: 'Validation failed', fields: ['email'] }, + { status: 400 } + ) +}) + +http.get('/api/protected', () => { + return HttpResponse.json( + { error: 'Unauthorized' }, + { status: 401 } + ) +}) + +http.get('/api/admin', () => { + return HttpResponse.json( + { error: 'Forbidden' }, + { status: 403 } + ) +}) + +// HTTP 5xx - Server errors +http.get('/api/user', () => { + return HttpResponse.json( + { error: 'Internal server error' }, + { status: 500 } + ) +}) + +http.get('/api/data', () => { + return new HttpResponse(null, { status: 503 }) // Service unavailable +}) + +// Network error (connection failure, DNS failure, etc.) +http.get('/api/user', () => { + return HttpResponse.error() // Causes fetch to reject +}) +``` + +**Testing error handling:** + +```typescript +it('displays 404 message when user not found', async () => { + server.use( + http.get('/api/user/:id', () => { + return HttpResponse.json( + { error: 'User not found' }, + { status: 404 } + ) + }) + ) + + render() + expect(await screen.findByText('User not found')).toBeInTheDocument() +}) + +it('handles network failure gracefully', async () => { + server.use( + http.get('/api/user', () => { + return HttpResponse.error() + }) + ) + + render() + expect(await screen.findByText('Network error')).toBeInTheDocument() +}) +``` + +**When NOT to use this pattern:** +- Happy path tests should use success responses + +Reference: [MSW HttpResponse API](https://mswjs.io/docs/api/http-response) diff --git a/.agents/skills/msw/references/response-http-response-helpers.md b/.agents/skills/msw/references/response-http-response-helpers.md new file mode 100644 index 0000000..a5a9408 --- /dev/null +++ b/.agents/skills/msw/references/response-http-response-helpers.md @@ -0,0 +1,83 @@ +--- +title: Use HttpResponse Static Methods +impact: HIGH +impactDescription: Automatic Content-Type headers; cleaner syntax; type safety +tags: response, HttpResponse, json, text, xml, helpers +--- + +## Use HttpResponse Static Methods + +Use `HttpResponse.json()`, `HttpResponse.text()`, and other static methods instead of manually constructing responses. These methods automatically set correct Content-Type headers and provide cleaner, more readable code. + +**Incorrect (manual response construction):** + +```typescript +http.get('/api/user', () => { + // Verbose, easy to forget Content-Type header + return new Response( + JSON.stringify({ name: 'John' }), + { + status: 200, + headers: { + 'Content-Type': 'application/json', + }, + } + ) +}) +``` + +**Correct (HttpResponse static methods):** + +```typescript +import { http, HttpResponse } from 'msw' + +export const handlers = [ + // JSON - sets Content-Type: application/json automatically + http.get('/api/user', () => { + return HttpResponse.json({ name: 'John', email: 'john@example.com' }) + }), + + // JSON with status code + http.post('/api/user', () => { + return HttpResponse.json( + { id: '1', message: 'Created' }, + { status: 201 } + ) + }), + + // Text - sets Content-Type: text/plain + http.get('/api/text', () => { + return HttpResponse.text('Hello, World!') + }), + + // XML - sets Content-Type: application/xml + http.get('/api/xml', () => { + return HttpResponse.xml('John') + }), + + // HTML - sets Content-Type: text/html + http.get('/page', () => { + return HttpResponse.html('

Hello

') + }), + + // ArrayBuffer for binary data + http.get('/api/file', () => { + const buffer = new ArrayBuffer(8) + return HttpResponse.arrayBuffer(buffer, { + headers: { 'Content-Type': 'application/octet-stream' }, + }) + }), + + // FormData + http.get('/api/form', () => { + const form = new FormData() + form.append('field', 'value') + return HttpResponse.formData(form) + }), +] +``` + +**When NOT to use this pattern:** +- Custom Content-Types not covered by helpers may need manual `new Response()` + +Reference: [MSW HttpResponse API](https://mswjs.io/docs/api/http-response) diff --git a/.agents/skills/msw/references/response-one-time-handlers.md b/.agents/skills/msw/references/response-one-time-handlers.md new file mode 100644 index 0000000..8d26c55 --- /dev/null +++ b/.agents/skills/msw/references/response-one-time-handlers.md @@ -0,0 +1,103 @@ +--- +title: Use One-Time Handlers for Sequential Scenarios +impact: HIGH +impactDescription: Models realistic multi-step flows; tests retry logic correctly +tags: response, once, one-time, sequential, retry +--- + +## Use One-Time Handlers for Sequential Scenarios + +Use the `{ once: true }` option for handlers that should only respond once, then fall back to the next matching handler. This is essential for testing retry logic, sequential API calls, or state changes between requests. + +**Incorrect (permanent override prevents testing retries):** + +```typescript +it('retries after failure', async () => { + server.use( + http.get('/api/user', () => { + return new HttpResponse(null, { status: 500 }) + }) + ) + + render() + + // Component retries, but always gets 500 - can't test success after retry + await userEvent.click(screen.getByRole('button', { name: 'Retry' })) + // Still failing... +}) +``` + +**Correct (one-time handler for first request):** + +```typescript +import { http, HttpResponse } from 'msw' + +it('retries after failure and succeeds', async () => { + server.use( + http.get( + '/api/user', + () => { + return new HttpResponse(null, { status: 500 }) + }, + { once: true } // Only affects first request + ) + ) + + render() + + // First request fails + expect(await screen.findByText('Error loading user')).toBeInTheDocument() + + // Retry succeeds (uses baseline happy-path handler) + await userEvent.click(screen.getByRole('button', { name: 'Retry' })) + expect(await screen.findByText('John')).toBeInTheDocument() +}) +``` + +**Sequential state changes:** + +```typescript +it('shows optimistic update then server response', async () => { + let callCount = 0 + + server.use( + http.post('/api/like', () => { + callCount++ + if (callCount === 1) { + // First call - slow response simulates network + return HttpResponse.json({ likes: 11 }) + } + // Subsequent calls + return HttpResponse.json({ likes: 12 }) + }) + ) + + // Test optimistic update behavior +}) +``` + +**Multiple sequential states:** + +```typescript +server.use( + // First request: pending + http.get('/api/order/:id', () => { + return HttpResponse.json({ status: 'pending' }) + }, { once: true }), + + // Second request: processing + http.get('/api/order/:id', () => { + return HttpResponse.json({ status: 'processing' }) + }, { once: true }), + + // Third+ requests: completed + http.get('/api/order/:id', () => { + return HttpResponse.json({ status: 'completed' }) + }) +) +``` + +**When NOT to use this pattern:** +- Single-state tests that don't involve retries or polling + +Reference: [Network Behavior Overrides](https://mswjs.io/docs/best-practices/network-behavior-overrides) diff --git a/.agents/skills/msw/references/response-streaming.md b/.agents/skills/msw/references/response-streaming.md new file mode 100644 index 0000000..3d82862 --- /dev/null +++ b/.agents/skills/msw/references/response-streaming.md @@ -0,0 +1,114 @@ +--- +title: Mock Streaming Responses with ReadableStream +impact: HIGH +impactDescription: Tests streaming UIs, chat interfaces, and progressive loading +tags: response, streaming, ReadableStream, sse, progressive +--- + +## Mock Streaming Responses with ReadableStream + +Use `ReadableStream` to mock streaming responses for Server-Sent Events (SSE), chunked transfers, or streaming APIs. This enables testing of real-time features and progressive UI updates. + +**Incorrect (returning complete response immediately):** + +```typescript +// Chat response arrives all at once - doesn't test streaming UI +http.post('/api/chat', () => { + return HttpResponse.json({ + message: 'Here is the complete response all at once', + }) +}) +``` + +**Correct (streaming response):** + +```typescript +import { http, HttpResponse } from 'msw' + +// Text streaming (like AI chat) +http.post('/api/chat', () => { + const encoder = new TextEncoder() + const chunks = ['Hello', ' ', 'world', '!'] + + const stream = new ReadableStream({ + async start(controller) { + for (const chunk of chunks) { + controller.enqueue(encoder.encode(chunk)) + await new Promise((resolve) => setTimeout(resolve, 100)) + } + controller.close() + }, + }) + + return new HttpResponse(stream, { + headers: { + 'Content-Type': 'text/plain', + 'Transfer-Encoding': 'chunked', + }, + }) +}) +``` + +**Server-Sent Events (SSE):** + +```typescript +http.get('/api/events', () => { + const encoder = new TextEncoder() + const events = [ + { id: '1', data: { message: 'First event' } }, + { id: '2', data: { message: 'Second event' } }, + { id: '3', data: { message: 'Third event' } }, + ] + + const stream = new ReadableStream({ + async start(controller) { + for (const event of events) { + const sseMessage = `id: ${event.id}\ndata: ${JSON.stringify(event.data)}\n\n` + controller.enqueue(encoder.encode(sseMessage)) + await new Promise((resolve) => setTimeout(resolve, 200)) + } + controller.close() + }, + }) + + return new HttpResponse(stream, { + headers: { + 'Content-Type': 'text/event-stream', + 'Cache-Control': 'no-cache', + 'Connection': 'keep-alive', + }, + }) +}) +``` + +**JSON streaming (newline-delimited):** + +```typescript +http.get('/api/stream-json', () => { + const encoder = new TextEncoder() + const items = [ + { id: 1, name: 'Item 1' }, + { id: 2, name: 'Item 2' }, + { id: 3, name: 'Item 3' }, + ] + + const stream = new ReadableStream({ + async start(controller) { + for (const item of items) { + controller.enqueue(encoder.encode(JSON.stringify(item) + '\n')) + await new Promise((resolve) => setTimeout(resolve, 100)) + } + controller.close() + }, + }) + + return new HttpResponse(stream, { + headers: { 'Content-Type': 'application/x-ndjson' }, + }) +}) +``` + +**When NOT to use this pattern:** +- APIs that return complete responses don't need streaming mocks + +Reference: [MSW ReadableStream Support](https://mswjs.io/blog/introducing-msw-2.0) diff --git a/.agents/skills/msw/references/setup-lifecycle-hooks.md b/.agents/skills/msw/references/setup-lifecycle-hooks.md new file mode 100644 index 0000000..9c6269d --- /dev/null +++ b/.agents/skills/msw/references/setup-lifecycle-hooks.md @@ -0,0 +1,57 @@ +--- +title: Configure Server Lifecycle in Test Setup +impact: CRITICAL +impactDescription: Prevents handler leakage and ensures test isolation; eliminates flaky tests +tags: setup, lifecycle, vitest, jest, beforeAll, afterEach +--- + +## Configure Server Lifecycle in Test Setup + +Server lifecycle hooks must be configured in test setup files to ensure proper initialization, cleanup between tests, and graceful shutdown. Missing hooks cause handler pollution and unpredictable test behavior. + +**Incorrect (no lifecycle management):** + +```typescript +// handlers.test.ts +import { server } from './mocks/node' + +// Server never started, handlers never reset +// Tests may pass/fail randomly depending on execution order +it('fetches user', async () => { + const response = await fetch('/user') + // This fails silently - no mocking active +}) +``` + +**Correct (proper lifecycle hooks):** + +```typescript +// vitest.setup.ts or setupTests.ts +import { beforeAll, afterEach, afterAll } from 'vitest' +import { server } from './mocks/node' + +// Start server before all tests +beforeAll(() => server.listen()) + +// Reset handlers after each test to ensure isolation +afterEach(() => server.resetHandlers()) + +// Clean shutdown after all tests complete +afterAll(() => server.close()) +``` + +**Jest equivalent:** + +```typescript +// setupTests.ts +import { server } from './mocks/node' + +beforeAll(() => server.listen()) +afterEach(() => server.resetHandlers()) +afterAll(() => server.close()) +``` + +**When NOT to use this pattern:** +- Browser-based tests use `worker.start()` and `worker.stop()` instead + +Reference: [MSW Quick Start - Test Setup](https://mswjs.io/docs/quick-start) diff --git a/.agents/skills/msw/references/setup-node-version.md b/.agents/skills/msw/references/setup-node-version.md new file mode 100644 index 0000000..ffec58c --- /dev/null +++ b/.agents/skills/msw/references/setup-node-version.md @@ -0,0 +1,72 @@ +--- +title: Require Node.js 18+ for MSW v2 +impact: CRITICAL +impactDescription: MSW v2 requires Node 18+; older versions cause complete failure +tags: setup, node, version, requirements, compatibility +--- + +## Require Node.js 18+ for MSW v2 + +MSW v2 sets Node.js 18.0.0 as the minimum supported version. Older versions lack native `fetch` and other required APIs, causing complete mocking failure. + +**Incorrect (using unsupported Node version):** + +```json +// package.json +{ + "engines": { + "node": ">=14.0.0" + } +} +``` + +```bash +# Node 16 - MSW v2 fails silently or throws cryptic errors +$ node -v +v16.20.0 + +$ npm test +# ReferenceError: fetch is not defined +# or: Cannot read properties of undefined +``` + +**Correct (enforce Node 18+ requirement):** + +```json +// package.json +{ + "engines": { + "node": ">=18.0.0" + } +} +``` + +```yaml +# .nvmrc +18 +``` + +```yaml +# CI configuration (GitHub Actions) +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + node-version: [18, 20, 22] +``` + +**Verify installation:** + +```bash +# Check Node version +node -v # Should be v18.x.x or higher + +# Check MSW version +npm ls msw # Should be v2.x.x +``` + +**When NOT to use this pattern:** +- If stuck on Node 16, use MSW v1.x instead (with different API patterns) + +Reference: [MSW v2 Migration - Requirements](https://mswjs.io/docs/migrations/1.x-to-2.x/) diff --git a/.agents/skills/msw/references/setup-server-node-entrypoint.md b/.agents/skills/msw/references/setup-server-node-entrypoint.md new file mode 100644 index 0000000..36abfbe --- /dev/null +++ b/.agents/skills/msw/references/setup-server-node-entrypoint.md @@ -0,0 +1,45 @@ +--- +title: Use Correct Entrypoint for Node.js +impact: CRITICAL +impactDescription: Zero mocking if wrong entrypoint; 100% test failures +tags: setup, entrypoint, node, server, msw-node +--- + +## Use Correct Entrypoint for Node.js + +MSW v2 separates browser and Node.js entrypoints. Using the wrong import causes complete mocking failure with no interception occurring. + +**Incorrect (importing from wrong path):** + +```typescript +// This imports browser code into Node.js - mocking silently fails +import { setupServer } from 'msw' +import { setupWorker } from 'msw' + +const server = setupServer(...handlers) +``` + +**Correct (using msw/node entrypoint):** + +```typescript +// Node.js environments (tests, SSR) use msw/node +import { setupServer } from 'msw/node' +import { handlers } from './handlers' + +export const server = setupServer(...handlers) +``` + +**Browser environments use msw/browser:** + +```typescript +// Browser environments use msw/browser +import { setupWorker } from 'msw/browser' +import { handlers } from './handlers' + +export const worker = setupWorker(...handlers) +``` + +**When NOT to use this pattern:** +- Never deviate from this pattern; entrypoint selection is binary based on environment + +Reference: [MSW Node.js Integration](https://mswjs.io/docs/integrations/node) diff --git a/.agents/skills/msw/references/setup-typescript-config.md b/.agents/skills/msw/references/setup-typescript-config.md new file mode 100644 index 0000000..b609e97 --- /dev/null +++ b/.agents/skills/msw/references/setup-typescript-config.md @@ -0,0 +1,74 @@ +--- +title: Configure TypeScript for MSW v2 +impact: CRITICAL +impactDescription: TypeScript 4.8+ required; incorrect config causes type errors +tags: setup, typescript, configuration, types, compiler +--- + +## Configure TypeScript for MSW v2 + +MSW v2 requires TypeScript 4.8+ for proper type inference. Incorrect TypeScript configuration causes confusing type errors and prevents proper handler typing. + +**Incorrect (outdated TypeScript or missing config):** + +```json +// tsconfig.json - missing moduleResolution +{ + "compilerOptions": { + "target": "ES2020", + "module": "ESNext" + // No moduleResolution - imports fail to resolve + } +} +``` + +```typescript +// Type errors due to incorrect resolution +import { http, HttpResponse } from 'msw' +// Error: Cannot find module 'msw' or its corresponding type declarations +``` + +**Correct (proper TypeScript configuration):** + +```json +// tsconfig.json +{ + "compilerOptions": { + "target": "ES2020", + "module": "ESNext", + "moduleResolution": "bundler", // or "node16" / "nodenext" + "esModuleInterop": true, + "strict": true, + "skipLibCheck": true + } +} +``` + +**Typed handlers with proper inference:** + +```typescript +import { http, HttpResponse } from 'msw' + +interface User { + id: string + name: string + email: string +} + +export const handlers = [ + http.get('/api/user/:id', ({ params }) => { + // params.id is typed as string + return HttpResponse.json({ + id: params.id, + name: 'John Doe', + email: 'john@example.com', + }) + }), +] +``` + +**When NOT to use this pattern:** +- JavaScript-only projects don't need TypeScript configuration +- Projects using older bundlers may need `moduleResolution: "node"` + +Reference: [MSW v2 Migration - TypeScript](https://mswjs.io/docs/migrations/1.x-to-2.x/) diff --git a/.agents/skills/msw/references/setup-unhandled-requests.md b/.agents/skills/msw/references/setup-unhandled-requests.md new file mode 100644 index 0000000..69f3bf8 --- /dev/null +++ b/.agents/skills/msw/references/setup-unhandled-requests.md @@ -0,0 +1,70 @@ +--- +title: Configure Unhandled Request Behavior +impact: CRITICAL +impactDescription: Catches missing handlers immediately; prevents silent test failures +tags: setup, unhandled, error, configuration, onUnhandledRequest +--- + +## Configure Unhandled Request Behavior + +Configure `onUnhandledRequest: 'error'` to fail tests when requests lack handlers. This catches missing mocks immediately instead of allowing silent network calls or undefined behavior. + +**Incorrect (default silent behavior):** + +```typescript +// mocks/node.ts +import { setupServer } from 'msw/node' +import { handlers } from './handlers' + +// Default behavior: warns but doesn't fail +// Unhandled requests may hit real APIs or return undefined +export const server = setupServer(...handlers) +``` + +```typescript +// Test passes despite missing handler - false positive! +it('submits form', async () => { + await submitForm({ email: 'test@example.com' }) + // POST /submit has no handler but test doesn't fail + expect(screen.getByText('Success')).toBeInTheDocument() +}) +``` + +**Correct (strict unhandled request handling):** + +```typescript +// vitest.setup.ts +import { server } from './mocks/node' + +beforeAll(() => { + server.listen({ + onUnhandledRequest: 'error', // Fail on any unhandled request + }) +}) + +afterEach(() => server.resetHandlers()) +afterAll(() => server.close()) +``` + +**Custom handling for specific URLs:** + +```typescript +beforeAll(() => { + server.listen({ + onUnhandledRequest(request, print) { + // Allow certain requests through (e.g., static assets) + if (request.url.includes('/static/')) { + return + } + // Error on all other unhandled requests + print.error() + }, + }) +}) +``` + +**When NOT to use this pattern:** +- Development environments may prefer `'warn'` for less disruptive feedback +- Integration tests that intentionally hit real endpoints + +Reference: [MSW Best Practices - Avoid Request Assertions](https://mswjs.io/docs/best-practices/avoid-request-assertions/) diff --git a/.agents/skills/msw/references/setup-worker-script-commit.md b/.agents/skills/msw/references/setup-worker-script-commit.md new file mode 100644 index 0000000..ad9a013 --- /dev/null +++ b/.agents/skills/msw/references/setup-worker-script-commit.md @@ -0,0 +1,65 @@ +--- +title: Commit Worker Script to Version Control +impact: CRITICAL +impactDescription: Eliminates setup friction for team members; prevents CI failures +tags: setup, worker, git, mockServiceWorker, browser +--- + +## Commit Worker Script to Version Control + +The `mockServiceWorker.js` file generated by `msw init` should be committed to Git. This ensures team members and CI environments can run browser tests without additional setup commands. + +**Incorrect (gitignoring worker script):** + +```gitignore +# .gitignore +# This forces every developer to run msw init manually +public/mockServiceWorker.js +``` + +```bash +# New team member clones repo, runs tests, gets cryptic errors +# because worker script doesn't exist +npm test +# Error: Cannot find mockServiceWorker.js +``` + +**Correct (commit and auto-update worker script):** + +```bash +# Generate worker script with --save flag +npx msw init public/ --save +``` + +```json +// package.json - auto-updates worker on msw version changes +{ + "msw": { + "workerDirectory": ["public"] + } +} +``` + +```gitignore +# .gitignore - do NOT ignore the worker script +# public/mockServiceWorker.js <- remove this line +``` + +**Monorepo configuration:** + +```json +// Root package.json for monorepos +{ + "msw": { + "workerDirectory": [ + "apps/web/public", + "apps/admin/public" + ] + } +} +``` + +**When NOT to use this pattern:** +- If treating as generated artifact, ensure CI runs `msw init` before tests + +Reference: [Managing the Worker](https://mswjs.io/docs/best-practices/managing-the-worker/) diff --git a/.agents/skills/msw/references/test-async-utilities.md b/.agents/skills/msw/references/test-async-utilities.md new file mode 100644 index 0000000..d228a71 --- /dev/null +++ b/.agents/skills/msw/references/test-async-utilities.md @@ -0,0 +1,81 @@ +--- +title: Use Async Testing Utilities for Mock Responses +impact: HIGH +impactDescription: Prevents race conditions; ensures responses arrive before assertions +tags: test, async, waitFor, findBy, testing-library, race-condition +--- + +## Use Async Testing Utilities for Mock Responses + +Use async testing utilities (`findBy`, `waitFor`) instead of `getBy` or manual `setTimeout` when testing components that make API calls. Mock responses are asynchronous, and synchronous assertions will fail before data arrives. + +**Incorrect (synchronous assertions):** + +```typescript +it('displays user name', () => { + render() + + // Fails! Response hasn't arrived yet + expect(screen.getByText('John')).toBeInTheDocument() +}) + +// Also incorrect - arbitrary timeout +it('displays user name', async () => { + render() + + await new Promise((resolve) => setTimeout(resolve, 100)) + + // Flaky - 100ms might not be enough, or wastes time if faster + expect(screen.getByText('John')).toBeInTheDocument() +}) +``` + +**Correct (async testing utilities):** + +```typescript +import { render, screen, waitFor } from '@testing-library/react' + +it('displays user name', async () => { + render() + + // findBy* returns a promise that resolves when element appears + expect(await screen.findByText('John')).toBeInTheDocument() +}) + +// For non-element assertions, use waitFor +it('updates document title', async () => { + render() + + await waitFor(() => { + expect(document.title).toBe('John - Profile') + }) +}) + +// For multiple elements +it('displays user list', async () => { + render() + + const users = await screen.findAllByRole('listitem') + expect(users).toHaveLength(3) +}) +``` + +**With loading states:** + +```typescript +it('shows loading then content', async () => { + render() + + // Loading state appears immediately + expect(screen.getByText('Loading...')).toBeInTheDocument() + + // Content replaces loading after response + expect(await screen.findByText('John')).toBeInTheDocument() + expect(screen.queryByText('Loading...')).not.toBeInTheDocument() +}) +``` + +**When NOT to use this pattern:** +- Synchronous operations that don't involve API calls can use `getBy` + +Reference: [Testing Library Async Methods](https://testing-library.com/docs/dom-testing-library/api-async/) diff --git a/.agents/skills/msw/references/test-avoid-request-assertions.md b/.agents/skills/msw/references/test-avoid-request-assertions.md new file mode 100644 index 0000000..159a84c --- /dev/null +++ b/.agents/skills/msw/references/test-avoid-request-assertions.md @@ -0,0 +1,87 @@ +--- +title: Avoid Direct Request Assertions +impact: HIGH +impactDescription: Tests implementation details; breaks on refactors that preserve behavior +tags: test, assertions, anti-pattern, implementation-details, behavior +--- + +## Avoid Direct Request Assertions + +Do not assert that specific requests were made with specific parameters. This tests implementation details rather than behavior. Instead, assert on your application's reaction to responses. + +**Incorrect (asserting request details):** + +```typescript +it('sends correct data when creating user', async () => { + const requestSpy = vi.fn() + + server.use( + http.post('/api/user', async ({ request }) => { + requestSpy(await request.json()) + return HttpResponse.json({ id: '1' }) + }) + ) + + await createUser({ name: 'John', email: 'john@example.com' }) + + // Testing implementation details - what if we add a field? + expect(requestSpy).toHaveBeenCalledWith({ + name: 'John', + email: 'john@example.com', + }) +}) +``` + +**Correct (assert behavior through responses):** + +```typescript +it('creates user and shows success message', async () => { + server.use( + http.post('/api/user', async ({ request }) => { + const body = await request.json() + // Validate in handler - returns error if invalid + if (!body.email) { + return HttpResponse.json( + { error: 'Email required' }, + { status: 400 } + ) + } + return HttpResponse.json({ id: '1', ...body }, { status: 201 }) + }) + ) + + render() + await userEvent.type(screen.getByLabelText('Name'), 'John') + await userEvent.type(screen.getByLabelText('Email'), 'john@example.com') + await userEvent.click(screen.getByRole('button', { name: 'Create' })) + + // Assert application behavior, not request details + expect(await screen.findByText('User created!')).toBeInTheDocument() +}) +``` + +**For one-way requests (analytics, logging):** + +```typescript +import { server } from './mocks/node' + +it('tracks page view', async () => { + const trackingPromise = new Promise((resolve) => { + server.events.on('request:end', ({ request }) => { + if (request.url.includes('/analytics')) { + resolve() + } + }) + }) + + render() + + // Verify the request was made without asserting payload + await expect(trackingPromise).resolves.toBeUndefined() +}) +``` + +**When NOT to use this pattern:** +- Analytics/telemetry testing may require request payload verification via lifecycle events + +Reference: [Avoid Request Assertions](https://mswjs.io/docs/best-practices/avoid-request-assertions/) diff --git a/.agents/skills/msw/references/test-clear-request-cache.md b/.agents/skills/msw/references/test-clear-request-cache.md new file mode 100644 index 0000000..8f62502 --- /dev/null +++ b/.agents/skills/msw/references/test-clear-request-cache.md @@ -0,0 +1,85 @@ +--- +title: Clear Request Library Caches Between Tests +impact: HIGH +impactDescription: Prevents stale cached responses; ensures fresh mock data per test +tags: test, cache, swr, react-query, tanstack-query, isolation +--- + +## Clear Request Library Caches Between Tests + +Clear data fetching library caches between tests. Libraries like SWR, TanStack Query, and Apollo cache responses, causing tests to receive stale data from previous tests instead of fresh mocked responses. + +**Incorrect (cached data leaks between tests):** + +```typescript +// test-a.spec.ts +it('displays original user', async () => { + // Response cached by SWR/React Query + render() + expect(await screen.findByText('John')).toBeInTheDocument() +}) + +// test-b.spec.ts +it('displays updated user', async () => { + server.use( + http.get('/api/user', () => { + return HttpResponse.json({ name: 'Jane' }) // Different user + }) + ) + render() + // FAILS! Cache returns 'John' from previous test + expect(await screen.findByText('Jane')).toBeInTheDocument() +}) +``` + +**Correct (clear caches in test setup):** + +```typescript +// SWR cache clearing +import { cache } from 'swr' + +afterEach(() => { + // Clear SWR cache + cache.clear() +}) +``` + +```typescript +// TanStack Query cache clearing +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' + +const createTestQueryClient = () => + new QueryClient({ + defaultOptions: { + queries: { retry: false, gcTime: 0 }, + }, + }) + +const renderWithClient = (ui: React.ReactElement) => { + const testQueryClient = createTestQueryClient() + return render( + {ui} + ) +} + +// Each test gets fresh QueryClient with no cached data +it('displays user', async () => { + renderWithClient() + expect(await screen.findByText('John')).toBeInTheDocument() +}) +``` + +```typescript +// Apollo Client cache clearing +import { ApolloClient, InMemoryCache } from '@apollo/client' + +afterEach(async () => { + await client.clearStore() + // or client.resetStore() to refetch active queries +}) +``` + +**When NOT to use this pattern:** +- Tests intentionally verifying cache behavior should not clear caches + +Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/) diff --git a/.agents/skills/msw/references/test-concurrent-boundary.md b/.agents/skills/msw/references/test-concurrent-boundary.md new file mode 100644 index 0000000..6735330 --- /dev/null +++ b/.agents/skills/msw/references/test-concurrent-boundary.md @@ -0,0 +1,88 @@ +--- +title: Use server.boundary() for Concurrent Tests +impact: HIGH +impactDescription: Enables parallel test execution; prevents cross-test handler pollution +tags: test, concurrent, boundary, isolation, parallel +--- + +## Use server.boundary() for Concurrent Tests + +Wrap concurrent tests in `server.boundary()` to isolate handler overrides. Without boundaries, concurrent tests share handlers, causing race conditions and unpredictable failures. + +**Incorrect (concurrent tests without boundaries):** + +```typescript +// Tests run in parallel - handlers leak between them +it.concurrent('fetches user', async () => { + // Uses initial handlers + const response = await fetch('https://api.example.com/user') + expect(response.ok).toBe(true) +}) + +it.concurrent('handles error', async () => { + server.use( + http.get('https://api.example.com/user', () => { + return new HttpResponse(null, { status: 500 }) + }) + ) + // This override might affect the other concurrent test! + const response = await fetch('https://api.example.com/user') + expect(response.status).toBe(500) +}) +``` + +**Correct (boundary-isolated concurrent tests):** + +```typescript +import { http, HttpResponse } from 'msw' +import { setupServer } from 'msw/node' + +const server = setupServer( + http.get('https://api.example.com/user', () => { + return HttpResponse.json({ name: 'John' }) + }) +) + +beforeAll(() => server.listen()) +afterAll(() => server.close()) + +it.concurrent( + 'fetches user', + server.boundary(async () => { + const response = await fetch('https://api.example.com/user') + const user = await response.json() + expect(user).toEqual({ name: 'John' }) + }) +) + +it.concurrent( + 'handles server error', + server.boundary(async () => { + // Override is scoped to this boundary only + server.use( + http.get('https://api.example.com/user', () => { + return new HttpResponse(null, { status: 500 }) + }) + ) + const response = await fetch('https://api.example.com/user') + expect(response.status).toBe(500) + }) +) + +it.concurrent( + 'handles network error', + server.boundary(async () => { + server.use( + http.get('https://api.example.com/user', () => { + return HttpResponse.error() + }) + ) + await expect(fetch('https://api.example.com/user')).rejects.toThrow() + }) +) +``` + +**When NOT to use this pattern:** +- Sequential tests (non-concurrent) can use standard `afterEach` reset pattern + +Reference: [server.boundary() API](https://mswjs.io/docs/api/setup-server/boundary) diff --git a/.agents/skills/msw/references/test-fake-timers-config.md b/.agents/skills/msw/references/test-fake-timers-config.md new file mode 100644 index 0000000..1dbca38 --- /dev/null +++ b/.agents/skills/msw/references/test-fake-timers-config.md @@ -0,0 +1,91 @@ +--- +title: Configure Fake Timers to Preserve queueMicrotask +impact: HIGH +impactDescription: Prevents request body parsing from hanging indefinitely +tags: test, timers, jest, vitest, queueMicrotask, fake-timers +--- + +## Configure Fake Timers to Preserve queueMicrotask + +When using fake timers, configure them to not mock `queueMicrotask`. The global `fetch` uses `queueMicrotask` internally for body parsing, and mocking it causes `request.json()` and similar methods to hang forever. + +**Incorrect (default fake timers):** + +```typescript +// vitest.config.ts or jest.config.js +beforeEach(() => { + vi.useFakeTimers() // Mocks ALL timer functions including queueMicrotask +}) + +// Test hangs indefinitely +it('parses request body', async () => { + server.use( + http.post('/api/user', async ({ request }) => { + const body = await request.json() // Never resolves! + return HttpResponse.json(body) + }) + ) + + await fetch('/api/user', { + method: 'POST', + body: JSON.stringify({ name: 'John' }), + }) +}) +``` + +**Correct (exclude queueMicrotask from fake timers):** + +```typescript +// Vitest +beforeEach(() => { + vi.useFakeTimers({ + toFake: [ + 'setTimeout', + 'setInterval', + 'clearTimeout', + 'clearInterval', + 'setImmediate', + 'clearImmediate', + 'Date', + ], + // queueMicrotask is NOT in the list - remains real + }) +}) + +// Or more explicitly with shouldAdvanceTime +beforeEach(() => { + vi.useFakeTimers({ shouldAdvanceTime: true }) +}) +``` + +```typescript +// Jest +beforeEach(() => { + jest.useFakeTimers({ + doNotFake: ['queueMicrotask'], // Explicitly preserve queueMicrotask + }) +}) +``` + +**Alternative - advance timers after async operations:** + +```typescript +it('handles delayed response', async () => { + vi.useFakeTimers() + + const fetchPromise = fetch('/api/user') + + // Advance timers to allow microtasks to process + await vi.runAllTimersAsync() + + const response = await fetchPromise + expect(response.ok).toBe(true) + + vi.useRealTimers() +}) +``` + +**When NOT to use this pattern:** +- If not using fake timers, this configuration is unnecessary + +Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/) diff --git a/.agents/skills/msw/references/test-jsdom-environment.md b/.agents/skills/msw/references/test-jsdom-environment.md new file mode 100644 index 0000000..de100b0 --- /dev/null +++ b/.agents/skills/msw/references/test-jsdom-environment.md @@ -0,0 +1,67 @@ +--- +title: Use Correct JSDOM Environment for Jest +impact: HIGH +impactDescription: Prevents Node.js global conflicts; ensures proper fetch availability +tags: test, jest, jsdom, environment, configuration +--- + +## Use Correct JSDOM Environment for Jest + +Use `jest-fixed-jsdom` instead of `jest-environment-jsdom` when testing with MSW in Jest. Standard JSDOM uses browser export conditions but runs in Node.js, causing conflicts with MSW's entrypoints. + +**Incorrect (standard jsdom environment):** + +```javascript +// jest.config.js +module.exports = { + testEnvironment: 'jsdom', // Uses browser exports incorrectly +} +``` + +```typescript +// Tests fail with cryptic errors +// TypeError: Cannot read properties of undefined +// or: fetch is not defined +``` + +**Correct (use jest-fixed-jsdom):** + +```bash +npm install -D jest-fixed-jsdom +``` + +```javascript +// jest.config.js +module.exports = { + testEnvironment: 'jest-fixed-jsdom', +} +``` + +**Alternative - migrate to Vitest:** + +```typescript +// vitest.config.ts +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + test: { + environment: 'jsdom', // Vitest handles this correctly + setupFiles: ['./vitest.setup.ts'], + }, +}) +``` + +**Why this matters:** + +JSDOM uses browser export conditions by default, causing packages like MSW to use browser-specific code in a Node.js context. This leads to: +- Missing Node.js globals +- Incorrect module resolution +- Silent failures or cryptic errors + +`jest-fixed-jsdom` and Vitest correctly handle the Node.js/browser boundary. + +**When NOT to use this pattern:** +- Vitest users don't need this; Vitest handles environments correctly +- Node-only tests (no DOM) should use `testEnvironment: 'node'` + +Reference: [MSW v2 Migration - Jest/JSDOM](https://mswjs.io/docs/migrations/1.x-to-2.x/) diff --git a/.agents/skills/msw/references/test-reset-handlers.md b/.agents/skills/msw/references/test-reset-handlers.md new file mode 100644 index 0000000..3831bce --- /dev/null +++ b/.agents/skills/msw/references/test-reset-handlers.md @@ -0,0 +1,63 @@ +--- +title: Reset Handlers After Each Test +impact: HIGH +impactDescription: Prevents handler pollution; eliminates test order dependencies +tags: test, reset, isolation, afterEach, resetHandlers +--- + +## Reset Handlers After Each Test + +Call `server.resetHandlers()` in `afterEach` to remove runtime handlers added during tests. Without reset, handlers from one test can affect subsequent tests, causing mysterious failures that depend on test execution order. + +**Incorrect (no handler reset):** + +```typescript +// test-a.spec.ts +it('handles server error', () => { + server.use( + http.get('/api/user', () => new HttpResponse(null, { status: 500 })) + ) + // Test passes... +}) + +// test-b.spec.ts - runs after test-a +it('displays user name', () => { + // FAILS! Still receiving 500 error from test-a's handler + render() + expect(screen.getByText('John')).toBeInTheDocument() +}) +``` + +**Correct (reset in afterEach):** + +```typescript +// vitest.setup.ts +import { server } from './mocks/node' + +beforeAll(() => server.listen()) +afterEach(() => server.resetHandlers()) // Clean slate for each test +afterAll(() => server.close()) +``` + +```typescript +// user.test.ts +it('handles server error', () => { + server.use( + http.get('/api/user', () => new HttpResponse(null, { status: 500 })) + ) + render() + expect(screen.getByRole('alert')).toHaveTextContent('Error') +}) +// Handler is removed after this test completes + +it('displays user name', () => { + // Uses baseline happy-path handler + render() + expect(screen.getByText('John')).toBeInTheDocument() +}) +``` + +**When NOT to use this pattern:** +- `server.boundary()` provides automatic isolation for concurrent tests + +Reference: [Network Behavior Overrides](https://mswjs.io/docs/best-practices/network-behavior-overrides) diff --git a/.agents/skills/nextjs/SKILL.md b/.agents/skills/nextjs/SKILL.md new file mode 100644 index 0000000..40ddc37 --- /dev/null +++ b/.agents/skills/nextjs/SKILL.md @@ -0,0 +1,115 @@ +--- +name: nextjs +description: Next.js 16 App Router caching and routing. +--- + +# Next.js Community Next.js 16 App Router Best Practices + +Comprehensive performance optimization guide for Next.js 16 App Router applications, maintained by the Next.js Community. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation. Two rules cover Next.js 16.3 preview features (Instant Navigations, Partial Prefetching), gated behind `cacheComponents` and `partialPrefetching`. + +## When to Apply + +Reference these guidelines when: +- Writing new Next.js 16 App Router code +- Configuring caching strategies with 'use cache' directive +- Implementing server components and data fetching +- Setting up routing with parallel and intercepting routes +- Creating server actions for form handling and mutations + +## Rule Categories by Priority + +| Priority | Category | Impact | Prefix | +|----------|----------|--------|--------| +| 1 | Build & Bundle Optimization | CRITICAL | `build-` | +| 2 | Caching Strategy | CRITICAL | `cache-` | +| 3 | Server Components & Data Fetching | HIGH | `server-` | +| 4 | Routing & Navigation | HIGH | `route-` | +| 5 | Server Actions & Mutations | MEDIUM-HIGH | `action-` | +| 6 | Streaming & Loading States | MEDIUM | `stream-` | +| 7 | Metadata & SEO | MEDIUM | `meta-` | +| 8 | Client Components | LOW-MEDIUM | `client-` | + +## Quick Reference + +### 1. Build & Bundle Optimization (CRITICAL) + +- `build-optimize-package-imports` - Configure optimizePackageImports for Icon Libraries +- `build-dynamic-imports` - Use Dynamic Imports for Heavy Components +- `build-barrel-files` - Avoid Barrel File Imports in App Router +- `build-turbopack-config` - Configure Turbopack at the top level +- `build-external-packages` - Configure Server External Packages for Node Dependencies + +### 2. Caching Strategy (CRITICAL) + +- `cache-use-cache-directive` - Use 'use cache' with Cache Components +- `cache-revalidate-tag` - Use revalidateTag with cacheLife Profiles +- `cache-fetch-options` - Configure Fetch Cache Options Explicitly +- `cache-revalidate-path` - Use revalidatePath for Route-Level Cache Invalidation +- `cache-react-cache` - Use React cache() for Request Deduplication +- `cache-segment-config` - Match route configuration to the active cache model + +### 3. Server Components & Data Fetching (HIGH) + +- `server-parallel-fetching` - Fetch Data in Parallel in Server Components +- `server-component-streaming` - Stream Server Components for Progressive Loading +- `server-data-colocation` - Colocate Data Fetching with Components +- `server-preload-pattern` - Use Preload Pattern for Critical Data +- `server-avoid-client-fetching` - Avoid Client-Side Data Fetching for Initial Data +- `server-error-handling` - Handle Server Component Errors Gracefully + +### 4. Routing & Navigation (HIGH) + +- `route-parallel-routes` - Use Parallel Routes for Independent Content +- `route-intercepting-routes` - Use Intercepting Routes for Modal Patterns +- `route-prefetching` - Configure Link Prefetching Appropriately +- `route-instant-navigations` - Make Navigations Instant with Stream, Cache, or Block (16.3 preview) +- `route-partial-prefetching` - Use Partial Prefetching for Reusable Route Shells (16.3 preview) +- `route-proxy-ts` - Use proxy.ts for Network Boundary Logic +- `route-not-found` - Use notFound() for Missing Resources + +### 5. Server Actions & Mutations (MEDIUM-HIGH) + +- `action-server-action-forms` - Use Server Actions for Form Submissions +- `action-pending-states` - Show Pending States with useFormStatus +- `action-error-handling` - Handle Server Action Errors Gracefully +- `action-optimistic-updates` - Use Optimistic Updates for Instant Feedback +- `action-revalidation` - Revalidate Cache After Mutations + +### 6. Streaming & Loading States (MEDIUM) + +- `stream-suspense-boundaries` - Place Suspense Boundaries Strategically +- `stream-loading-tsx` - Use loading.tsx for Route-Level Loading States +- `stream-error-tsx` - Use error.tsx for Route-Level Error Boundaries +- `stream-skeleton-matching` - Match Skeleton Dimensions to Actual Content +- `stream-nested-suspense` - Nest Suspense for Progressive Disclosure + +### 7. Metadata & SEO (MEDIUM) + +- `meta-generate-metadata` - Use generateMetadata for Dynamic Metadata +- `meta-sitemap` - Generate Sitemaps Dynamically +- `meta-robots` - Configure Robots for Crawl Control +- `meta-opengraph-images` - Generate Dynamic OpenGraph Images + +### 8. Client Components (LOW-MEDIUM) + +- `client-use-client-boundary` - Minimize 'use client' Boundary Scope +- `client-children-pattern` - Pass Server Components as Children to Client Components +- `client-hydration-mismatch` - Avoid Hydration Mismatches +- `client-third-party-scripts` - Load Third-Party Scripts Efficiently + +## How to Use + +Run in the project root first: + +```bash +npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions +npx -y @pymodel/react-frontend-skills scan --skill nextjs # deprecated APIs → rule IDs +``` + +Read `references/.md` for each rule above that matches the task and for each `scan` hit: why it matters, then incorrect vs. correct code. + +## Related Skills + +- For React 19 fundamentals, see `react` skill +- For data fetching patterns, see `tanstack-query` skill +- For client-side forms, see `react-hook-form` skill diff --git a/.agents/skills/nextjs/references/action-error-handling.md b/.agents/skills/nextjs/references/action-error-handling.md new file mode 100644 index 0000000..98eba94 --- /dev/null +++ b/.agents/skills/nextjs/references/action-error-handling.md @@ -0,0 +1,75 @@ +--- +title: Handle Server Action Errors Gracefully +impact: MEDIUM-HIGH +impactDescription: prevents silent failures, better error UX +tags: action, error-handling, validation, useActionState +--- + +## Handle Server Action Errors Gracefully + +Return error states from Server Actions instead of throwing. Use `useActionState` to manage form state and display errors. + +**Incorrect (unhandled errors):** + +```typescript +async function createPost(formData: FormData) { + 'use server' + + const title = formData.get('title') as string + await db.posts.create({ data: { title } }) + // If validation fails or DB errors, user sees nothing +} +``` + +**Correct (returning error state):** + +```typescript +// actions.ts +'use server' + +type ActionState = { + error?: string + success?: boolean +} + +export async function createPost( + prevState: ActionState, + formData: FormData +): Promise { + const title = formData.get('title') as string + + if (!title || title.length < 3) { + return { error: 'Title must be at least 3 characters' } + } + + try { + await db.posts.create({ data: { title } }) + revalidatePath('/posts') + return { success: true } + } catch (e) { + return { error: 'Failed to create post. Please try again.' } + } +} + +// page.tsx +'use client' + +import { useActionState } from 'react' +import { createPost } from './actions' + +export default function NewPostForm() { + const [state, formAction, isPending] = useActionState(createPost, {}) + + return ( +
+ + {state.error &&

{state.error}

} + +
+ ) +} +``` + +Reference: [useActionState](https://react.dev/reference/react/useActionState) diff --git a/.agents/skills/nextjs/references/action-optimistic-updates.md b/.agents/skills/nextjs/references/action-optimistic-updates.md new file mode 100644 index 0000000..31b1afe --- /dev/null +++ b/.agents/skills/nextjs/references/action-optimistic-updates.md @@ -0,0 +1,74 @@ +--- +title: Use Optimistic Updates for Instant Feedback +impact: MEDIUM +impactDescription: instant UI response, better perceived performance +tags: action, optimistic, useOptimistic, mutation +--- + +## Use Optimistic Updates for Instant Feedback + +Use `useOptimistic` to update UI immediately before the server confirms. If the action fails, React reverts to the previous state. + +**Incorrect (waiting for server response):** + +```typescript +'use client' + +import { useState } from 'react' + +export function LikeButton({ postId, initialLikes }: { postId: string; initialLikes: number }) { + const [likes, setLikes] = useState(initialLikes) + const [isLiking, setIsLiking] = useState(false) + + async function handleLike() { + setIsLiking(true) + const newLikes = await likePost(postId) // Wait for server + setLikes(newLikes) + setIsLiking(false) + } + + return ( + + ) +} +// UI updates only after the server round trip. +``` + +**Correct (optimistic update):** + +```typescript +'use client' + +import { useOptimistic } from 'react' +import { likePost } from './actions' + +export function LikeButton({ postId, initialLikes }: { postId: string; initialLikes: number }) { + const [optimisticLikes, addOptimisticLike] = useOptimistic( + initialLikes, + (state, _) => state + 1 + ) + + async function handleLike() { + addOptimisticLike(null) // Instant UI update + await likePost(postId) // Server update in background + // If fails, React reverts automatically + } + + return ( +
+ +
+ ) +} +// Instant feedback, reverts on failure +``` + +**When to use:** +- Like/vote buttons +- Adding items to cart +- Toggling favorites +- Any action where instant feedback improves UX diff --git a/.agents/skills/nextjs/references/action-pending-states.md b/.agents/skills/nextjs/references/action-pending-states.md new file mode 100644 index 0000000..9cea961 --- /dev/null +++ b/.agents/skills/nextjs/references/action-pending-states.md @@ -0,0 +1,68 @@ +--- +title: Show Pending States with useFormStatus +impact: MEDIUM-HIGH +impactDescription: better UX during form submission +tags: action, useFormStatus, pending, loading +--- + +## Show Pending States with useFormStatus + +Use `useFormStatus` to show loading indicators and disable buttons during form submission. This provides immediate feedback to users. + +**Incorrect (no feedback during submission):** + +```typescript +// app/posts/new/page.tsx +export default function NewPostPage() { + async function createPost(formData: FormData) { + 'use server' + await db.posts.create({ data: { title: formData.get('title') } }) + } + + return ( +
+ + + {/* User clicks multiple times, no feedback */} +
+ ) +} +``` + +**Correct (pending state with useFormStatus):** + +```typescript +// app/posts/new/page.tsx +import { SubmitButton } from './submit-button' + +export default function NewPostPage() { + async function createPost(formData: FormData) { + 'use server' + await db.posts.create({ data: { title: formData.get('title') } }) + } + + return ( +
+ + + + ) +} + +// submit-button.tsx +'use client' + +import { useFormStatus } from 'react-dom' + +export function SubmitButton() { + const { pending } = useFormStatus() + + return ( + + ) +} +``` + +**Note:** `useFormStatus` must be used in a child component of the form, not in the same component as the form element. diff --git a/.agents/skills/nextjs/references/action-revalidation.md b/.agents/skills/nextjs/references/action-revalidation.md new file mode 100644 index 0000000..ad7b791 --- /dev/null +++ b/.agents/skills/nextjs/references/action-revalidation.md @@ -0,0 +1,78 @@ +--- +title: Revalidate Cache After Mutations +impact: MEDIUM +impactDescription: ensures fresh data after changes +tags: action, revalidation, cache, mutation +--- + +## Revalidate Cache After Mutations + +After a mutation, invalidate only cached reads affected by the write. Use `revalidatePath` for route-level invalidation, `revalidateTag(tag, 'max')` for stale-while-revalidate content, or `updateTag(tag)` inside a Server Action for immediate read-your-writes behavior. + +**Incorrect (stale cache after mutation):** + +```typescript +'use server' + +export async function deletePost(postId: string) { + await db.posts.delete({ where: { id: postId } }) + redirect('/posts') + // Posts list still shows deleted post from cache! +} +``` + +**Correct (invalidating cache):** + +```typescript +'use server' + +import { revalidatePath, revalidateTag, updateTag } from 'next/cache' +import { redirect } from 'next/navigation' + +export async function deletePost(postId: string) { + await db.posts.delete({ where: { id: postId } }) + + // Option 1: Revalidate specific path + revalidatePath('/posts') + + // Option 2: expire and immediately refresh for this user's write + updateTag('posts') + + redirect('/posts') +} + +export async function updatePost(postId: string, formData: FormData) { + await db.posts.update({ + where: { id: postId }, + data: { title: formData.get('title') } + }) + + // Revalidate both the list and detail pages + revalidatePath('/posts') + revalidatePath(`/posts/${postId}`) +} +``` + +**Revalidation strategies:** + +```typescript +// Specific route +revalidatePath('/posts') + +// Dynamic route with specific ID +revalidatePath(`/posts/${postId}`) + +// All routes using a layout +revalidatePath('/dashboard', 'layout') + +// Stale-while-revalidate for webhook/content updates +revalidateTag('posts', 'max') + +// Immediate read-your-writes in a Server Action +updateTag('posts') +updateTag(`post-${postId}`) +``` + +`updateTag` requires `cacheComponents: true` and can only be called from a Server Action. In Route Handlers and webhooks use `revalidateTag(tag, 'max')` instead. + +Reference: [Next.js updating cached data](https://nextjs.org/docs/app/getting-started/caching-and-revalidating#updating-data) diff --git a/.agents/skills/nextjs/references/action-server-action-forms.md b/.agents/skills/nextjs/references/action-server-action-forms.md new file mode 100644 index 0000000..13d1655 --- /dev/null +++ b/.agents/skills/nextjs/references/action-server-action-forms.md @@ -0,0 +1,75 @@ +--- +title: Use Server Actions for Form Submissions +impact: MEDIUM-HIGH +impactDescription: eliminates API routes, type-safe mutations +tags: action, server-action, form, mutation +--- + +## Use Server Actions for Form Submissions + +Server Actions handle form submissions directly without creating API routes. They're type-safe, progressively enhanced, and integrate with caching. + +**Incorrect (API route for form handling):** + +```typescript +// app/api/posts/route.ts +export async function POST(request: Request) { + const data = await request.json() + const post = await db.posts.create({ data }) + return Response.json(post) +} + +// app/posts/new/page.tsx +'use client' + +export default function NewPostPage() { + const handleSubmit = async (e) => { + e.preventDefault() + const formData = new FormData(e.target) + await fetch('/api/posts', { + method: 'POST', + body: JSON.stringify(Object.fromEntries(formData)) + }) + } + // Requires client component, manual fetch, no type safety +} +``` + +**Correct (Server Action):** + +```typescript +// app/posts/new/page.tsx +import { redirect } from 'next/navigation' +import { revalidatePath } from 'next/cache' + +export default function NewPostPage() { + async function createPost(formData: FormData) { + 'use server' + + const title = formData.get('title') as string + const content = formData.get('content') as string + + const post = await db.posts.create({ + data: { title, content } + }) + + revalidatePath('/posts') + redirect(`/posts/${post.id}`) + } + + return ( +
+ +