chore: add CLI project, pin System.Text.Json 8.0.5, update CI gate and docs

Author: KeelMatrix

.github/workflows/ci.yml

@@ -27,6 +27,14 @@ jobs:
         run: dotnet build --configuration Release --no-restore
       - name: Test
         run: dotnet test --configuration Release --no-build --collect:"XPlat Code Coverage" --results-directory ./artifacts/TestResults
+      - name: QueryWatch gate (optional - JSON)
+        shell: pwsh
+        run: |
+          if (Test-Path "artifacts/qwatch.report.json") {
+            dotnet run --project tools/KeelMatrix.QueryWatch.Cli -- --input artifacts/qwatch.report.json --max-queries 50
+          } else {
+            Write-Host "No QueryWatch JSON found; skipping QueryWatch gate."
+          }
       - name: Pack
         run: dotnet pack --configuration Release --no-build --include-symbols --p:SymbolPackageFormat=snupkg --output ./artifacts/packages
       - name: Upload packages
@@ -57,8 +65,3 @@ jobs:
 #   if: always()
 #   run: |
 #     echo "TODO: Scan changed fixture files for PII patterns"
-#
-# - name: Query performance budget
-#   if: always()
-#   run: |
-#     echo "TODO: Check test output for query counts / durations and enforce a threshold"

Directory.Packages.props

@@ -11,6 +11,10 @@
     <PackageVersion Include="xunit" Version="2.7.1" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.7" />
     <PackageVersion Include="coverlet.collector" Version="6.0.2" />
-	<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+
+    <!-- JSON serializer used by QueryWatch.Reporting -->
+    <!-- Pin a patched System.Text.Json so NuGet never resolves 8.0.0 -->
+    <PackageVersion Include="System.Text.Json" Version="8.0.5" />
   </ItemGroup>
 </Project>

KeelMatrix.QueryWatch.sln

@@ -6,6 +6,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KeelMatrix.QueryWatch", "sr
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KeelMatrix.QueryWatch.Tests", "tests\KeelMatrix.QueryWatch.Tests\KeelMatrix.QueryWatch.Tests.csproj", "{22222222-2222-2222-2222-222222222222}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KeelMatrix.QueryWatch.Cli", "tools\KeelMatrix.QueryWatch.Cli\KeelMatrix.QueryWatch.Cli.csproj", "{33333333-3333-3333-3333-333333333333}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -20,6 +22,10 @@ Global
 		{22222222-2222-2222-2222-222222222222}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{22222222-2222-2222-2222-222222222222}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{22222222-2222-2222-2222-222222222222}.Release|Any CPU.Build.0 = Release|Any CPU
+		{33333333-3333-3333-3333-333333333333}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{33333333-3333-3333-3333-333333333333}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{33333333-3333-3333-3333-333333333333}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{33333333-3333-3333-3333-333333333333}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

README.md

@@ -1,146 +1,57 @@
 # KeelMatrix.QueryWatch
 
-[![Build](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml) [![NuGet](https://img.shields.io/nuget/v/KeelMatrix.QueryWatch.svg)](https://www.nuget.org/packages/KeelMatrix.QueryWatch/)
-
-**For developers building tools and libraries, `KeelMatrix.QueryWatch` delivers a working NuGet package in minutes without the usual boilerplate.**
-
-This repository is a template that bundles together a library project, an xUnit test project, a sample console application, common build configuration, GitHub workflows, licensing and telemetry stubs, and a full suite of documentation. It allows you to start publishing high‑quality NuGet packages with minimal effort.
+> Catch N+1 queries and slow SQL in tests. Fail builds when query budgets are exceeded.
 
-## Getting started
-
-1. Clone or download this template.
-2. Rename the solution and default project names when prompted to match your package name.
-3. Open the solution in Visual Studio 2022 or run `dotnet build` from the command line.
+[![Build](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml) [![NuGet](https://img.shields.io/nuget/v/KeelMatrix.QueryWatch.svg)](https://www.nuget.org/packages/KeelMatrix.QueryWatch/)
 
-### Install from NuGet
+## Install
 
 ```bash
 dotnet add package KeelMatrix.QueryWatch
 ```
 
-### Quickstart
+## 5‑minute success (with JSON for CI)
 
-Here's how to use the sample API exposed by the template:
+**Per‑test scope → export JSON:**
 
 ```csharp
-using KeelMatrix.QueryWatch;
+using KeelMatrix.QueryWatch.Testing;
 
-var hello = new Hello();
-Console.WriteLine(hello.Greet("World"));
-```
-
-You can also explore the sample console application by running:
+// JSON is written even if assertions fail (helps CI).
+using var q = QueryWatchScope.Start(
+    maxQueries: 5,
+    maxAverage: TimeSpan.FromMilliseconds(50),
+    exportJsonPath: "artifacts/qwatch.report.json");
 
-```bash
-cd samples/KeelMatrix.QueryWatch.Sample
-dotnet run
+// wire EF Core or ADO to q.Session, run your code...
 ```
 
-## Target frameworks
-
-This package targets the following frameworks:
-
-* `net8.0` – for modern .NET applications.
-* `netstandard2.0` – for broad compatibility with .NET Framework and .NET Core.
+**Gate in CI (already wired in ci.yml):**
 
-## Versioning and releases
-
-This project follows [Semantic Versioning](https://semver.org/). Breaking changes or removal of a target framework require a new major version. New features that do not break existing behavior increment the minor version. Patch versions are used for bug fixes and small improvements. Pre‑release packages use suffixes such as `-alpha`, `-beta`, or `-rc`.
-
-Release notes are maintained in [`CHANGELOG.md`](CHANGELOG.md). To create a new release:
-
-1. Update the version in the library’s `.csproj` file and add an entry in the changelog.
-2. Commit your changes and tag the commit (for example `git tag v1.0.0`).
-3. Push the tag. GitHub Actions will build, sign, and publish the package to nuget.org (assuming you have configured `NUGET_API_KEY` in your repository secrets).
-
-## Documentation
-
-* [`LICENSE`](LICENSE) – The license this project is released under (MIT by default).
-* [`SECURITY.md`](SECURITY.md) – How to report security issues.
-* [`CONTRIBUTING.md`](CONTRIBUTING.md) – Guidelines for contributors.
-* [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) – The code of conduct for this project.
-* [`PRIVACY.md`](PRIVACY.md) – Information about telemetry and how to disable it.
-
-## FAQ
-
-### How do I build and test the package locally?
-
-Run the following commands from the repository root:
-
-```bash
-dotnet restore
-dotnet build --configuration Release
-dotnet test --configuration Release --no-build
-dotnet pack --configuration Release --no-build --output ./artifacts/packages
+```pwsh
+dotnet run --project tools/KeelMatrix.QueryWatch.Cli -- --input artifacts/qwatch.report.json --max-queries 50
 ```
 
-The resulting `.nupkg` and `.snupkg` files can be found in `./artifacts/packages`.
-
-### How do I consume the package without publishing it to NuGet?
-
-Update your `NuGet.config` to add a local feed pointing at the `artifacts/packages` folder. For example:
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configuration>
-  <packageSources>
-    <add key="local" value="./artifacts/packages" />
-    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
-  </packageSources>
-</configuration>
-```
-
-Then run `dotnet restore` in your consuming project.
-
-### How do I add paid features or telemetry?
-
-The template includes stub interfaces `ILicenseValidator` and `ITelemetryClient` with no‑op implementations. Replace these with your own implementations and wire them into your API as needed. See comments in the source code for guidance.
-
----
-
-_This README is intentionally generic. Replace the sample code and descriptive text with information relevant to your package._
-
-## Why this template (promise line)
-
-For developers shipping .NET libraries quickly: this template gets you from **idea → publishable NuGet** in minutes, with tests, CI, SourceLink, symbols, docs, and repo hygiene baked in.
-
-## Supported TFMs
-
-- `net8.0`
-- `netstandard2.0`
-
-## Release & versioning policy
-
-- **SemVer**: PATCH=fixed bugs, MINOR=new features (no breaking changes), MAJOR=breaking changes or dropping a TFM.
-- Use pre-releases: `-alpha`, `-beta`, `-rc` as needed.
-- Tag releases as `vX.Y.Z`; CI picks up tags to publish.
-- Maintain `CHANGELOG.md` for notable changes.
-
-## NuGet ID & branding
-
-- Choose a consistent **package ID prefix** (e.g., `KeelMatrix.*`).
-- When ready, **reserve your prefix** on nuget.org (TODO: add link).
-- Set **Authors**, **RepositoryUrl**, **PackageProjectUrl**, **icon** in the `.csproj`.
-
-## CI artifacts
-
-CI uploads built packages to `./artifacts/packages` as workflow artifacts you can download.
+**EF Core:** see `src/KeelMatrix.QueryWatch/README.md` for full example.
 
-## Licensing & monetization stubs
+## Why QueryWatch?
 
-This template includes `ILicenseValidator` + `NoopLicenseValidator` and doc notes to wire a MoR (Paddle/Lemon Squeezy). Mark paid features in code and validate via your chosen MoR before enabling. Include an **offline grace** policy (e.g., 7–30 days).
+- **Prevents N+1 and slow queries** before they reach production.
+- **Lightweight**: plug into EF Core or wrap ADO/Dapper connection.
+- **Redaction hooks**: mask PII or noisy literals.
+- **CI‑friendly**: export JSON and use the CLI gate to fail PRs.
 
-## Telemetry (optional, off by default)
+## JSON schema
 
-Implements `ITelemetryClient` with a no‑op default. If you later enable telemetry, publish a clear privacy note and allow opt‑out via `TOOLNAME_NO_TELEMETRY=1`.
+Stable, compact summary emitted by `KeelMatrix.QueryWatch.Reporting.QueryWatchJson.ExportToFile(report, path)` with fields:
+`schema, startedAt, stoppedAt, totalQueries, totalDurationMs, averageDurationMs, events[]`.
 
-## Release checklist
+## CLI
 
-- [ ] Tests pass on Release configuration
-- [ ] `dotnet pack` produces one `.nupkg` and one `.snupkg`
-- [ ] Version bumped in the `.csproj`
-- [ ] Tag created `vX.Y.Z`
-- [ ] CI artifacts verified; (optional) nuget.org push succeeded
+- `--input` path to JSON (default `artifacts/qwatch.report.json`)
+- `--max-queries`, `--max-average-ms`, `--max-total-ms`
+- `--baseline <file>` and `--write-baseline` to store today’s good results
 
+## License
 
-> **Note:** Consider adopting [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning) later for repo-driven versioning (optional; not bundled in the template).
+MIT. See `LICENSE`.  See `PRIVACY.md` for telemetry stance (off by default).

src/KeelMatrix.QueryWatch/Ado/QueryWatchCommand.cs

@@ -0,0 +1,136 @@
+#nullable enable
+using System.Data;
+using System.Data.Common;
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace KeelMatrix.QueryWatch.Ado
+{
+    /// <summary>
+    /// Delegating <see cref="DbCommand"/> that measures execution and records into a session.
+    /// </summary>
+    public sealed class QueryWatchCommand : DbCommand
+    {
+        private readonly DbCommand _inner;
+        private readonly QueryWatchSession _session;
+        private readonly DbConnection? _connection; // wrapper connection
+
+        public QueryWatchCommand(DbCommand inner, QueryWatchSession session, DbConnection? wrapperConnection = null)
+        {
+            _inner = inner ?? throw new ArgumentNullException(nameof(inner));
+            _session = session ?? throw new ArgumentNullException(nameof(session));
+            _connection = wrapperConnection;
+        }
+
+        [AllowNull]
+        public override string CommandText
+        {
+            get => _inner.CommandText;
+            set => _inner.CommandText = value;
+        }
+
+        public override int CommandTimeout
+        {
+            get => _inner.CommandTimeout;
+            set => _inner.CommandTimeout = value;
+        }
+
+        public override CommandType CommandType
+        {
+            get => _inner.CommandType;
+            set => _inner.CommandType = value;
+        }
+
+        protected override DbConnection? DbConnection
+        {
+            get => _connection ?? _inner.Connection;
+            set
+            {
+                if (value is null) {
+                    _inner.Connection = null;
+                }
+                else if (value is QueryWatchConnection qwc) {
+                    _inner.Connection = qwc.Inner;
+                }
+                else {
+                    _inner.Connection = value;
+                }
+            }
+        }
+
+        protected override DbParameterCollection DbParameterCollection => _inner.Parameters;
+
+        protected override DbTransaction? DbTransaction
+        {
+            get => _inner.Transaction;
+            set => _inner.Transaction = value;
+        }
+
+        public override bool DesignTimeVisible
+        {
+            get => _inner.DesignTimeVisible;
+            set => _inner.DesignTimeVisible = value;
+        }
+
+        public override UpdateRowSource UpdatedRowSource
+        {
+            get => _inner.UpdatedRowSource;
+            set => _inner.UpdatedRowSource = value;
+        }
+
+        public override void Cancel() => _inner.Cancel();
+        public override void Prepare() => _inner.Prepare();
+
+        protected override DbParameter CreateDbParameter() => _inner.CreateParameter();
+
+        private void Record(TimeSpan elapsed) => _session.Record(_inner.CommandText ?? string.Empty, elapsed);
+
+        public override int ExecuteNonQuery()
+        {
+            var sw = Stopwatch.StartNew();
+            try { return _inner.ExecuteNonQuery(); }
+            finally { sw.Stop(); Record(sw.Elapsed); }
+        }
+
+        public override object? ExecuteScalar()
+        {
+            var sw = Stopwatch.StartNew();
+            try { return _inner.ExecuteScalar(); }
+            finally { sw.Stop(); Record(sw.Elapsed); }
+        }
+
+        protected override DbDataReader ExecuteDbDataReader(CommandBehavior behavior)
+        {
+            var sw = Stopwatch.StartNew();
+            try { return _inner.ExecuteReader(behavior); }
+            finally { sw.Stop(); Record(sw.Elapsed); }
+        }
+
+        public override async Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken)
+        {
+            var sw = Stopwatch.StartNew();
+            try { return await _inner.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false); }
+            finally { sw.Stop(); Record(sw.Elapsed); }
+        }
+
+        public override async Task<object?> ExecuteScalarAsync(CancellationToken cancellationToken)
+        {
+            var sw = Stopwatch.StartNew();
+            try { return await _inner.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false); }
+            finally { sw.Stop(); Record(sw.Elapsed); }
+        }
+
+        protected override async Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken)
+        {
+            var sw = Stopwatch.StartNew();
+            try { return await _inner.ExecuteReaderAsync(behavior, cancellationToken).ConfigureAwait(false); }
+            finally { sw.Stop(); Record(sw.Elapsed); }
+        }
+
+        protected override void Dispose(bool disposing)
+        {
+            if (disposing) _inner.Dispose();
+            base.Dispose(disposing);
+        }
+    }
+}