feat(testfile-directives): Add per-test file directives to control runtime permissions and flags (Deno, Node, Bun, Chromium)

readme.md

@@ -442,6 +442,70 @@ const s3 = await tapNodeTools.createSmarts3();
 await s3.stop();
 ```
 
+## Test File Directives
+
+Control runtime behavior directly from your test files using special comment directives at the top of the file. Directives must appear before any `import` statements.
+
+### Deno Permissions
+
+By default, Deno tests run with `--allow-read`, `--allow-env`, `--allow-net`, `--allow-write`, `--allow-sys`, and `--allow-import`. Add directives to request additional permissions:
+
+```typescript
+// tstest:deno:allowAll
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+
+tap.test('test with full Deno permissions', async () => {
+  // Runs with --allow-all (e.g., for FFI, subprocess spawning, etc.)
+});
+
+export default tap.start();
+```
+
+### Available Directives
+
+| Directive | Effect |
+|---|---|
+| `// tstest:deno:allowAll` | Grants all Deno permissions (`--allow-all`) |
+| `// tstest:deno:allowRun` | Adds `--allow-run` for subprocess spawning |
+| `// tstest:deno:allowFfi` | Adds `--allow-ffi` for native library calls |
+| `// tstest:deno:allowHrtime` | Adds `--allow-hrtime` for high-res timers |
+| `// tstest:deno:flag:--unstable-ffi` | Passes any arbitrary Deno flag |
+| `// tstest:node:flag:--max-old-space-size=4096` | Passes flags to Node.js |
+| `// tstest:bun:flag:--smol` | Passes flags to Bun |
+
+### Multiple Directives
+
+Combine as many directives as needed:
+
+```typescript
+// tstest:deno:allowRun
+// tstest:deno:allowFfi
+// tstest:deno:flag:--unstable-ffi
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+
+tap.test('test with Rust FFI', async () => {
+  // Has --allow-run, --allow-ffi, and --unstable-ffi in addition to defaults
+});
+
+export default tap.start();
+```
+
+### Shared Directives via 00init.ts
+
+Directives in a `00init.ts` file apply to all test files in that directory. Test file directives are merged with (and extend) init file directives.
+
+```typescript
+// test/00init.ts
+// tstest:deno:allowRun
+```
+
+```typescript
+// test/test.mytest.deno.ts
+// tstest:deno:allowFfi
+// Both --allow-run (from 00init.ts) and --allow-ffi are active
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+```
+
 ## Advanced Features
 
 ### Watch Mode