feat: add experimental plugin API and AWS auth plugin (#452)

### What changed
- Experimental plugin system for extending SafeQL with custom behavior
- First official plugin: `@ts-safeql/plugin-auth-aws` for AWS RDS IAM authentication
- Docs and demo project for plugin usage

### Why
Enables modular extensibility - users can add plugins for custom authentication, connection logic, and analysis hooks without hardcoding every scenario. Keeps SafeQL’s worker-based design while making it extensible.

Author: Newbie012

.agents/docs/authoring-plugin.md

@@ -0,0 +1,73 @@
+# Authoring a SafeQL Plugin
+
+## Checklist
+
+- [ ] Create a new package under `packages/plugins/<name>/` (see [creating a package](creating-package.md))
+- [ ] Add `@ts-safeql/plugin-utils` as a dependency
+- [ ] Add `postgres` as a dependency (if using `createConnection`)
+- [ ] Default-export a `definePlugin()` result
+- [ ] Add tests under `src/plugin.test.ts` and `src/plugin.integration.test.ts`
+- [ ] Add a demo under `demos/plugin-<name>/`
+- [ ] Add a docs page at `docs/plugins/<name>.md` or update `docs/compatibility/<name>.md`
+- [ ] Add sidebar entry in `docs/.vitepress/config.ts`
+
+## Plugin Hooks
+
+### `createConnection`
+
+Custom database connection strategy. Returns a `postgres` Sql instance.
+
+### `connectionDefaults`
+
+Default config values merged under user config. Use for library-specific type overrides.
+
+### `onTarget({ node, context })`
+
+Called for each TaggedTemplateExpression. Return:
+
+- `TargetMatch` object to proceed with checking
+- `false` to skip entirely (e.g., `sql.fragment`)
+- `undefined` to defer to SafeQL default
+
+### `onExpression({ node, context })`
+
+Called for each interpolated expression. Return:
+
+- `string` - SQL fragment (use `$N` for placeholder)
+- `false` - skip the entire query
+- `undefined` - use default `$N::type` behavior
+
+## Key Constraints
+
+- Use `type` aliases (not `interface`) for the config type
+- Plugin names are auto-prefixed with `safeql-plugin-`
+- Package names must be prefixed with `plugin-` (e.g., `@ts-safeql/plugin-auth-aws`)
+- Test file naming: `plugin.test.ts` for unit tests, `plugin.integration.test.ts` for DB tests
+
+## Example Structure
+
+```
+packages/plugins/my-lib/
+├── src/
+│   ├── index.ts              # definePlugin() export
+│   ├── plugin.test.ts        # Unit tests (PluginTestDriver)
+│   └── plugin.integration.test.ts  # Integration tests (RuleTester)
+├── package.json
+├── tsconfig.json
+└── build.config.ts
+```
+
+## Testing
+
+Unit tests use `PluginTestDriver` from `@ts-safeql/plugin-utils/testing`:
+
+```ts
+import { PluginTestDriver } from "@ts-safeql/plugin-utils/testing";
+import plugin from "./plugin";
+
+const driver = new PluginTestDriver({ plugin: plugin.factory({}) });
+const result = driver.toSQL(`import { sql } from "my-lib"; sql.unsafe\`SELECT 1\``);
+expect(result).toEqual({ sql: "SELECT 1" });
+```
+
+Integration tests use `@typescript-eslint/rule-tester` with a real database.

.agents/docs/coding-guidelines.md

@@ -0,0 +1,9 @@
+# Coding Guidelines
+
+No headline comments. Don't use comments as section dividers (e.g., `// ---- Helpers ----`). If a file needs sections, it needs separate files.
+
+No comments that explain what code does. If a comment restates the code below it, the code isn't clear enough. Rename, extract, or restructure instead. A comment like `// Check if the user is valid` above `if (isValidUser(u))` is noise. Comments should explain why, not what.
+
+Exception: `// ARRANGE`, `// ACT`, `// ASSERT` comments in tests are allowed.
+
+Avoid using `any`, `as unknown as`, or any unsafe casts. Use type inference and type guards instead.

.agents/docs/creating-package.md

@@ -0,0 +1,8 @@
+# Creating a New Package
+
+1. Create the directory under `packages/` (or `packages/plugins/` for plugins)
+2. Add `package.json` — mirror an existing package for the `name`, `exports`, `scripts`, and `type` fields
+3. Add `tsconfig.json` extending the root `tsconfig.node.json` (adjust the relative path based on depth)
+4. Add `build.config.ts` — copy from an existing package
+5. Run `pnpm install`
+6. Workspace glob `packages/plugins/*` is already in `pnpm-workspace.yaml`

.changeset/plugin-system.md

@@ -0,0 +1,11 @@
+---
+"@ts-safeql/eslint-plugin": minor
+"@ts-safeql/shared": minor
+"@ts-safeql/plugin-utils": minor
+"@ts-safeql/plugin-auth-aws": minor
+---
+
+Add experimental plugin API and AWS auth plugin
+
+- Experimental plugin system for extending SafeQL with custom behavior
+- First official plugin: `@ts-safeql/plugin-auth-aws` for AWS RDS IAM authentication

.gitignore

@@ -2,4 +2,6 @@ node_modules
 .turbo
 *.tsbuildinfo
 dist
-generated
+generated
+.env
+.env.local

AGENTS.md

@@ -0,0 +1,20 @@
+# Agent Guidelines
+
+## Common Commands
+
+```sh
+pnpm build          # production build (via turbo)
+pnpm dev            # stub all packages for local dev
+pnpm test           # run all tests (via turbo)
+pnpm --filter <pkg> test -- --run   # single package tests
+```
+
+## Gotchas
+
+- Never run `pnpm --filter <pkg> build`. Instead, always use `pnpm build` (which handles dependency ordering and output formats correctly).
+- For local dev, use `pnpm dev` (stubs via `unbuild --stub`, bypasses rollup entirely).
+- A local PostgreSQL instance is expected at `postgres://postgres:postgres@localhost:5432/postgres`.
+
+## References
+ - [Creating a New Package](.agents/docs/creating-package.md)
+ - [Authoring a Plugin](.agents/docs/authoring-plugin.md)

demos/plugin-aws-iam/.env.example

@@ -0,0 +1,6 @@
+SAFEQL_AWS_PROFILE=my-profile
+SAFEQL_AWS_REGION=eu-west-1
+SAFEQL_DATABASE_HOST=<instance>.<id>.<region>.rds.amazonaws.com
+SAFEQL_DATABASE_NAME=mydb
+SAFEQL_DATABASE_PORT=5432
+SAFEQL_DATABASE_USER=iam_user

demos/plugin-aws-iam/eslint.config.js

@@ -0,0 +1,31 @@
+// @ts-check
+
+import "dotenv/config";
+import safeql from "@ts-safeql/eslint-plugin/config";
+import awsIamAuth from "@ts-safeql/plugin-auth-aws";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config({
+  files: ["src/**/*.ts"],
+  languageOptions: {
+    parser: tseslint.parser,
+    parserOptions: {
+      projectService: true,
+    },
+  },
+  extends: [
+    safeql.configs.connections({
+      plugins: [
+        awsIamAuth({
+          databaseHost: process.env.SAFEQL_DATABASE_HOST ?? "",
+          databasePort: Number(process.env.SAFEQL_DATABASE_PORT ?? 5432),
+          databaseUser: process.env.SAFEQL_DATABASE_USER ?? "",
+          databaseName: process.env.SAFEQL_DATABASE_NAME ?? "",
+          awsRegion: process.env.SAFEQL_AWS_REGION ?? "",
+          awsProfile: process.env.SAFEQL_AWS_PROFILE,
+        }),
+      ],
+      targets: [{ tag: "sql", transform: "{type}[]" }],
+    }),
+  ],
+});

demos/plugin-aws-iam/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ts-safeql-demos/plugin-aws-iam",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "lint": "bash scripts/verify-plugin-error.sh",
+    "lint:live": "eslint src",
+    "lint!": "eslint src --fix"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.23.0",
+    "@types/node": "^22.13.13",
+    "dotenv": "^16.4.7",
+    "eslint": "^9.23.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.28.0"
+  },
+  "dependencies": {
+    "@ts-safeql/plugin-auth-aws": "workspace:*",
+    "@ts-safeql/eslint-plugin": "workspace:*",
+    "postgres": "^3.4.5"
+  }
+}

demos/plugin-aws-iam/scripts/verify-plugin-error.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -euo pipefail
+
+# Simulate a CI environment with no AWS credentials or config.
+export AWS_CONFIG_FILE=/dev/null
+export AWS_SHARED_CREDENTIALS_FILE=/dev/null
+unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE 2>/dev/null || true
+
+output=$(pnpm exec eslint src 2>&1 || true)
+
+echo "$output"
+
+echo "$output" | grep -q '\[safeql-plugin-aws-iam\]'   || { echo "FAIL: plugin error prefix missing"; exit 1; }
+! echo "$output" | grep -q 'Internal error'            || { echo "FAIL: got Internal error"; exit 1; }
+! echo "$output" | grep -q 'could not be loaded'       || { echo "FAIL: plugin failed to load"; exit 1; }
+
+echo "OK: plugin loaded, failed with expected plugin error"