@dudousxd/nestjs-authz-testing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davi Carvalho
+
+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.

package/README.md

@@ -0,0 +1,34 @@
+# `@dudousxd/nestjs-authz-testing`
+
+Test helpers for [`@dudousxd/nestjs-authz`](../core). Build a real `Gate`/`BoundGate`
+from fixture users, policies, gates, and an in-memory permission/role provider — no
+Nest module, no database — then assert verdicts with `expectCan` / `expectCannot`.
+
+```ts
+import 'reflect-metadata';
+import { Policy } from '@dudousxd/nestjs-authz';
+import { buildGate, expectCan, expectCannot, FakePermissionProvider } from '@dudousxd/nestjs-authz-testing';
+
+@Policy(Post)
+class PostPolicy {
+  update(user, post) { return user?.id === post.authorId; }
+}
+
+const gate = buildGate({ policies: [new PostPolicy()] });
+await expectCan(gate, { id: 1 }, 'update', new Post(10, 1));
+await expectCannot(gate, { id: 2 }, 'update', new Post(10, 1));
+
+// RBAC seam, zero DB — wildcard grants work via the core matcher:
+const gate2 = buildGate({ permissionProvider: new FakePermissionProvider({ '1': ['posts.*'] }) });
+await expectCan(gate2, { id: 1 }, 'posts.update');
+```
+
+## API
+
+- `buildGate(options?)` → `Gate` from `{ policies, gates, superAdmin, after, resolveRoles, permissionProvider, roleProvider }`.
+- `buildBoundGate(user, options?)` → `BoundGate` bound to a fixture user.
+- `expectCan(gate, user, ability, resource?)` / `expectCannot(...)` — assert the verdict
+  (accept a `Gate` + user, or a `BoundGate` with `undefined` user). `expectCannot`
+  treats an unresolved ability as "cannot".
+- `FakePermissionProvider` / `FakeRoleProvider` — in-memory RBAC seams keyed by user id.
+- `AuthzAssertionError` — thrown on assertion failure.

package/dist/fakes.d.ts

@@ -0,0 +1,41 @@
+import type { PermissionProvider, RoleProvider, User } from '@dudousxd/nestjs-authz';
+/**
+ * A grants table for {@link FakePermissionProvider} / {@link FakeRoleProvider},
+ * keyed by a user identity. The default identity is the user's `id` (or the user
+ * itself when it has none), so `{ '1': ['posts.*'] }` grants user #1.
+ */
+export type FakePermissionGrants = Record<string, string[]>;
+/**
+ * An in-memory {@link PermissionProvider} for tests — no database. Grants are a
+ * `{ userId: permissions[] }` table; the user's granted set is exposed via
+ * `getPermissions`, so the core's wildcard matcher applies (`posts.*` satisfies
+ * `posts.update`, `*` satisfies anything) exactly as with a real RBAC adapter.
+ *
+ * @example
+ * const provider = new FakePermissionProvider({ '1': ['posts.*'], '2': ['posts.read'] });
+ * const gate = buildGate({ permissionProvider: provider });
+ * await expectCan(gate, { id: 1 }, 'posts.update'); // wildcard grant
+ */
+export declare class FakePermissionProvider implements PermissionProvider {
+    private readonly grants;
+    private readonly identity;
+    constructor(grants?: FakePermissionGrants, identity?: (user: User) => string);
+    /** Grant `permission` to a user (chainable). */
+    grant(user: User, permission: string): this;
+    hasPermission(user: User, permission: string): boolean;
+    getPermissions(user: User): string[] | undefined;
+}
+/**
+ * An in-memory {@link RoleProvider} for tests — a `{ userId: roles[] }` table. Use
+ * with `buildGate({ roleProvider })` to exercise coarse role checks (`gate.hasRole`)
+ * without a database.
+ */
+export declare class FakeRoleProvider implements RoleProvider {
+    private readonly roles;
+    private readonly identity;
+    constructor(roles?: FakePermissionGrants, identity?: (user: User) => string);
+    /** Assign `role` to a user (chainable). */
+    assign(user: User, role: string): this;
+    getRoles(user: User): string[] | undefined;
+}
+//# sourceMappingURL=fakes.d.ts.map

package/dist/fakes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakes.d.ts","sourceRoot":"","sources":["../src/fakes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAErF;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAY5D;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAGhD,MAAM,GAAE,oBAAyB,EACjC,QAAQ,GAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAwB;IAMpD,gDAAgD;IAChD,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAQ3C,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAItD,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,SAAS;CAIjD;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAGhD,KAAK,GAAE,oBAAyB,EAChC,QAAQ,GAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAwB;IAMpD,2CAA2C;IAC3C,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQtC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,SAAS;CAI3C"}

package/dist/fakes.js

@@ -0,0 +1,71 @@
+/** Default identity: the user's `id` (stringified), else the value itself. */
+function defaultIdentity(user) {
+    if (user == null)
+        return '';
+    if (typeof user === 'object') {
+        const id = user.id;
+        if (id != null)
+            return String(id);
+    }
+    return String(user);
+}
+/**
+ * An in-memory {@link PermissionProvider} for tests — no database. Grants are a
+ * `{ userId: permissions[] }` table; the user's granted set is exposed via
+ * `getPermissions`, so the core's wildcard matcher applies (`posts.*` satisfies
+ * `posts.update`, `*` satisfies anything) exactly as with a real RBAC adapter.
+ *
+ * @example
+ * const provider = new FakePermissionProvider({ '1': ['posts.*'], '2': ['posts.read'] });
+ * const gate = buildGate({ permissionProvider: provider });
+ * await expectCan(gate, { id: 1 }, 'posts.update'); // wildcard grant
+ */
+export class FakePermissionProvider {
+    grants;
+    identity;
+    constructor(grants = {}, identity = defaultIdentity) {
+        this.identity = identity;
+        this.grants = new Map(Object.entries(grants).map(([key, perms]) => [key, new Set(perms)]));
+    }
+    /** Grant `permission` to a user (chainable). */
+    grant(user, permission) {
+        const key = this.identity(user);
+        const set = this.grants.get(key) ?? new Set();
+        set.add(permission);
+        this.grants.set(key, set);
+        return this;
+    }
+    hasPermission(user, permission) {
+        return this.grants.get(this.identity(user))?.has(permission) ?? false;
+    }
+    getPermissions(user) {
+        const set = this.grants.get(this.identity(user));
+        return set ? [...set] : undefined;
+    }
+}
+/**
+ * An in-memory {@link RoleProvider} for tests — a `{ userId: roles[] }` table. Use
+ * with `buildGate({ roleProvider })` to exercise coarse role checks (`gate.hasRole`)
+ * without a database.
+ */
+export class FakeRoleProvider {
+    roles;
+    identity;
+    constructor(roles = {}, identity = defaultIdentity) {
+        this.identity = identity;
+        this.roles = new Map(Object.entries(roles).map(([key, names]) => [key, new Set(names)]));
+    }
+    /** Assign `role` to a user (chainable). */
+    assign(user, role) {
+        const key = this.identity(user);
+        const set = this.roles.get(key) ?? new Set();
+        set.add(role);
+        this.roles.set(key, set);
+        return this;
+    }
+    getRoles(user) {
+        const set = this.roles.get(this.identity(user));
+        return set ? [...set] : undefined;
+    }
+}
+//# sourceMappingURL=fakes.js.map

package/dist/fakes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakes.js","sourceRoot":"","sources":["../src/fakes.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Test helpers for `@dudousxd/nestjs-authz`.
+ *
+ * Build a real {@link Gate} (no Nest module, no DB) from fixture policies, ad-hoc
+ * gates, hooks, and an optional in-memory permission/role provider — then assert
+ * verdicts with {@link expectCan}/{@link expectCannot}. The helpers exercise the
+ * SAME resolution path the production Gate uses, so a policy that passes here passes
+ * in the app.
+ *
+ * @example
+ * ```ts
+ * const gate = buildGate({ policies: [new PostPolicy()] });
+ * await expectCan(gate, { id: 1 }, 'update', new Post(1, 1));
+ * await expectCannot(gate, { id: 2 }, 'update', new Post(1, 1));
+ * ```
+ *
+ * @module
+ */
+import { type AfterHook, BoundGate, Gate, type GateFn, type PermissionProvider, type PolicyInstance, type Resource, type RoleProvider, type SuperAdminHook, type User } from '@dudousxd/nestjs-authz';
+export { FakePermissionProvider, FakeRoleProvider, } from './fakes.js';
+export type { FakePermissionGrants } from './fakes.js';
+/** Fixture configuration for {@link buildGate}. Every field is optional. */
+export interface BuildGateOptions {
+    /**
+     * Policy INSTANCES to register (e.g. `new PostPolicy()`). Unlike the Nest module,
+     * the test helper does not run DI — pass already-constructed instances. Each MUST be
+     * `@Policy(Resource)`-decorated (the registry resolves by resource constructor and
+     * throws on an undecorated class, same as production).
+     */
+    policies?: PolicyInstance[];
+    /** Ad-hoc, model-less gates keyed by ability name (same as `gate.define(name, fn)`). */
+    gates?: Record<string, GateFn>;
+    /** Global super-admin before-hook (Laravel `Gate::before`). */
+    superAdmin?: SuperAdminHook;
+    /** Global `after` hook (Laravel `Gate::after`). */
+    after?: AfterHook;
+    /** Override how a user's roles are derived (default reads `user.roles`/`user.role`). */
+    resolveRoles?: (user: User) => string[] | undefined | Promise<string[] | undefined>;
+    /**
+     * An in-memory {@link PermissionProvider} (the RBAC seam) — grants named abilities
+     * when the fixture user holds the permission. Use {@link FakePermissionProvider} for
+     * a zero-DB stand-in.
+     */
+    permissionProvider?: PermissionProvider;
+    /** An in-memory {@link RoleProvider} for coarse role checks. Use {@link FakeRoleProvider}. */
+    roleProvider?: RoleProvider;
+}
+/**
+ * Build a real {@link Gate} from fixtures — no Nest container, no database. The
+ * returned Gate behaves exactly like the production one (same hooks, same RBAC seam,
+ * same resolution order); only the wiring is in-memory.
+ */
+export declare function buildGate(options?: BuildGateOptions): Gate;
+/**
+ * Build a {@link BoundGate} for a fixture `user` directly — sugar over
+ * `buildGate(options).forUser(user)` for tests that focus on a single principal.
+ */
+export declare function buildBoundGate(user: User, options?: BuildGateOptions): BoundGate;
+/**
+ * Accept either a {@link Gate} (then `user` is required) or an already-bound
+ * {@link BoundGate}. Lets the assertion helpers serve both styles.
+ */
+export type GateLike = Gate | BoundGate;
+/** A thrown assertion failure from {@link expectCan}/{@link expectCannot}. */
+export declare class AuthzAssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert the user CAN perform `ability` (optionally on `resource`). Resolves when
+ * allowed; throws {@link AuthzAssertionError} when denied. Works with either a
+ * {@link Gate} (+ `user`) or a {@link BoundGate} (pass `undefined` for `user`).
+ *
+ * @example await expectCan(gate, { id: 1 }, 'update', post);
+ * @example await expectCan(boundGate, undefined, 'create');
+ */
+export declare function expectCan(gate: GateLike, user: User, ability: string, resource?: Resource): Promise<void>;
+/**
+ * Assert the user CANNOT perform `ability` (optionally on `resource`). Resolves when
+ * denied; throws {@link AuthzAssertionError} when allowed. An unresolved ability
+ * (no policy/gate) counts as "cannot" — the deny-by-default outcome a caller wants
+ * to assert — so this never leaks the underlying `AbilityNotResolvedException`.
+ */
+export declare function expectCannot(gate: GateLike, user: User, ability: string, resource?: Resource): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,KAAK,SAAS,EACd,SAAS,EACT,IAAI,EACJ,KAAK,MAAM,EACX,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAEnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,IAAI,EACV,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,wFAAwF;IACxF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACpF;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,8FAA8F;IAC9F,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAwB9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAEpF;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC;AAMxC,8EAA8E;AAC9E,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/index.js

@@ -0,0 +1,98 @@
+/**
+ * Test helpers for `@dudousxd/nestjs-authz`.
+ *
+ * Build a real {@link Gate} (no Nest module, no DB) from fixture policies, ad-hoc
+ * gates, hooks, and an optional in-memory permission/role provider — then assert
+ * verdicts with {@link expectCan}/{@link expectCannot}. The helpers exercise the
+ * SAME resolution path the production Gate uses, so a policy that passes here passes
+ * in the app.
+ *
+ * @example
+ * ```ts
+ * const gate = buildGate({ policies: [new PostPolicy()] });
+ * await expectCan(gate, { id: 1 }, 'update', new Post(1, 1));
+ * await expectCannot(gate, { id: 2 }, 'update', new Post(1, 1));
+ * ```
+ *
+ * @module
+ */
+import { BoundGate, Gate, PolicyRegistry, } from '@dudousxd/nestjs-authz';
+export { FakePermissionProvider, FakeRoleProvider, } from './fakes.js';
+/**
+ * Build a real {@link Gate} from fixtures — no Nest container, no database. The
+ * returned Gate behaves exactly like the production one (same hooks, same RBAC seam,
+ * same resolution order); only the wiring is in-memory.
+ */
+export function buildGate(options = {}) {
+    const registry = new PolicyRegistry();
+    for (const policy of options.policies ?? [])
+        registry.register(policy);
+    const moduleOptions = {
+        ...(options.superAdmin ? { superAdmin: options.superAdmin } : {}),
+        ...(options.after ? { after: options.after } : {}),
+        ...(options.resolveRoles ? { resolveRoles: options.resolveRoles } : {}),
+    };
+    // Ctor: (policies, options, context?, moduleRef?, permissionProvider?, roleProvider?).
+    const gate = new Gate(registry, moduleOptions, undefined, undefined, options.permissionProvider, options.roleProvider);
+    for (const [ability, fn] of Object.entries(options.gates ?? {})) {
+        gate.define(ability, fn);
+    }
+    return gate;
+}
+/**
+ * Build a {@link BoundGate} for a fixture `user` directly — sugar over
+ * `buildGate(options).forUser(user)` for tests that focus on a single principal.
+ */
+export function buildBoundGate(user, options = {}) {
+    return buildGate(options).forUser(user);
+}
+function bind(gate, user) {
+    return gate instanceof BoundGate ? gate : gate.forUser(user);
+}
+/** A thrown assertion failure from {@link expectCan}/{@link expectCannot}. */
+export class AuthzAssertionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthzAssertionError';
+    }
+}
+/**
+ * Assert the user CAN perform `ability` (optionally on `resource`). Resolves when
+ * allowed; throws {@link AuthzAssertionError} when denied. Works with either a
+ * {@link Gate} (+ `user`) or a {@link BoundGate} (pass `undefined` for `user`).
+ *
+ * @example await expectCan(gate, { id: 1 }, 'update', post);
+ * @example await expectCan(boundGate, undefined, 'create');
+ */
+export async function expectCan(gate, user, ability, resource) {
+    const allowed = await bind(gate, user).allows(ability, resource);
+    if (!allowed) {
+        throw new AuthzAssertionError(`Expected user to be able to "${ability}"${describeResource(resource)}, but it was DENIED.`);
+    }
+}
+/**
+ * Assert the user CANNOT perform `ability` (optionally on `resource`). Resolves when
+ * denied; throws {@link AuthzAssertionError} when allowed. An unresolved ability
+ * (no policy/gate) counts as "cannot" — the deny-by-default outcome a caller wants
+ * to assert — so this never leaks the underlying `AbilityNotResolvedException`.
+ */
+export async function expectCannot(gate, user, ability, resource) {
+    let allowed;
+    try {
+        allowed = await bind(gate, user).allows(ability, resource);
+    }
+    catch {
+        // Unresolved/ambiguous ability → effectively "cannot" (deny by default).
+        return;
+    }
+    if (allowed) {
+        throw new AuthzAssertionError(`Expected user to be UNABLE to "${ability}"${describeResource(resource)}, but it was ALLOWED.`);
+    }
+}
+function describeResource(resource) {
+    if (resource === undefined)
+        return '';
+    const name = resource.constructor?.name;
+    return name && name !== 'Object' ? ` on a ${name}` : ' on the resource';
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@dudousxd/nestjs-authz-testing",
+  "version": "0.1.0",
+  "description": "Test helpers for @dudousxd/nestjs-authz — build a Gate/BoundGate from fixture users & policies and assert with expectCan/expectCannot.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/nestjs-authz.git",
+    "directory": "packages/testing"
+  },
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "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"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@dudousxd/nestjs-authz": ">=0.5.0",
+    "reflect-metadata": ">=0.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0",
+    "@dudousxd/nestjs-authz": "^0.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "nestjs",
+    "authorization",
+    "authz",
+    "testing",
+    "gate",
+    "policy",
+    "fixtures"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}