feat(plugin-assert): add assertion plugin (#46)

Author: andrewmelchor

.github/workflows/release-plugin-assert.yml

@@ -0,0 +1,96 @@
+name: Release Plugin Assert
+
+on:
+  push:
+    tags:
+      - "plugin-assert-v*.*.*"
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Dry run (don't actually publish)"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    name: Build and Publish Plugin Assert
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            # Extract version from tag (plugin-assert-v1.2.3 -> 1.2.3)
+            VERSION="${GITHUB_REF#refs/tags/plugin-assert-v}"
+          else
+            # For manual trigger, read from package.json
+            VERSION=$(jq -r .version packages/plugins/assert/package.json)
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version: $VERSION"
+
+      - name: Verify version matches package.json
+        run: |
+          PKG_VERSION=$(jq -r .version packages/plugins/assert/package.json)
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          if [[ "$PKG_VERSION" != "$TAG_VERSION" ]]; then
+            echo "Error: Tag version ($TAG_VERSION) does not match package.json version ($PKG_VERSION)"
+            echo "The tag must match the committed version. Ensure you've merged the Version Packages PR first."
+            exit 1
+          fi
+          echo "Version verified: $PKG_VERSION"
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Verify publish manifest
+        run: bun run script/verify-publish-manifest.ts packages/plugins/assert/package.json
+
+      - name: Build core (workspace dependency)
+        run: bun run build
+        working-directory: packages/core
+
+      - name: Build
+        run: bun run build
+        working-directory: packages/plugins/assert
+
+      - name: Check types
+        run: bun run check-types
+        working-directory: packages/plugins/assert
+
+      - name: Run tests
+        run: bun run test
+        working-directory: packages/plugins/assert
+
+      - name: Publish to npm
+        if: ${{ github.event_name == 'push' || !inputs.dry-run }}
+        run: npm publish --access public
+        working-directory: packages/plugins/assert
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Dry run publish
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry-run }}
+        run: |
+          npm pack
+          echo "[dry-run] Would publish @t-req/plugin-assert@${{ steps.version.outputs.version }}"
+        working-directory: packages/plugins/assert

bun.lock

@@ -18,6 +18,7 @@
     "release:core": "bun run script/release.ts --package core",
     "release:sdk": "bun run script/release.ts --package sdk",
     "release:plugin-base": "bun run script/release.ts --package plugin-base",
+    "release:plugin-assert": "bun run script/release.ts --package plugin-assert",
     "sst:dev": "sst dev",
     "sst:deploy": "sst deploy",
     "sst:deploy:prod": "sst deploy --stage production"

package.json

@@ -0,0 +1,9 @@
+# @t-req/plugin-assert
+
+## 0.1.0
+
+### Features
+
+- Initial release.
+- Runtime assertion evaluation for `# @assert ...` directives.
+- `treq validate` integration for assertion diagnostics.

packages/plugins/assert/CHANGELOG.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tensorix labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/plugins/assert/LICENSE

@@ -0,0 +1,84 @@
+# @t-req/plugin-assert
+
+Inline assertions for [t-req](https://github.com/tensorix-labs/t-req) using `# @assert ...` directives in `.http` files.
+
+[![npm version](https://img.shields.io/npm/v/@t-req/plugin-assert.svg)](https://www.npmjs.com/package/@t-req/plugin-assert)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install @t-req/plugin-assert
+
+# or
+bun add @t-req/plugin-assert
+yarn add @t-req/plugin-assert
+pnpm add @t-req/plugin-assert
+```
+
+## Setup
+
+Add to `treq.jsonc`:
+
+```jsonc
+{
+  "plugins": ["@t-req/plugin-assert"]
+}
+```
+
+Or load ad-hoc:
+
+```bash
+treq run ./requests/user.http --plugin @t-req/plugin-assert
+```
+
+## Assertion Syntax
+
+```http
+# @assert status == 200
+# @assert header Content-Type contains application/json
+# @assert body contains "ok"
+# @assert jsonpath $.token exists
+GET https://api.example.com/health
+```
+
+Supported targets:
+
+| Target | Operators | Example |
+|---|---|---|
+| `status` | `== != > >= < <=` | `# @assert status == 200` |
+| `header <name>` | `exists == != contains` | `# @assert header X-Trace-Id exists` |
+| `body` | `contains not-contains` | `# @assert body not-contains "error"` |
+| `jsonpath <expr>` | `exists == !=` | `# @assert jsonpath $.count == 2` |
+
+## Behavior
+
+- Assertions run in `response.after`.
+- One summary report is emitted per request with:
+  - `kind: "assert"`
+  - `passed: boolean`
+  - `total`, `failed`
+  - `checks[]` details
+- Any failed assertion sets `passed: false`, and `treq run` exits with code `1`.
+- Malformed assertions also fail the run (fail-fast behavior).
+
+## Validate Integration
+
+`treq validate` uses this plugin's `validate` hook to surface assertion issues early:
+
+- `assert.syntax`
+- `assert.operator`
+- `assert.target`
+- `assert.missing-value`
+- `assert.invalid-jsonpath`
+- `assert.position`
+
+Example:
+
+```bash
+treq validate ./requests
+```
+
+## License
+
+MIT

packages/plugins/assert/README.md

@@ -0,0 +1,66 @@
+{
+  "name": "@t-req/plugin-assert",
+  "version": "0.1.0",
+  "description": "Inline assertion plugin for t-req (@assert directives in .http files)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tensorix-labs/t-req",
+    "directory": "packages/plugins/assert"
+  },
+  "homepage": "https://github.com/tensorix-labs/t-req#readme",
+  "bugs": {
+    "url": "https://github.com/tensorix-labs/t-req/issues"
+  },
+  "keywords": [
+    "t-req",
+    "plugin",
+    "assertions",
+    "jsonpath",
+    "http-testing"
+  ],
+  "author": "tensorix labs",
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0.0"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build --target node --minify --sourcemap --outdir ./dist --root ./src ./src/index.ts",
+    "build:types": "tsc -p tsconfig.build.json",
+    "check-types": "tsc -p tsconfig.build.json --noEmit",
+    "test": "bun test",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "prepublishOnly": "bun run build && bun run test"
+  },
+  "peerDependencies": {
+    "@t-req/core": "^0.2.3"
+  },
+  "dependencies": {
+    "fast-deep-equal": "^3.1.3",
+    "jsonpath-plus": "^10.3.0"
+  },
+  "devDependencies": {
+    "@t-req/core": "workspace:*",
+    "@types/bun": "latest"
+  }
+}