{"owner":"denoland","repo":"deno","hasSkills":true,"totalSkillsCount":6,"totalTokensCount":7077,"categories":["claude-rule","copilot-instructions","mcp-config","marketplace","plugin-manifest","cursor-rule"],"hasMcp":true,"mcpConfig":{"mcpServers":{"deno":{"command":"npx","args":["-y","@modelcontextprotocol/server-deno"]}}},"found":["CLAUDE.md",".github/copilot-instructions.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json",".cursorrules (deno-integration-techniques-cursorrules-prompt-fil.mdc)"],"skills":{"CLAUDE.md":"# Deno Development Guide\n\n## Table of Contents\n\n- [Git workflow](#git-workflow)\n- [High Level Overview](#high-level-overview)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Testing](#testing)\n- [Development Workflows](#development-workflows)\n- [Debugging](#debugging)\n- [Codebase Navigation](#codebase-navigation)\n- [Troubleshooting](#troubleshooting)\n\n## Git workflow\n\nDeno uses a GH based standard git workflow. The main branch is `main`. All\ndevelopment happens in feature branches, which are then merged into `main` via\npull requests.\n\nWhen the feature is finished and ready to for review, follow these steps:\n\n- Create a new git branch, if you haven't already, with a descriptive name\n (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).\n- Commit your changes with clear and descriptive commit messages.\n- Push your branch to the remote repository.\n- Open a pull request (PR) against the `main` branch on GitHub.\n- Before committing, make sure `tools/format.js` is run to format your code\n- Before committing, if only non-Rust was changed, make sure to run\n `tools/lint.js --js` and fix any lint errors before committing\n- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint\n errors before committing\n- In the PR description, provide a clear summary of the changes you made, why\n they were necessary, and any relevant context or links to related issues.\n- When pushing updates to the PR, make sure to never force push. Create as many\n commits as you need, all of them get squashed when the PR is merged, so there\n is no need to rewrite history. This also allows reviewers to see the\n incremental changes you made in response to feedback.\n- Keep your changes minimal, don't do drive-by changes in a PR. If you need to\n make a change that is not directly related to the PR, create a separate PR for\n it. This keeps the review process focused and efficient.\n\n## High Level Overview\n\nThe user visible interface and high level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all \"extensions\" (native functionality exposed to JavaScript). The\nextensions themselves are in the `ext/` directory, and provide system access to\nJavaScript – for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` - User-facing CLI implementation, subcommands, and tools\n- `runtime/` - JavaScript runtime assembly and integration\n- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)\n- `tests/specs/` - Integration tests (spec tests)\n- `tests/unit/` - Unit tests\n- `tests/testdata/` - Test fixtures and data files\n\n## Quick Start\n\nBefore building, install the required prerequisites (Rust, native compilers,\ncmake, protobuf, etc.) and clone with `--recurse-submodules` as described in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Building Deno\n\nTo compile after making changes:\n\n```bash\ncargo build\n```\n\nFor faster iteration during development (less optimization):\n\n```bash\ncargo build --bin deno\n```\n\nExecute your development build:\n\n```bash\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n### Running with your changes\n\n```bash\n# Run a local file\n./target/debug/deno run path/to/file.ts\n\n# Run with permissions\n./target/debug/deno run --allow-net --allow-read script.ts\n\n# Run the REPL\n./target/debug/deno\n```\n\n## Commands\n\n### Compilation and Checks\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Check specific package\ncargo check -p deno_runtime\n\n# Build release version (slow, optimized)\ncargo build --release\n```\n\n### Code Quality\n\n```bash\n# Lint the code\n./tools/lint.js\n\n# Format the code\n./tools/format.js\n\n# Both lint and format\n./tools/format.js && ./tools/lint.js\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests (this takes a while)\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Unit Tests (`tests/unit/`)\n\nJavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run\nthem via `cargo test`:\n\n```bash\n# Run all unit tests in a specific file\ncargo test unit::webcrypto_test\n\n# Run all unit tests\ncargo test unit::\n\n# Run Node.js compatibility unit tests (tests/unit_node/)\ncargo test unit_node::crypto_test\n\n# Run all Node.js compat unit tests\ncargo test unit_node::\n```\n\nDo NOT run these directly with `./target/debug/deno test` — they depend on the\ncargo test harness for correct setup.\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command\n execution and output validation\n- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime\n APIs\n- **Integration tests** (`tests/integration/`) - Additional integration tests\n- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance\n\n## \"spec\" tests\n\nThe main form of integration test in deno is the \"spec\" test. These tests can be\nfound in `tests/specs`. The idea is that you have a `__test__.jsonc` file that\nlays out one or more tests, where a test is a CLI command to execute and the\noutput is captured and asserted against.\n\nThe name of the test comes from the directory the `__test__.jsonc` appears in.\n\n### Creating a New Spec Test\n\n1. Create a directory in `tests/specs/` with a descriptive name\n2. Add a `__test__.jsonc` file describing your test steps\n3. Add any input files needed for the test\n4. Add `.out` files for expected output (or inline in `__test__.jsonc`)\n\nExample:\n\n```\ntests/specs/my_feature/\n __test__.jsonc\n main.ts\n expected.out\n```\n\n### `__test__.jsonc` schema\n\nThe schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.\n\nExample test structure:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n },\n \"with_flag\": {\n \"steps\": [\n {\n \"args\": \"run --allow-net main.ts\",\n \"output\": \"[WILDCARD]success[WILDCARD]\"\n }\n ]\n }\n }\n}\n```\n\n### Output assertions\n\nThe expected output can be inline in a `__test__.jsonc` file or in a file ending\nwith `.out`. For a given test step, the `output` field tells you either the\ninline expectation or the name of the file containing the **expectation**. The\nexpectation uses a small matching language to support wildcards and things like\nthat. A literal character means you expect that exact character, so `Foo bar`\nwould expect the output to be \"Foo bar\". Then there are things with special\nmeanings:\n\n- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this\n can cross newlines\n- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line\n- `[WILDCHAR]` - match the next character\n- `[WILDCHARS(5)]` - match any of the next 5 characters\n- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match\n the lines in any order (useful for non-deterministic output)\n- `[# example]` - line comments start with `[#` and end with `]`\n\nExample `.out` file:\n\n```\nCheck file://[WILDCARD]/main.ts\n[WILDCARD]\nSuccessfully compiled [WILDLINE]\n```\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\nExample files to reference:\n\n- Simple command: `cli/tools/fmt.rs`\n- Complex command: `cli/tools/test/`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//` (e.g., `ext/fs/`, `ext/net/`)\n2. Rust code provides the ops (operations) exposed to JavaScript\n3. JavaScript code in the extension provides the higher-level APIs\n4. Update `runtime/worker.rs` to register the extension if new\n5. Add tests in the extension's directory\n\n### Updating Dependencies\n\n```bash\n# Update Cargo dependencies\ncargo update\n\n# Update to latest compatible versions\ncargo upgrade # Requires cargo-edit: cargo install cargo-edit\n\n# Check for outdated dependencies\ncargo outdated # Requires cargo-outdated\n```\n\n## Debugging\n\n### Debugging Rust Code\n\nUse `lldb` directly:\n\n```bash\nlldb ./target/debug/deno\n(lldb) run eval 'console.log(\"test\")'\n```\n\n### Debugging JavaScript Runtime Issues\n\nUse println debugging.\n\n### Verbose Logging\n\n```bash\n# Set Rust log level\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Specific module logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n```\n\n### Debug Prints\n\nIn Rust code:\n\n```rust\neprintln!(\"Debug: {:?}\", some_variable);\ndbg!(some_variable);\n```\n\nIn JavaScript/TypeScript code:\n\n```javascript\nconsole.log(\"Debug:\", value);\n```\n\n## Codebase Navigation\n\n### Key Files to Understand First\n\n1. `cli/main.rs` - Entry point, command routing\n2. `cli/args/flags.rs` - CLI flag parsing and structure\n3. `runtime/worker.rs` - Worker/runtime initialization\n4. `runtime/permissions.rs` - Permission system\n5. `cli/module_loader.rs` - Module loading and resolution\n\n### Common Patterns\n\n- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** - Collections of ops and JS code providing functionality\n- **Workers** - JavaScript execution contexts (main worker, web workers)\n- **Resources** - Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n### Finding Examples\n\n- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`\n- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,\n `ext/fs/lib.rs`)\n- Need to add a tool? Reference existing tools in `cli/tools/`\n\n## Troubleshooting\n\n### Build Failures\n\n**Error: linking with `cc` failed**\n\n- Make sure you have the required system dependencies\n- On macOS: `xcode-select --install`\n- On Linux: Install `build-essential` or equivalent\n\n**Error: failed to download dependencies**\n\n- Check internet connection\n- Try `cargo clean` then rebuild\n- Check if behind a proxy, configure cargo accordingly\n\nFor other build failures (missing `cmake`, `stdarg.h`, etc.), see the full\nprerequisites in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Test Failures\n\n**Spec test failures**\n\n- Check the test output carefully for differences\n- Update `.out` files if output format changed intentionally\n- Use `[WILDCARD]` for non-deterministic parts of output\n\n**Flaky tests**\n\n- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output\n- Check for race conditions in test code\n- May need to increase timeouts or add retries\n\n### Permission Issues\n\n**Tests failing with permission errors**\n\n- Ensure test files have correct permissions\n- Check that test setup properly grants necessary permissions\n\n### Performance Issues\n\n**Slow compile times**\n\n- Use `cargo check` instead of `cargo build` when possible\n- Use `--bin deno` to build only the main binary\n- Use `sccache` or `mold` linker for faster builds\n- Consider using `cargo-watch` for incremental builds\n\n### Runtime Debugging\n\n**Crashes or panics**\n\n- Run with `RUST_BACKTRACE=1` for full backtrace\n- Use `RUST_BACKTRACE=full` for even more detail\n- Check for unwrap() calls that might panic\n\n**Unexpected behavior**\n\n- Add debug prints liberally\n- Check permission grants - many features require explicit permissions\n\n### Getting Help\n\n- Check existing issues on GitHub\n- Look at recent PRs for similar changes\n- Review the Discord community for discussions\n- When in doubt, ask! The maintainers are helpful\n",".github/copilot-instructions.md":"# Deno Development Guide for GitHub Copilot\n\n## Network Access\n\nThe development tools in this repository need network access to function. When\nrunning `tools/format.js` or `tools/lint.js`, ensure the following domains are\nreachable:\n\n- `https://jsr.io` — Deno's package registry, used for `@std/*` imports\n- `https://dprint.dev` and `https://plugins.dprint.dev` — the formatter\n (`tools/format.js`) runs `npm:dprint` which downloads WASM plugins from\n `plugins.dprint.dev`\n\nIf you are running in a sandboxed environment, you must allowlist these domains\nor the tools will fail with network errors.\n\n## High Level Overview\n\nThe user-visible interface and high-level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all of the \"extensions\" (native functionality exposed to JavaScript).\nThe extensions themselves are in the `ext/` directory, and provide system access\nto JavaScript — for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` — User-facing CLI implementation, subcommands, and tools\n- `runtime/` — JavaScript runtime assembly and integration\n- `ext/` — Extensions providing native functionality to JS (fs, net, etc.)\n- `libs/` — Shared Rust crates (core, resolver, npm, node_resolver, serde_v8,\n etc.)\n- `tests/specs/` — Integration tests (spec tests)\n- `tests/unit/` — Unit tests\n- `tests/testdata/` — Test fixtures and data files\n\n### Key Files to Understand First\n\n1. `cli/main.rs` — Entry point, command routing\n2. `cli/args/flags.rs` — CLI flag parsing and structure\n3. `runtime/worker.rs` — Worker/runtime initialization\n4. `runtime/permissions.rs` — Permission system\n5. `cli/module_loader.rs` — Module loading and resolution\n\n### Common Patterns\n\n- **Ops** — Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** — Collections of ops and JS code providing functionality\n- **Workers** — JavaScript execution contexts (main worker, web workers)\n- **Resources** — Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n## Building\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Build debug binary\ncargo build --bin deno\n\n# Build release version (slow, optimized)\ncargo build --release\n\n# Run the dev build\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n## Code Quality\n\nBefore committing, always run the formatter and linter:\n\n```bash\n# Format all code (uses dprint under the hood)\n./tools/format.js\n\n# Lint all code (JS + Rust via clippy)\n./tools/lint.js\n\n# Lint only JS/TS (faster, skips clippy)\n./tools/lint.js --js\n\n# Lint only Rust\n./tools/lint.js --rs\n```\n\nThe formatter (`tools/format.js`) runs `dprint` via `npm:dprint@0.47.2`. It\nformats TypeScript, JavaScript, JSON, Markdown, YAML, and Rust (via `rustfmt`).\nConfiguration is in `.dprint.json`.\n\nThe linter (`tools/lint.js`) runs `deno lint` for JS/TS and `cargo clippy` for\nRust.\n\n## Testing\n\n```bash\n# Run all tests\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) — Main integration tests\n- **Unit tests** — Inline with source code in each module\n- **Integration tests** (`tests/integration/`) — Additional integration tests\n- **WPT** (`tests/wpt/`) — Web Platform Tests for web standards compliance\n\n### Spec Tests\n\nThe main form of integration test is the \"spec\" test in `tests/specs/`. Each\ntest has a `__test__.jsonc` file describing CLI commands to run and expected\noutput. The schema is in `tests/specs/schema.json`.\n\nExample `__test__.jsonc`:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n }\n }\n}\n```\n\nOutput assertions support wildcards:\n\n- `[WILDCARD]` — matches 0 or more characters (crosses newlines)\n- `[WILDLINE]` — matches to end of line\n- `[WILDCHAR]` — matches one character\n- `[WILDCHARS(N)]` — matches N characters\n- `[UNORDERED_START]` / `[UNORDERED_END]` — matches lines in any order\n\n## Git Workflow and Pull Requests\n\n### PR Title Linting\n\nPR titles are validated by CI (see `.github/workflows/pr.ts`). The title must\nfollow [Conventional Commits](https://www.conventionalcommits.org) and start\nwith one of these prefixes:\n\n- `feat:` — new features\n- `fix:` — bug fixes\n- `chore:` — maintenance tasks\n- `perf:` — performance improvements\n- `ci:` — CI changes\n- `cleanup:` — code cleanup\n- `docs:` — documentation\n- `bench:` — benchmarks\n- `build:` — build system changes\n- `refactor:` — refactoring\n- `test:` — test changes\n- `Revert` — reverting a previous commit\n- `Reland` — relanding a reverted commit\n- `BREAKING` — breaking changes\n\nAdditionally, deno_core/v8 upgrades must NOT use `chore:` — use `feat:`, `fix:`,\nor `refactor:` instead, with a title describing the actual change.\n\nRelease PRs (titles matching `X.Y.Z`) are also valid.\n\nThe validation script is at `tools/verify_pr_title.js`.\n\n### Workflow Rules\n\n- Create feature branches with descriptive names\n- Commit with clear, descriptive messages\n- Never force push — all commits are squashed on merge\n- Keep changes minimal and focused; avoid drive-by changes\n- Before committing, run `tools/format.js` and `tools/lint.js`\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//`\n2. Rust code provides the ops exposed to JavaScript\n3. JavaScript code in the extension provides higher-level APIs\n4. Update `runtime/worker.rs` to register a new extension\n5. Add tests in the extension's directory\n\n## Debugging\n\n```bash\n# Verbose logging\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Module-specific logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n\n# Full backtrace on panic\nRUST_BACKTRACE=1 ./target/debug/deno run script.ts\n\n# V8 inspector\n./target/debug/deno run --inspect-brk script.ts\n```\n\nIn Rust code: `eprintln!(\"Debug: {:?}\", var);` or `dbg!(var);`\n\n## Pull Request Reviews\n\n### Before commenting, verify your claims\n\n- If you claim something is missing (a stub, a test, error handling), search the\n full diff AND the existing codebase before commenting. Do not flag missing\n code that already exists elsewhere in the PR or the repository.\n- If you suggest a code change, verify it compiles and does not break the\n intended behavior. Do not suggest fixes that contradict the PR's stated goal.\n- Do not duplicate your own comments. If you already flagged an issue, do not\n post a second comment about the same thing.\n\n### Focus on high-value issues\n\nPrioritize these (in order):\n\n1. **Correctness bugs** — logic errors, race conditions (e.g. spurious wakeups\n on `Condvar`), use-after-free, null derefs\n2. **Public API leaks** — internal fields accidentally exposed in public return\n types\n3. **Security** — unsafe blocks with incorrect safety invariants, unsanitized\n inputs at system boundaries\n4. **Missing error handling** — errors silently swallowed where they should\n propagate, or propagated where they should be caught\n\nDo NOT comment on:\n\n- Style preferences already enforced by the project's formatter (dprint) and\n linter (clippy + deno lint)\n- Suggesting longer timeouts or shorter delays in tests without evidence of\n flakiness\n- Minor documentation wording unless it is actively misleading\n- Hypothetical edge cases that cannot realistically occur (e.g. a process having\n > 256 direct children)\n\n### Understand the runtime model before suggesting fixes\n\nDeno embeds V8 and uses a single-threaded async event loop (tokio). Code that\nlooks like a busy-spin may actually be required because:\n\n- `poll_sessions(None)` in the inspector drives async I/O — parking the thread\n prevents WebSocket close frames from being processed, causing deadlocks\n- The event loop must keep running for futures to make progress; blocking the\n main thread stops the I/O reactor\n- Some loops intentionally spin to allow the waker/poller to process events each\n iteration\n\nBefore suggesting `sleep`, `park`, or backoff in a polling loop, check whether\nthe loop body drives async I/O that would stall if the thread were blocked.\n\n### Trace through the actual code path, not just the function signature\n\nA common review mistake is looking at a function's local behavior without\ntracing its callers and the runtime context. For example:\n\n- A function that \"doesn't check field X\" may not need to because callers\n guarantee X is consumed before the check runs (e.g., `handshake` is always\n `take()`n at the top of `poll_sessions` before any session-count checks)\n- A heuristic that \"doesn't handle case Y\" may already handle it through a\n different code path (e.g., dotenv comment detection via `#` prefix check\n happens before the inner-quote fallback is reached)\n\n### Don't suggest fixes that introduce circular dependencies\n\nIn parsers and state machines, be careful not to suggest fixes that require\nknowing the answer to the question being solved. For example, suggesting \"detect\nwhere the comment starts before matching quotes\" is circular when the quote\nmatching is what determines where the value (and thus the comment) begins.\n\n### Verify suggestions against existing tests\n\nBefore suggesting a change, check whether the codebase already has test coverage\nfor the case in question. The `test_valid_env` test in `libs/dotenv/lib.rs`\ncovers many edge cases including inline comments with quotes\n(`EDGE_CASE_INLINE_COMMENTS`). Running existing tests before and after a\nsuggested change catches regressions.\n\n### Match existing patterns in the codebase\n\nWhen suggesting changes to a function, look for similar functions nearby that\nsolve analogous problems. If the existing pattern (e.g., `wait_for_session`)\nuses a specific flag/mechanism, understand why before suggesting a different\napproach for a similar function (e.g., `wait_for_sessions_disconnect`). The\ndifference may be intentional.\n\n### Deno-specific conventions\n\n- Ops use the `#[op2]` macro. Fast ops use `#[op2(fast)]`.\n- Internal symbols in JS (`ext/process/40_process.js`, `ext/node/polyfills/`)\n use the `k` prefix convention: `kIpc`, `kSerialization`, `kInputOption`. Flag\n deviations.\n- Node.js compatibility code is in `ext/node/polyfills/`. When reviewing these\n files, check behavior against Node.js docs, not just Deno conventions. Some\n patterns (like synchronous `throw` in `spawn()` for EPERM but async error\n event for ENOENT) are intentional Node.js compatibility.\n\n### When suggesting error handling changes\n\n- Check whether the function's callers expect the error to propagate or be\n swallowed. Do not suggest propagating errors in paths that are intentionally\n best-effort (e.g. killing already-exited processes).\n- When suggesting a specific error variant or code change, verify the types\n actually match. For example, `Option::or_else` takes `FnOnce() -> Option`,\n not `FnOnce(E) -> ...`.\n- If a Rust function returns `Result` and an `Option` is needed, use `.ok()`\n before `.or_else()` or `.unwrap_or()`.\n\n### Platform-specific code\n\n- `#[cfg(unix)]` code that calls `find_descendant_pids` or similar must have\n stubs for non-Linux/non-macOS Unix targets. Check that\n `#[cfg(all(unix, not(target_os = \"linux\"), not(target_os = \"macos\")))]` stubs\n exist before flagging missing platform support.\n- Windows `unsafe` blocks using `windows_sys` are common for process management.\n Verify handle cleanup (`CloseHandle`) but do not flag the `unsafe` usage\n itself.\n\n## Troubleshooting\n\n- **Slow compile times**: Use `cargo check`, `--bin deno`, or `sccache`\n- **Build failures on macOS**: Run `xcode-select --install`\n- **Build failures on Linux**: Install `build-essential`\n- **Spec test failures**: Check output diffs, use `[WILDCARD]` for\n non-deterministic parts\n- **Permission errors**: Ensure test files have correct permissions\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/plugin.json)",".cursorrules (deno-integration-techniques-cursorrules-prompt-fil.mdc)":"---\ndescription: \"Cursor rules for Deno development with integration techniques.\"\nglobs: **/*\nalwaysApply: false\n---\nThis project contains automation scripts and workflows for the @findhow packages, based on the original Deno automation repository. The goal is to provide consistent and efficient automation for the @findhow ecosystem.\n\nThe purpose of this project is to refactor and adapt the automation scripts from [denoland/automation](https://github.com/denoland/automation) for use with the configured @findhow package repositories.\n\nWhen working on this project, Cursor AI should:\n\nWhen making changes:\n\nWhen updating documentation:\n\nWhen creating or modifying automation scripts:\n\nRemember to thoroughly test all modifications to ensure they work correctly with the @findhow ecosystem before merging changes into the main branch.\n"},"files":{"CLAUDE.md":"# Deno Development Guide\n\n## Table of Contents\n\n- [Git workflow](#git-workflow)\n- [High Level Overview](#high-level-overview)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Testing](#testing)\n- [Development Workflows](#development-workflows)\n- [Debugging](#debugging)\n- [Codebase Navigation](#codebase-navigation)\n- [Troubleshooting](#troubleshooting)\n\n## Git workflow\n\nDeno uses a GH based standard git workflow. The main branch is `main`. All\ndevelopment happens in feature branches, which are then merged into `main` via\npull requests.\n\nWhen the feature is finished and ready to for review, follow these steps:\n\n- Create a new git branch, if you haven't already, with a descriptive name\n (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).\n- Commit your changes with clear and descriptive commit messages.\n- Push your branch to the remote repository.\n- Open a pull request (PR) against the `main` branch on GitHub.\n- Before committing, make sure `tools/format.js` is run to format your code\n- Before committing, if only non-Rust was changed, make sure to run\n `tools/lint.js --js` and fix any lint errors before committing\n- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint\n errors before committing\n- In the PR description, provide a clear summary of the changes you made, why\n they were necessary, and any relevant context or links to related issues.\n- When pushing updates to the PR, make sure to never force push. Create as many\n commits as you need, all of them get squashed when the PR is merged, so there\n is no need to rewrite history. This also allows reviewers to see the\n incremental changes you made in response to feedback.\n- Keep your changes minimal, don't do drive-by changes in a PR. If you need to\n make a change that is not directly related to the PR, create a separate PR for\n it. This keeps the review process focused and efficient.\n\n## High Level Overview\n\nThe user visible interface and high level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all \"extensions\" (native functionality exposed to JavaScript). The\nextensions themselves are in the `ext/` directory, and provide system access to\nJavaScript – for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` - User-facing CLI implementation, subcommands, and tools\n- `runtime/` - JavaScript runtime assembly and integration\n- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)\n- `tests/specs/` - Integration tests (spec tests)\n- `tests/unit/` - Unit tests\n- `tests/testdata/` - Test fixtures and data files\n\n## Quick Start\n\nBefore building, install the required prerequisites (Rust, native compilers,\ncmake, protobuf, etc.) and clone with `--recurse-submodules` as described in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Building Deno\n\nTo compile after making changes:\n\n```bash\ncargo build\n```\n\nFor faster iteration during development (less optimization):\n\n```bash\ncargo build --bin deno\n```\n\nExecute your development build:\n\n```bash\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n### Running with your changes\n\n```bash\n# Run a local file\n./target/debug/deno run path/to/file.ts\n\n# Run with permissions\n./target/debug/deno run --allow-net --allow-read script.ts\n\n# Run the REPL\n./target/debug/deno\n```\n\n## Commands\n\n### Compilation and Checks\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Check specific package\ncargo check -p deno_runtime\n\n# Build release version (slow, optimized)\ncargo build --release\n```\n\n### Code Quality\n\n```bash\n# Lint the code\n./tools/lint.js\n\n# Format the code\n./tools/format.js\n\n# Both lint and format\n./tools/format.js && ./tools/lint.js\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests (this takes a while)\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Unit Tests (`tests/unit/`)\n\nJavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run\nthem via `cargo test`:\n\n```bash\n# Run all unit tests in a specific file\ncargo test unit::webcrypto_test\n\n# Run all unit tests\ncargo test unit::\n\n# Run Node.js compatibility unit tests (tests/unit_node/)\ncargo test unit_node::crypto_test\n\n# Run all Node.js compat unit tests\ncargo test unit_node::\n```\n\nDo NOT run these directly with `./target/debug/deno test` — they depend on the\ncargo test harness for correct setup.\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command\n execution and output validation\n- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime\n APIs\n- **Integration tests** (`tests/integration/`) - Additional integration tests\n- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance\n\n## \"spec\" tests\n\nThe main form of integration test in deno is the \"spec\" test. These tests can be\nfound in `tests/specs`. The idea is that you have a `__test__.jsonc` file that\nlays out one or more tests, where a test is a CLI command to execute and the\noutput is captured and asserted against.\n\nThe name of the test comes from the directory the `__test__.jsonc` appears in.\n\n### Creating a New Spec Test\n\n1. Create a directory in `tests/specs/` with a descriptive name\n2. Add a `__test__.jsonc` file describing your test steps\n3. Add any input files needed for the test\n4. Add `.out` files for expected output (or inline in `__test__.jsonc`)\n\nExample:\n\n```\ntests/specs/my_feature/\n __test__.jsonc\n main.ts\n expected.out\n```\n\n### `__test__.jsonc` schema\n\nThe schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.\n\nExample test structure:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n },\n \"with_flag\": {\n \"steps\": [\n {\n \"args\": \"run --allow-net main.ts\",\n \"output\": \"[WILDCARD]success[WILDCARD]\"\n }\n ]\n }\n }\n}\n```\n\n### Output assertions\n\nThe expected output can be inline in a `__test__.jsonc` file or in a file ending\nwith `.out`. For a given test step, the `output` field tells you either the\ninline expectation or the name of the file containing the **expectation**. The\nexpectation uses a small matching language to support wildcards and things like\nthat. A literal character means you expect that exact character, so `Foo bar`\nwould expect the output to be \"Foo bar\". Then there are things with special\nmeanings:\n\n- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this\n can cross newlines\n- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line\n- `[WILDCHAR]` - match the next character\n- `[WILDCHARS(5)]` - match any of the next 5 characters\n- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match\n the lines in any order (useful for non-deterministic output)\n- `[# example]` - line comments start with `[#` and end with `]`\n\nExample `.out` file:\n\n```\nCheck file://[WILDCARD]/main.ts\n[WILDCARD]\nSuccessfully compiled [WILDLINE]\n```\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\nExample files to reference:\n\n- Simple command: `cli/tools/fmt.rs`\n- Complex command: `cli/tools/test/`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//` (e.g., `ext/fs/`, `ext/net/`)\n2. Rust code provides the ops (operations) exposed to JavaScript\n3. JavaScript code in the extension provides the higher-level APIs\n4. Update `runtime/worker.rs` to register the extension if new\n5. Add tests in the extension's directory\n\n### Updating Dependencies\n\n```bash\n# Update Cargo dependencies\ncargo update\n\n# Update to latest compatible versions\ncargo upgrade # Requires cargo-edit: cargo install cargo-edit\n\n# Check for outdated dependencies\ncargo outdated # Requires cargo-outdated\n```\n\n## Debugging\n\n### Debugging Rust Code\n\nUse `lldb` directly:\n\n```bash\nlldb ./target/debug/deno\n(lldb) run eval 'console.log(\"test\")'\n```\n\n### Debugging JavaScript Runtime Issues\n\nUse println debugging.\n\n### Verbose Logging\n\n```bash\n# Set Rust log level\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Specific module logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n```\n\n### Debug Prints\n\nIn Rust code:\n\n```rust\neprintln!(\"Debug: {:?}\", some_variable);\ndbg!(some_variable);\n```\n\nIn JavaScript/TypeScript code:\n\n```javascript\nconsole.log(\"Debug:\", value);\n```\n\n## Codebase Navigation\n\n### Key Files to Understand First\n\n1. `cli/main.rs` - Entry point, command routing\n2. `cli/args/flags.rs` - CLI flag parsing and structure\n3. `runtime/worker.rs` - Worker/runtime initialization\n4. `runtime/permissions.rs` - Permission system\n5. `cli/module_loader.rs` - Module loading and resolution\n\n### Common Patterns\n\n- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** - Collections of ops and JS code providing functionality\n- **Workers** - JavaScript execution contexts (main worker, web workers)\n- **Resources** - Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n### Finding Examples\n\n- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`\n- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,\n `ext/fs/lib.rs`)\n- Need to add a tool? Reference existing tools in `cli/tools/`\n\n## Troubleshooting\n\n### Build Failures\n\n**Error: linking with `cc` failed**\n\n- Make sure you have the required system dependencies\n- On macOS: `xcode-select --install`\n- On Linux: Install `build-essential` or equivalent\n\n**Error: failed to download dependencies**\n\n- Check internet connection\n- Try `cargo clean` then rebuild\n- Check if behind a proxy, configure cargo accordingly\n\nFor other build failures (missing `cmake`, `stdarg.h`, etc.), see the full\nprerequisites in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Test Failures\n\n**Spec test failures**\n\n- Check the test output carefully for differences\n- Update `.out` files if output format changed intentionally\n- Use `[WILDCARD]` for non-deterministic parts of output\n\n**Flaky tests**\n\n- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output\n- Check for race conditions in test code\n- May need to increase timeouts or add retries\n\n### Permission Issues\n\n**Tests failing with permission errors**\n\n- Ensure test files have correct permissions\n- Check that test setup properly grants necessary permissions\n\n### Performance Issues\n\n**Slow compile times**\n\n- Use `cargo check` instead of `cargo build` when possible\n- Use `--bin deno` to build only the main binary\n- Use `sccache` or `mold` linker for faster builds\n- Consider using `cargo-watch` for incremental builds\n\n### Runtime Debugging\n\n**Crashes or panics**\n\n- Run with `RUST_BACKTRACE=1` for full backtrace\n- Use `RUST_BACKTRACE=full` for even more detail\n- Check for unwrap() calls that might panic\n\n**Unexpected behavior**\n\n- Add debug prints liberally\n- Check permission grants - many features require explicit permissions\n\n### Getting Help\n\n- Check existing issues on GitHub\n- Look at recent PRs for similar changes\n- Review the Discord community for discussions\n- When in doubt, ask! The maintainers are helpful\n",".github/copilot-instructions.md":"# Deno Development Guide for GitHub Copilot\n\n## Network Access\n\nThe development tools in this repository need network access to function. When\nrunning `tools/format.js` or `tools/lint.js`, ensure the following domains are\nreachable:\n\n- `https://jsr.io` — Deno's package registry, used for `@std/*` imports\n- `https://dprint.dev` and `https://plugins.dprint.dev` — the formatter\n (`tools/format.js`) runs `npm:dprint` which downloads WASM plugins from\n `plugins.dprint.dev`\n\nIf you are running in a sandboxed environment, you must allowlist these domains\nor the tools will fail with network errors.\n\n## High Level Overview\n\nThe user-visible interface and high-level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all of the \"extensions\" (native functionality exposed to JavaScript).\nThe extensions themselves are in the `ext/` directory, and provide system access\nto JavaScript — for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` — User-facing CLI implementation, subcommands, and tools\n- `runtime/` — JavaScript runtime assembly and integration\n- `ext/` — Extensions providing native functionality to JS (fs, net, etc.)\n- `libs/` — Shared Rust crates (core, resolver, npm, node_resolver, serde_v8,\n etc.)\n- `tests/specs/` — Integration tests (spec tests)\n- `tests/unit/` — Unit tests\n- `tests/testdata/` — Test fixtures and data files\n\n### Key Files to Understand First\n\n1. `cli/main.rs` — Entry point, command routing\n2. `cli/args/flags.rs` — CLI flag parsing and structure\n3. `runtime/worker.rs` — Worker/runtime initialization\n4. `runtime/permissions.rs` — Permission system\n5. `cli/module_loader.rs` — Module loading and resolution\n\n### Common Patterns\n\n- **Ops** — Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** — Collections of ops and JS code providing functionality\n- **Workers** — JavaScript execution contexts (main worker, web workers)\n- **Resources** — Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n## Building\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Build debug binary\ncargo build --bin deno\n\n# Build release version (slow, optimized)\ncargo build --release\n\n# Run the dev build\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n## Code Quality\n\nBefore committing, always run the formatter and linter:\n\n```bash\n# Format all code (uses dprint under the hood)\n./tools/format.js\n\n# Lint all code (JS + Rust via clippy)\n./tools/lint.js\n\n# Lint only JS/TS (faster, skips clippy)\n./tools/lint.js --js\n\n# Lint only Rust\n./tools/lint.js --rs\n```\n\nThe formatter (`tools/format.js`) runs `dprint` via `npm:dprint@0.47.2`. It\nformats TypeScript, JavaScript, JSON, Markdown, YAML, and Rust (via `rustfmt`).\nConfiguration is in `.dprint.json`.\n\nThe linter (`tools/lint.js`) runs `deno lint` for JS/TS and `cargo clippy` for\nRust.\n\n## Testing\n\n```bash\n# Run all tests\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) — Main integration tests\n- **Unit tests** — Inline with source code in each module\n- **Integration tests** (`tests/integration/`) — Additional integration tests\n- **WPT** (`tests/wpt/`) — Web Platform Tests for web standards compliance\n\n### Spec Tests\n\nThe main form of integration test is the \"spec\" test in `tests/specs/`. Each\ntest has a `__test__.jsonc` file describing CLI commands to run and expected\noutput. The schema is in `tests/specs/schema.json`.\n\nExample `__test__.jsonc`:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n }\n }\n}\n```\n\nOutput assertions support wildcards:\n\n- `[WILDCARD]` — matches 0 or more characters (crosses newlines)\n- `[WILDLINE]` — matches to end of line\n- `[WILDCHAR]` — matches one character\n- `[WILDCHARS(N)]` — matches N characters\n- `[UNORDERED_START]` / `[UNORDERED_END]` — matches lines in any order\n\n## Git Workflow and Pull Requests\n\n### PR Title Linting\n\nPR titles are validated by CI (see `.github/workflows/pr.ts`). The title must\nfollow [Conventional Commits](https://www.conventionalcommits.org) and start\nwith one of these prefixes:\n\n- `feat:` — new features\n- `fix:` — bug fixes\n- `chore:` — maintenance tasks\n- `perf:` — performance improvements\n- `ci:` — CI changes\n- `cleanup:` — code cleanup\n- `docs:` — documentation\n- `bench:` — benchmarks\n- `build:` — build system changes\n- `refactor:` — refactoring\n- `test:` — test changes\n- `Revert` — reverting a previous commit\n- `Reland` — relanding a reverted commit\n- `BREAKING` — breaking changes\n\nAdditionally, deno_core/v8 upgrades must NOT use `chore:` — use `feat:`, `fix:`,\nor `refactor:` instead, with a title describing the actual change.\n\nRelease PRs (titles matching `X.Y.Z`) are also valid.\n\nThe validation script is at `tools/verify_pr_title.js`.\n\n### Workflow Rules\n\n- Create feature branches with descriptive names\n- Commit with clear, descriptive messages\n- Never force push — all commits are squashed on merge\n- Keep changes minimal and focused; avoid drive-by changes\n- Before committing, run `tools/format.js` and `tools/lint.js`\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//`\n2. Rust code provides the ops exposed to JavaScript\n3. JavaScript code in the extension provides higher-level APIs\n4. Update `runtime/worker.rs` to register a new extension\n5. Add tests in the extension's directory\n\n## Debugging\n\n```bash\n# Verbose logging\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Module-specific logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n\n# Full backtrace on panic\nRUST_BACKTRACE=1 ./target/debug/deno run script.ts\n\n# V8 inspector\n./target/debug/deno run --inspect-brk script.ts\n```\n\nIn Rust code: `eprintln!(\"Debug: {:?}\", var);` or `dbg!(var);`\n\n## Pull Request Reviews\n\n### Before commenting, verify your claims\n\n- If you claim something is missing (a stub, a test, error handling), search the\n full diff AND the existing codebase before commenting. Do not flag missing\n code that already exists elsewhere in the PR or the repository.\n- If you suggest a code change, verify it compiles and does not break the\n intended behavior. Do not suggest fixes that contradict the PR's stated goal.\n- Do not duplicate your own comments. If you already flagged an issue, do not\n post a second comment about the same thing.\n\n### Focus on high-value issues\n\nPrioritize these (in order):\n\n1. **Correctness bugs** — logic errors, race conditions (e.g. spurious wakeups\n on `Condvar`), use-after-free, null derefs\n2. **Public API leaks** — internal fields accidentally exposed in public return\n types\n3. **Security** — unsafe blocks with incorrect safety invariants, unsanitized\n inputs at system boundaries\n4. **Missing error handling** — errors silently swallowed where they should\n propagate, or propagated where they should be caught\n\nDo NOT comment on:\n\n- Style preferences already enforced by the project's formatter (dprint) and\n linter (clippy + deno lint)\n- Suggesting longer timeouts or shorter delays in tests without evidence of\n flakiness\n- Minor documentation wording unless it is actively misleading\n- Hypothetical edge cases that cannot realistically occur (e.g. a process having\n > 256 direct children)\n\n### Understand the runtime model before suggesting fixes\n\nDeno embeds V8 and uses a single-threaded async event loop (tokio). Code that\nlooks like a busy-spin may actually be required because:\n\n- `poll_sessions(None)` in the inspector drives async I/O — parking the thread\n prevents WebSocket close frames from being processed, causing deadlocks\n- The event loop must keep running for futures to make progress; blocking the\n main thread stops the I/O reactor\n- Some loops intentionally spin to allow the waker/poller to process events each\n iteration\n\nBefore suggesting `sleep`, `park`, or backoff in a polling loop, check whether\nthe loop body drives async I/O that would stall if the thread were blocked.\n\n### Trace through the actual code path, not just the function signature\n\nA common review mistake is looking at a function's local behavior without\ntracing its callers and the runtime context. For example:\n\n- A function that \"doesn't check field X\" may not need to because callers\n guarantee X is consumed before the check runs (e.g., `handshake` is always\n `take()`n at the top of `poll_sessions` before any session-count checks)\n- A heuristic that \"doesn't handle case Y\" may already handle it through a\n different code path (e.g., dotenv comment detection via `#` prefix check\n happens before the inner-quote fallback is reached)\n\n### Don't suggest fixes that introduce circular dependencies\n\nIn parsers and state machines, be careful not to suggest fixes that require\nknowing the answer to the question being solved. For example, suggesting \"detect\nwhere the comment starts before matching quotes\" is circular when the quote\nmatching is what determines where the value (and thus the comment) begins.\n\n### Verify suggestions against existing tests\n\nBefore suggesting a change, check whether the codebase already has test coverage\nfor the case in question. The `test_valid_env` test in `libs/dotenv/lib.rs`\ncovers many edge cases including inline comments with quotes\n(`EDGE_CASE_INLINE_COMMENTS`). Running existing tests before and after a\nsuggested change catches regressions.\n\n### Match existing patterns in the codebase\n\nWhen suggesting changes to a function, look for similar functions nearby that\nsolve analogous problems. If the existing pattern (e.g., `wait_for_session`)\nuses a specific flag/mechanism, understand why before suggesting a different\napproach for a similar function (e.g., `wait_for_sessions_disconnect`). The\ndifference may be intentional.\n\n### Deno-specific conventions\n\n- Ops use the `#[op2]` macro. Fast ops use `#[op2(fast)]`.\n- Internal symbols in JS (`ext/process/40_process.js`, `ext/node/polyfills/`)\n use the `k` prefix convention: `kIpc`, `kSerialization`, `kInputOption`. Flag\n deviations.\n- Node.js compatibility code is in `ext/node/polyfills/`. When reviewing these\n files, check behavior against Node.js docs, not just Deno conventions. Some\n patterns (like synchronous `throw` in `spawn()` for EPERM but async error\n event for ENOENT) are intentional Node.js compatibility.\n\n### When suggesting error handling changes\n\n- Check whether the function's callers expect the error to propagate or be\n swallowed. Do not suggest propagating errors in paths that are intentionally\n best-effort (e.g. killing already-exited processes).\n- When suggesting a specific error variant or code change, verify the types\n actually match. For example, `Option::or_else` takes `FnOnce() -> Option`,\n not `FnOnce(E) -> ...`.\n- If a Rust function returns `Result` and an `Option` is needed, use `.ok()`\n before `.or_else()` or `.unwrap_or()`.\n\n### Platform-specific code\n\n- `#[cfg(unix)]` code that calls `find_descendant_pids` or similar must have\n stubs for non-Linux/non-macOS Unix targets. Check that\n `#[cfg(all(unix, not(target_os = \"linux\"), not(target_os = \"macos\")))]` stubs\n exist before flagging missing platform support.\n- Windows `unsafe` blocks using `windows_sys` are common for process management.\n Verify handle cleanup (`CloseHandle`) but do not flag the `unsafe` usage\n itself.\n\n## Troubleshooting\n\n- **Slow compile times**: Use `cargo check`, `--bin deno`, or `sccache`\n- **Build failures on macOS**: Run `xcode-select --install`\n- **Build failures on Linux**: Install `build-essential`\n- **Spec test failures**: Check output diffs, use `[WILDCARD]` for\n non-deterministic parts\n- **Permission errors**: Ensure test files have correct permissions\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/plugin.json)",".cursorrules (deno-integration-techniques-cursorrules-prompt-fil.mdc)":"---\ndescription: \"Cursor rules for Deno development with integration techniques.\"\nglobs: **/*\nalwaysApply: false\n---\nThis project contains automation scripts and workflows for the @findhow packages, based on the original Deno automation repository. The goal is to provide consistent and efficient automation for the @findhow ecosystem.\n\nThe purpose of this project is to refactor and adapt the automation scripts from [denoland/automation](https://github.com/denoland/automation) for use with the configured @findhow package repositories.\n\nWhen working on this project, Cursor AI should:\n\nWhen making changes:\n\nWhen updating documentation:\n\nWhen creating or modifying automation scripts:\n\nRemember to thoroughly test all modifications to ensure they work correctly with the @findhow ecosystem before merging changes into the main branch.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/denoland/deno/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# Deno Development Guide\n\n## Table of Contents\n\n- [Git workflow](#git-workflow)\n- [High Level Overview](#high-level-overview)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Testing](#testing)\n- [Development Workflows](#development-workflows)\n- [Debugging](#debugging)\n- [Codebase Navigation](#codebase-navigation)\n- [Troubleshooting](#troubleshooting)\n\n## Git workflow\n\nDeno uses a GH based standard git workflow. The main branch is `main`. All\ndevelopment happens in feature branches, which are then merged into `main` via\npull requests.\n\nWhen the feature is finished and ready to for review, follow these steps:\n\n- Create a new git branch, if you haven't already, with a descriptive name\n (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).\n- Commit your changes with clear and descriptive commit messages.\n- Push your branch to the remote repository.\n- Open a pull request (PR) against the `main` branch on GitHub.\n- Before committing, make sure `tools/format.js` is run to format your code\n- Before committing, if only non-Rust was changed, make sure to run\n `tools/lint.js --js` and fix any lint errors before committing\n- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint\n errors before committing\n- In the PR description, provide a clear summary of the changes you made, why\n they were necessary, and any relevant context or links to related issues.\n- When pushing updates to the PR, make sure to never force push. Create as many\n commits as you need, all of them get squashed when the PR is merged, so there\n is no need to rewrite history. This also allows reviewers to see the\n incremental changes you made in response to feedback.\n- Keep your changes minimal, don't do drive-by changes in a PR. If you need to\n make a change that is not directly related to the PR, create a separate PR for\n it. This keeps the review process focused and efficient.\n\n## High Level Overview\n\nThe user visible interface and high level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all \"extensions\" (native functionality exposed to JavaScript). The\nextensions themselves are in the `ext/` directory, and provide system access to\nJavaScript – for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` - User-facing CLI implementation, subcommands, and tools\n- `runtime/` - JavaScript runtime assembly and integration\n- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)\n- `tests/specs/` - Integration tests (spec tests)\n- `tests/unit/` - Unit tests\n- `tests/testdata/` - Test fixtures and data files\n\n## Quick Start\n\nBefore building, install the required prerequisites (Rust, native compilers,\ncmake, protobuf, etc.) and clone with `--recurse-submodules` as described in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Building Deno\n\nTo compile after making changes:\n\n```bash\ncargo build\n```\n\nFor faster iteration during development (less optimization):\n\n```bash\ncargo build --bin deno\n```\n\nExecute your development build:\n\n```bash\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n### Running with your changes\n\n```bash\n# Run a local file\n./target/debug/deno run path/to/file.ts\n\n# Run with permissions\n./target/debug/deno run --allow-net --allow-read script.ts\n\n# Run the REPL\n./target/debug/deno\n```\n\n## Commands\n\n### Compilation and Checks\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Check specific package\ncargo check -p deno_runtime\n\n# Build release version (slow, optimized)\ncargo build --release\n```\n\n### Code Quality\n\n```bash\n# Lint the code\n./tools/lint.js\n\n# Format the code\n./tools/format.js\n\n# Both lint and format\n./tools/format.js && ./tools/lint.js\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests (this takes a while)\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Unit Tests (`tests/unit/`)\n\nJavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run\nthem via `cargo test`:\n\n```bash\n# Run all unit tests in a specific file\ncargo test unit::webcrypto_test\n\n# Run all unit tests\ncargo test unit::\n\n# Run Node.js compatibility unit tests (tests/unit_node/)\ncargo test unit_node::crypto_test\n\n# Run all Node.js compat unit tests\ncargo test unit_node::\n```\n\nDo NOT run these directly with `./target/debug/deno test` — they depend on the\ncargo test harness for correct setup.\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command\n execution and output validation\n- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime\n APIs\n- **Integration tests** (`tests/integration/`) - Additional integration tests\n- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance\n\n## \"spec\" tests\n\nThe main form of integration test in deno is the \"spec\" test. These tests can be\nfound in `tests/specs`. The idea is that you have a `__test__.jsonc` file that\nlays out one or more tests, where a test is a CLI command to execute and the\noutput is captured and asserted against.\n\nThe name of the test comes from the directory the `__test__.jsonc` appears in.\n\n### Creating a New Spec Test\n\n1. Create a directory in `tests/specs/` with a descriptive name\n2. Add a `__test__.jsonc` file describing your test steps\n3. Add any input files needed for the test\n4. Add `.out` files for expected output (or inline in `__test__.jsonc`)\n\nExample:\n\n```\ntests/specs/my_feature/\n __test__.jsonc\n main.ts\n expected.out\n```\n\n### `__test__.jsonc` schema\n\nThe schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.\n\nExample test structure:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n },\n \"with_flag\": {\n \"steps\": [\n {\n \"args\": \"run --allow-net main.ts\",\n \"output\": \"[WILDCARD]success[WILDCARD]\"\n }\n ]\n }\n }\n}\n```\n\n### Output assertions\n\nThe expected output can be inline in a `__test__.jsonc` file or in a file ending\nwith `.out`. For a given test step, the `output` field tells you either the\ninline expectation or the name of the file containing the **expectation**. The\nexpectation uses a small matching language to support wildcards and things like\nthat. A literal character means you expect that exact character, so `Foo bar`\nwould expect the output to be \"Foo bar\". Then there are things with special\nmeanings:\n\n- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this\n can cross newlines\n- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line\n- `[WILDCHAR]` - match the next character\n- `[WILDCHARS(5)]` - match any of the next 5 characters\n- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match\n the lines in any order (useful for non-deterministic output)\n- `[# example]` - line comments start with `[#` and end with `]`\n\nExample `.out` file:\n\n```\nCheck file://[WILDCARD]/main.ts\n[WILDCARD]\nSuccessfully compiled [WILDLINE]\n```\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\nExample files to reference:\n\n- Simple command: `cli/tools/fmt.rs`\n- Complex command: `cli/tools/test/`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//` (e.g., `ext/fs/`, `ext/net/`)\n2. Rust code provides the ops (operations) exposed to JavaScript\n3. JavaScript code in the extension provides the higher-level APIs\n4. Update `runtime/worker.rs` to register the extension if new\n5. Add tests in the extension's directory\n\n### Updating Dependencies\n\n```bash\n# Update Cargo dependencies\ncargo update\n\n# Update to latest compatible versions\ncargo upgrade # Requires cargo-edit: cargo install cargo-edit\n\n# Check for outdated dependencies\ncargo outdated # Requires cargo-outdated\n```\n\n## Debugging\n\n### Debugging Rust Code\n\nUse `lldb` directly:\n\n```bash\nlldb ./target/debug/deno\n(lldb) run eval 'console.log(\"test\")'\n```\n\n### Debugging JavaScript Runtime Issues\n\nUse println debugging.\n\n### Verbose Logging\n\n```bash\n# Set Rust log level\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Specific module logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n```\n\n### Debug Prints\n\nIn Rust code:\n\n```rust\neprintln!(\"Debug: {:?}\", some_variable);\ndbg!(some_variable);\n```\n\nIn JavaScript/TypeScript code:\n\n```javascript\nconsole.log(\"Debug:\", value);\n```\n\n## Codebase Navigation\n\n### Key Files to Understand First\n\n1. `cli/main.rs` - Entry point, command routing\n2. `cli/args/flags.rs` - CLI flag parsing and structure\n3. `runtime/worker.rs` - Worker/runtime initialization\n4. `runtime/permissions.rs` - Permission system\n5. `cli/module_loader.rs` - Module loading and resolution\n\n### Common Patterns\n\n- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** - Collections of ops and JS code providing functionality\n- **Workers** - JavaScript execution contexts (main worker, web workers)\n- **Resources** - Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n### Finding Examples\n\n- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`\n- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,\n `ext/fs/lib.rs`)\n- Need to add a tool? Reference existing tools in `cli/tools/`\n\n## Troubleshooting\n\n### Build Failures\n\n**Error: linking with `cc` failed**\n\n- Make sure you have the required system dependencies\n- On macOS: `xcode-select --install`\n- On Linux: Install `build-essential` or equivalent\n\n**Error: failed to download dependencies**\n\n- Check internet connection\n- Try `cargo clean` then rebuild\n- Check if behind a proxy, configure cargo accordingly\n\nFor other build failures (missing `cmake`, `stdarg.h`, etc.), see the full\nprerequisites in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Test Failures\n\n**Spec test failures**\n\n- Check the test output carefully for differences\n- Update `.out` files if output format changed intentionally\n- Use `[WILDCARD]` for non-deterministic parts of output\n\n**Flaky tests**\n\n- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output\n- Check for race conditions in test code\n- May need to increase timeouts or add retries\n\n### Permission Issues\n\n**Tests failing with permission errors**\n\n- Ensure test files have correct permissions\n- Check that test setup properly grants necessary permissions\n\n### Performance Issues\n\n**Slow compile times**\n\n- Use `cargo check` instead of `cargo build` when possible\n- Use `--bin deno` to build only the main binary\n- Use `sccache` or `mold` linker for faster builds\n- Consider using `cargo-watch` for incremental builds\n\n### Runtime Debugging\n\n**Crashes or panics**\n\n- Run with `RUST_BACKTRACE=1` for full backtrace\n- Use `RUST_BACKTRACE=full` for even more detail\n- Check for unwrap() calls that might panic\n\n**Unexpected behavior**\n\n- Add debug prints liberally\n- Check permission grants - many features require explicit permissions\n\n### Getting Help\n\n- Check existing issues on GitHub\n- Look at recent PRs for similar changes\n- Review the Discord community for discussions\n- When in doubt, ask! The maintainers are helpful\n","isInternal":false,"tokens":2966,"sizeBytes":11866},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/denoland/deno/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Deno Development Guide for GitHub Copilot\n\n## Network Access\n\nThe development tools in this repository need network access to function. When\nrunning `tools/format.js` or `tools/lint.js`, ensure the following domains are\nreachable:\n\n- `https://jsr.io` — Deno's package registry, used for `@std/*` imports\n- `https://dprint.dev` and `https://plugins.dprint.dev` — the formatter\n (`tools/format.js`) runs `npm:dprint` which downloads WASM plugins from\n `plugins.dprint.dev`\n\nIf you are running in a sandboxed environment, you must allowlist these domains\nor the tools will fail with network errors.\n\n## High Level Overview\n\nThe user-visible interface and high-level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all of the \"extensions\" (native functionality exposed to JavaScript).\nThe extensions themselves are in the `ext/` directory, and provide system access\nto JavaScript — for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` — User-facing CLI implementation, subcommands, and tools\n- `runtime/` — JavaScript runtime assembly and integration\n- `ext/` — Extensions providing native functionality to JS (fs, net, etc.)\n- `libs/` — Shared Rust crates (core, resolver, npm, node_resolver, serde_v8,\n etc.)\n- `tests/specs/` — Integration tests (spec tests)\n- `tests/unit/` — Unit tests\n- `tests/testdata/` — Test fixtures and data files\n\n### Key Files to Understand First\n\n1. `cli/main.rs` — Entry point, command routing\n2. `cli/args/flags.rs` — CLI flag parsing and structure\n3. `runtime/worker.rs` — Worker/runtime initialization\n4. `runtime/permissions.rs` — Permission system\n5. `cli/module_loader.rs` — Module loading and resolution\n\n### Common Patterns\n\n- **Ops** — Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** — Collections of ops and JS code providing functionality\n- **Workers** — JavaScript execution contexts (main worker, web workers)\n- **Resources** — Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n## Building\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Build debug binary\ncargo build --bin deno\n\n# Build release version (slow, optimized)\ncargo build --release\n\n# Run the dev build\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n## Code Quality\n\nBefore committing, always run the formatter and linter:\n\n```bash\n# Format all code (uses dprint under the hood)\n./tools/format.js\n\n# Lint all code (JS + Rust via clippy)\n./tools/lint.js\n\n# Lint only JS/TS (faster, skips clippy)\n./tools/lint.js --js\n\n# Lint only Rust\n./tools/lint.js --rs\n```\n\nThe formatter (`tools/format.js`) runs `dprint` via `npm:dprint@0.47.2`. It\nformats TypeScript, JavaScript, JSON, Markdown, YAML, and Rust (via `rustfmt`).\nConfiguration is in `.dprint.json`.\n\nThe linter (`tools/lint.js`) runs `deno lint` for JS/TS and `cargo clippy` for\nRust.\n\n## Testing\n\n```bash\n# Run all tests\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) — Main integration tests\n- **Unit tests** — Inline with source code in each module\n- **Integration tests** (`tests/integration/`) — Additional integration tests\n- **WPT** (`tests/wpt/`) — Web Platform Tests for web standards compliance\n\n### Spec Tests\n\nThe main form of integration test is the \"spec\" test in `tests/specs/`. Each\ntest has a `__test__.jsonc` file describing CLI commands to run and expected\noutput. The schema is in `tests/specs/schema.json`.\n\nExample `__test__.jsonc`:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n }\n }\n}\n```\n\nOutput assertions support wildcards:\n\n- `[WILDCARD]` — matches 0 or more characters (crosses newlines)\n- `[WILDLINE]` — matches to end of line\n- `[WILDCHAR]` — matches one character\n- `[WILDCHARS(N)]` — matches N characters\n- `[UNORDERED_START]` / `[UNORDERED_END]` — matches lines in any order\n\n## Git Workflow and Pull Requests\n\n### PR Title Linting\n\nPR titles are validated by CI (see `.github/workflows/pr.ts`). The title must\nfollow [Conventional Commits](https://www.conventionalcommits.org) and start\nwith one of these prefixes:\n\n- `feat:` — new features\n- `fix:` — bug fixes\n- `chore:` — maintenance tasks\n- `perf:` — performance improvements\n- `ci:` — CI changes\n- `cleanup:` — code cleanup\n- `docs:` — documentation\n- `bench:` — benchmarks\n- `build:` — build system changes\n- `refactor:` — refactoring\n- `test:` — test changes\n- `Revert` — reverting a previous commit\n- `Reland` — relanding a reverted commit\n- `BREAKING` — breaking changes\n\nAdditionally, deno_core/v8 upgrades must NOT use `chore:` — use `feat:`, `fix:`,\nor `refactor:` instead, with a title describing the actual change.\n\nRelease PRs (titles matching `X.Y.Z`) are also valid.\n\nThe validation script is at `tools/verify_pr_title.js`.\n\n### Workflow Rules\n\n- Create feature branches with descriptive names\n- Commit with clear, descriptive messages\n- Never force push — all commits are squashed on merge\n- Keep changes minimal and focused; avoid drive-by changes\n- Before committing, run `tools/format.js` and `tools/lint.js`\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//`\n2. Rust code provides the ops exposed to JavaScript\n3. JavaScript code in the extension provides higher-level APIs\n4. Update `runtime/worker.rs` to register a new extension\n5. Add tests in the extension's directory\n\n## Debugging\n\n```bash\n# Verbose logging\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Module-specific logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n\n# Full backtrace on panic\nRUST_BACKTRACE=1 ./target/debug/deno run script.ts\n\n# V8 inspector\n./target/debug/deno run --inspect-brk script.ts\n```\n\nIn Rust code: `eprintln!(\"Debug: {:?}\", var);` or `dbg!(var);`\n\n## Pull Request Reviews\n\n### Before commenting, verify your claims\n\n- If you claim something is missing (a stub, a test, error handling), search the\n full diff AND the existing codebase before commenting. Do not flag missing\n code that already exists elsewhere in the PR or the repository.\n- If you suggest a code change, verify it compiles and does not break the\n intended behavior. Do not suggest fixes that contradict the PR's stated goal.\n- Do not duplicate your own comments. If you already flagged an issue, do not\n post a second comment about the same thing.\n\n### Focus on high-value issues\n\nPrioritize these (in order):\n\n1. **Correctness bugs** — logic errors, race conditions (e.g. spurious wakeups\n on `Condvar`), use-after-free, null derefs\n2. **Public API leaks** — internal fields accidentally exposed in public return\n types\n3. **Security** — unsafe blocks with incorrect safety invariants, unsanitized\n inputs at system boundaries\n4. **Missing error handling** — errors silently swallowed where they should\n propagate, or propagated where they should be caught\n\nDo NOT comment on:\n\n- Style preferences already enforced by the project's formatter (dprint) and\n linter (clippy + deno lint)\n- Suggesting longer timeouts or shorter delays in tests without evidence of\n flakiness\n- Minor documentation wording unless it is actively misleading\n- Hypothetical edge cases that cannot realistically occur (e.g. a process having\n > 256 direct children)\n\n### Understand the runtime model before suggesting fixes\n\nDeno embeds V8 and uses a single-threaded async event loop (tokio). Code that\nlooks like a busy-spin may actually be required because:\n\n- `poll_sessions(None)` in the inspector drives async I/O — parking the thread\n prevents WebSocket close frames from being processed, causing deadlocks\n- The event loop must keep running for futures to make progress; blocking the\n main thread stops the I/O reactor\n- Some loops intentionally spin to allow the waker/poller to process events each\n iteration\n\nBefore suggesting `sleep`, `park`, or backoff in a polling loop, check whether\nthe loop body drives async I/O that would stall if the thread were blocked.\n\n### Trace through the actual code path, not just the function signature\n\nA common review mistake is looking at a function's local behavior without\ntracing its callers and the runtime context. For example:\n\n- A function that \"doesn't check field X\" may not need to because callers\n guarantee X is consumed before the check runs (e.g., `handshake` is always\n `take()`n at the top of `poll_sessions` before any session-count checks)\n- A heuristic that \"doesn't handle case Y\" may already handle it through a\n different code path (e.g., dotenv comment detection via `#` prefix check\n happens before the inner-quote fallback is reached)\n\n### Don't suggest fixes that introduce circular dependencies\n\nIn parsers and state machines, be careful not to suggest fixes that require\nknowing the answer to the question being solved. For example, suggesting \"detect\nwhere the comment starts before matching quotes\" is circular when the quote\nmatching is what determines where the value (and thus the comment) begins.\n\n### Verify suggestions against existing tests\n\nBefore suggesting a change, check whether the codebase already has test coverage\nfor the case in question. The `test_valid_env` test in `libs/dotenv/lib.rs`\ncovers many edge cases including inline comments with quotes\n(`EDGE_CASE_INLINE_COMMENTS`). Running existing tests before and after a\nsuggested change catches regressions.\n\n### Match existing patterns in the codebase\n\nWhen suggesting changes to a function, look for similar functions nearby that\nsolve analogous problems. If the existing pattern (e.g., `wait_for_session`)\nuses a specific flag/mechanism, understand why before suggesting a different\napproach for a similar function (e.g., `wait_for_sessions_disconnect`). The\ndifference may be intentional.\n\n### Deno-specific conventions\n\n- Ops use the `#[op2]` macro. Fast ops use `#[op2(fast)]`.\n- Internal symbols in JS (`ext/process/40_process.js`, `ext/node/polyfills/`)\n use the `k` prefix convention: `kIpc`, `kSerialization`, `kInputOption`. Flag\n deviations.\n- Node.js compatibility code is in `ext/node/polyfills/`. When reviewing these\n files, check behavior against Node.js docs, not just Deno conventions. Some\n patterns (like synchronous `throw` in `spawn()` for EPERM but async error\n event for ENOENT) are intentional Node.js compatibility.\n\n### When suggesting error handling changes\n\n- Check whether the function's callers expect the error to propagate or be\n swallowed. Do not suggest propagating errors in paths that are intentionally\n best-effort (e.g. killing already-exited processes).\n- When suggesting a specific error variant or code change, verify the types\n actually match. For example, `Option::or_else` takes `FnOnce() -> Option`,\n not `FnOnce(E) -> ...`.\n- If a Rust function returns `Result` and an `Option` is needed, use `.ok()`\n before `.or_else()` or `.unwrap_or()`.\n\n### Platform-specific code\n\n- `#[cfg(unix)]` code that calls `find_descendant_pids` or similar must have\n stubs for non-Linux/non-macOS Unix targets. Check that\n `#[cfg(all(unix, not(target_os = \"linux\"), not(target_os = \"macos\")))]` stubs\n exist before flagging missing platform support.\n- Windows `unsafe` blocks using `windows_sys` are common for process management.\n Verify handle cleanup (`CloseHandle`) but do not flag the `unsafe` usage\n itself.\n\n## Troubleshooting\n\n- **Slow compile times**: Use `cargo check`, `--bin deno`, or `sccache`\n- **Build failures on macOS**: Run `xcode-select --install`\n- **Build failures on Linux**: Install `build-essential`\n- **Spec test failures**: Check output diffs, use `[WILDCARD]` for\n non-deterministic parts\n- **Permission errors**: Ensure test files have correct permissions\n","isInternal":false,"tokens":3056,"sizeBytes":12567},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":192},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":178},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/denoland/deno/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":171},{"name":".cursorrules","path":".cursorrules (deno-integration-techniques-cursorrules-prompt-fil.mdc)","rawUrl":"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/deno-integration-techniques-cursorrules-prompt-fil.mdc","title":"Awesome Cursorrules: deno integration techniques cursorrules prompt fil","category":"cursor-rule","format":"markdown","content":"---\ndescription: \"Cursor rules for Deno development with integration techniques.\"\nglobs: **/*\nalwaysApply: false\n---\nThis project contains automation scripts and workflows for the @findhow packages, based on the original Deno automation repository. The goal is to provide consistent and efficient automation for the @findhow ecosystem.\n\nThe purpose of this project is to refactor and adapt the automation scripts from [denoland/automation](https://github.com/denoland/automation) for use with the configured @findhow package repositories.\n\nWhen working on this project, Cursor AI should:\n\nWhen making changes:\n\nWhen updating documentation:\n\nWhen creating or modifying automation scripts:\n\nRemember to thoroughly test all modifications to ensure they work correctly with the @findhow ecosystem before merging changes into the main branch.\n","tokens":155,"sizeBytes":838}],"systemPromptSnippet":"\n\n# Deno Development Guide\n\n## Table of Contents\n\n- [Git workflow](#git-workflow)\n- [High Level Overview](#high-level-overview)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Testing](#testing)\n- [Development Workflows](#development-workflows)\n- [Debugging](#debugging)\n- [Codebase Navigation](#codebase-navigation)\n- [Troubleshooting](#troubleshooting)\n\n## Git workflow\n\nDeno uses a GH based standard git workflow. The main branch is `main`. All\ndevelopment happens in feature branches, which are then merged into `main` via\npull requests.\n\nWhen the feature is finished and ready to for review, follow these steps:\n\n- Create a new git branch, if you haven't already, with a descriptive name\n (e.g., `feature/new-cli-command` or `fix/bug-in-worker-threads`).\n- Commit your changes with clear and descriptive commit messages.\n- Push your branch to the remote repository.\n- Open a pull request (PR) against the `main` branch on GitHub.\n- Before committing, make sure `tools/format.js` is run to format your code\n- Before committing, if only non-Rust was changed, make sure to run\n `tools/lint.js --js` and fix any lint errors before committing\n- If you changed Rust code, make sure to run `tools/lint.js` and fix any lint\n errors before committing\n- In the PR description, provide a clear summary of the changes you made, why\n they were necessary, and any relevant context or links to related issues.\n- When pushing updates to the PR, make sure to never force push. Create as many\n commits as you need, all of them get squashed when the PR is merged, so there\n is no need to rewrite history. This also allows reviewers to see the\n incremental changes you made in response to feedback.\n- Keep your changes minimal, don't do drive-by changes in a PR. If you need to\n make a change that is not directly related to the PR, create a separate PR for\n it. This keeps the review process focused and efficient.\n\n## High Level Overview\n\nThe user visible interface and high level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all \"extensions\" (native functionality exposed to JavaScript). The\nextensions themselves are in the `ext/` directory, and provide system access to\nJavaScript – for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` - User-facing CLI implementation, subcommands, and tools\n- `runtime/` - JavaScript runtime assembly and integration\n- `ext/` - Extensions providing native functionality to JS (fs, net, etc.)\n- `tests/specs/` - Integration tests (spec tests)\n- `tests/unit/` - Unit tests\n- `tests/testdata/` - Test fixtures and data files\n\n## Quick Start\n\nBefore building, install the required prerequisites (Rust, native compilers,\ncmake, protobuf, etc.) and clone with `--recurse-submodules` as described in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Building Deno\n\nTo compile after making changes:\n\n```bash\ncargo build\n```\n\nFor faster iteration during development (less optimization):\n\n```bash\ncargo build --bin deno\n```\n\nExecute your development build:\n\n```bash\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n### Running with your changes\n\n```bash\n# Run a local file\n./target/debug/deno run path/to/file.ts\n\n# Run with permissions\n./target/debug/deno run --allow-net --allow-read script.ts\n\n# Run the REPL\n./target/debug/deno\n```\n\n## Commands\n\n### Compilation and Checks\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Check specific package\ncargo check -p deno_runtime\n\n# Build release version (slow, optimized)\ncargo build --release\n```\n\n### Code Quality\n\n```bash\n# Lint the code\n./tools/lint.js\n\n# Format the code\n./tools/format.js\n\n# Both lint and format\n./tools/format.js && ./tools/lint.js\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests (this takes a while)\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Unit Tests (`tests/unit/`)\n\nJavaScript/TypeScript unit tests live in `tests/unit/` as `*_test.ts` files. Run\nthem via `cargo test`:\n\n```bash\n# Run all unit tests in a specific file\ncargo test unit::webcrypto_test\n\n# Run all unit tests\ncargo test unit::\n\n# Run Node.js compatibility unit tests (tests/unit_node/)\ncargo test unit_node::crypto_test\n\n# Run all Node.js compat unit tests\ncargo test unit_node::\n```\n\nDo NOT run these directly with `./target/debug/deno test` — they depend on the\ncargo test harness for correct setup.\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) - Main integration tests, CLI command\n execution and output validation\n- **Unit tests** (`tests/unit/`) - JavaScript/TypeScript unit tests for runtime\n APIs\n- **Integration tests** (`tests/integration/`) - Additional integration tests\n- **WPT** (`tests/wpt/`) - Web Platform Tests for web standards compliance\n\n## \"spec\" tests\n\nThe main form of integration test in deno is the \"spec\" test. These tests can be\nfound in `tests/specs`. The idea is that you have a `__test__.jsonc` file that\nlays out one or more tests, where a test is a CLI command to execute and the\noutput is captured and asserted against.\n\nThe name of the test comes from the directory the `__test__.jsonc` appears in.\n\n### Creating a New Spec Test\n\n1. Create a directory in `tests/specs/` with a descriptive name\n2. Add a `__test__.jsonc` file describing your test steps\n3. Add any input files needed for the test\n4. Add `.out` files for expected output (or inline in `__test__.jsonc`)\n\nExample:\n\n```\ntests/specs/my_feature/\n __test__.jsonc\n main.ts\n expected.out\n```\n\n### `__test__.jsonc` schema\n\nThe schema for `__test__.jsonc` can be found in `tests/specs/schema.json`.\n\nExample test structure:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n },\n \"with_flag\": {\n \"steps\": [\n {\n \"args\": \"run --allow-net main.ts\",\n \"output\": \"[WILDCARD]success[WILDCARD]\"\n }\n ]\n }\n }\n}\n```\n\n### Output assertions\n\nThe expected output can be inline in a `__test__.jsonc` file or in a file ending\nwith `.out`. For a given test step, the `output` field tells you either the\ninline expectation or the name of the file containing the **expectation**. The\nexpectation uses a small matching language to support wildcards and things like\nthat. A literal character means you expect that exact character, so `Foo bar`\nwould expect the output to be \"Foo bar\". Then there are things with special\nmeanings:\n\n- `[WILDCARD]` : matches 0 or more of any character, like `.*` in regex. this\n can cross newlines\n- `[WILDLINE]` : matches 0 or more of any character, ending at the end of a line\n- `[WILDCHAR]` - match the next character\n- `[WILDCHARS(5)]` - match any of the next 5 characters\n- `[UNORDERED_START]` followed by many lines then `[UNORDERED_END]` will match\n the lines in any order (useful for non-deterministic output)\n- `[# example]` - line comments start with `[#` and end with `]`\n\nExample `.out` file:\n\n```\nCheck file://[WILDCARD]/main.ts\n[WILDCARD]\nSuccessfully compiled [WILDLINE]\n```\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\nExample files to reference:\n\n- Simple command: `cli/tools/fmt.rs`\n- Complex command: `cli/tools/test/`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//` (e.g., `ext/fs/`, `ext/net/`)\n2. Rust code provides the ops (operations) exposed to JavaScript\n3. JavaScript code in the extension provides the higher-level APIs\n4. Update `runtime/worker.rs` to register the extension if new\n5. Add tests in the extension's directory\n\n### Updating Dependencies\n\n```bash\n# Update Cargo dependencies\ncargo update\n\n# Update to latest compatible versions\ncargo upgrade # Requires cargo-edit: cargo install cargo-edit\n\n# Check for outdated dependencies\ncargo outdated # Requires cargo-outdated\n```\n\n## Debugging\n\n### Debugging Rust Code\n\nUse `lldb` directly:\n\n```bash\nlldb ./target/debug/deno\n(lldb) run eval 'console.log(\"test\")'\n```\n\n### Debugging JavaScript Runtime Issues\n\nUse println debugging.\n\n### Verbose Logging\n\n```bash\n# Set Rust log level\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Specific module logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n```\n\n### Debug Prints\n\nIn Rust code:\n\n```rust\neprintln!(\"Debug: {:?}\", some_variable);\ndbg!(some_variable);\n```\n\nIn JavaScript/TypeScript code:\n\n```javascript\nconsole.log(\"Debug:\", value);\n```\n\n## Codebase Navigation\n\n### Key Files to Understand First\n\n1. `cli/main.rs` - Entry point, command routing\n2. `cli/args/flags.rs` - CLI flag parsing and structure\n3. `runtime/worker.rs` - Worker/runtime initialization\n4. `runtime/permissions.rs` - Permission system\n5. `cli/module_loader.rs` - Module loading and resolution\n\n### Common Patterns\n\n- **Ops** - Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** - Collections of ops and JS code providing functionality\n- **Workers** - JavaScript execution contexts (main worker, web workers)\n- **Resources** - Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n### Finding Examples\n\n- Need to add a CLI flag? Look at similar commands in `cli/args/flags.rs`\n- Need to add an op? Look at ops in relevant `ext/` directory (e.g.,\n `ext/fs/lib.rs`)\n- Need to add a tool? Reference existing tools in `cli/tools/`\n\n## Troubleshooting\n\n### Build Failures\n\n**Error: linking with `cc` failed**\n\n- Make sure you have the required system dependencies\n- On macOS: `xcode-select --install`\n- On Linux: Install `build-essential` or equivalent\n\n**Error: failed to download dependencies**\n\n- Check internet connection\n- Try `cargo clean` then rebuild\n- Check if behind a proxy, configure cargo accordingly\n\nFor other build failures (missing `cmake`, `stdarg.h`, etc.), see the full\nprerequisites in\n[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md#building-from-source).\n\n### Test Failures\n\n**Spec test failures**\n\n- Check the test output carefully for differences\n- Update `.out` files if output format changed intentionally\n- Use `[WILDCARD]` for non-deterministic parts of output\n\n**Flaky tests**\n\n- Add `[UNORDERED_START]`/`[UNORDERED_END]` for order-independent output\n- Check for race conditions in test code\n- May need to increase timeouts or add retries\n\n### Permission Issues\n\n**Tests failing with permission errors**\n\n- Ensure test files have correct permissions\n- Check that test setup properly grants necessary permissions\n\n### Performance Issues\n\n**Slow compile times**\n\n- Use `cargo check` instead of `cargo build` when possible\n- Use `--bin deno` to build only the main binary\n- Use `sccache` or `mold` linker for faster builds\n- Consider using `cargo-watch` for incremental builds\n\n### Runtime Debugging\n\n**Crashes or panics**\n\n- Run with `RUST_BACKTRACE=1` for full backtrace\n- Use `RUST_BACKTRACE=full` for even more detail\n- Check for unwrap() calls that might panic\n\n**Unexpected behavior**\n\n- Add debug prints liberally\n- Check permission grants - many features require explicit permissions\n\n### Getting Help\n\n- Check existing issues on GitHub\n- Look at recent PRs for similar changes\n- Review the Discord community for discussions\n- When in doubt, ask! The maintainers are helpful\n\n\n# Deno Development Guide for GitHub Copilot\n\n## Network Access\n\nThe development tools in this repository need network access to function. When\nrunning `tools/format.js` or `tools/lint.js`, ensure the following domains are\nreachable:\n\n- `https://jsr.io` — Deno's package registry, used for `@std/*` imports\n- `https://dprint.dev` and `https://plugins.dprint.dev` — the formatter\n (`tools/format.js`) runs `npm:dprint` which downloads WASM plugins from\n `plugins.dprint.dev`\n\nIf you are running in a sandboxed environment, you must allowlist these domains\nor the tools will fail with network errors.\n\n## High Level Overview\n\nThe user-visible interface and high-level integration is in the `deno` crate\n(located in `./cli`).\n\nThis includes flag parsing, subcommands, package management tooling, etc. Flag\nparsing is in `cli/args/flags.rs`. Tools are in `cli/tools/`.\n\nThe `deno_runtime` crate (`./runtime`) assembles the JavaScript runtime,\nincluding all of the \"extensions\" (native functionality exposed to JavaScript).\nThe extensions themselves are in the `ext/` directory, and provide system access\nto JavaScript — for instance filesystem operations and networking.\n\n### Key Directories\n\n- `cli/` — User-facing CLI implementation, subcommands, and tools\n- `runtime/` — JavaScript runtime assembly and integration\n- `ext/` — Extensions providing native functionality to JS (fs, net, etc.)\n- `libs/` — Shared Rust crates (core, resolver, npm, node_resolver, serde_v8,\n etc.)\n- `tests/specs/` — Integration tests (spec tests)\n- `tests/unit/` — Unit tests\n- `tests/testdata/` — Test fixtures and data files\n\n### Key Files to Understand First\n\n1. `cli/main.rs` — Entry point, command routing\n2. `cli/args/flags.rs` — CLI flag parsing and structure\n3. `runtime/worker.rs` — Worker/runtime initialization\n4. `runtime/permissions.rs` — Permission system\n5. `cli/module_loader.rs` — Module loading and resolution\n\n### Common Patterns\n\n- **Ops** — Rust functions exposed to JavaScript (in `ext/` directories)\n- **Extensions** — Collections of ops and JS code providing functionality\n- **Workers** — JavaScript execution contexts (main worker, web workers)\n- **Resources** — Managed objects passed between Rust and JS (files, sockets,\n etc.)\n\n## Building\n\n```bash\n# Check for compilation errors (fast, no binary output)\ncargo check\n\n# Build debug binary\ncargo build --bin deno\n\n# Build release version (slow, optimized)\ncargo build --release\n\n# Run the dev build\n./target/debug/deno eval 'console.log(\"Hello from dev build\")'\n```\n\n## Code Quality\n\nBefore committing, always run the formatter and linter:\n\n```bash\n# Format all code (uses dprint under the hood)\n./tools/format.js\n\n# Lint all code (JS + Rust via clippy)\n./tools/lint.js\n\n# Lint only JS/TS (faster, skips clippy)\n./tools/lint.js --js\n\n# Lint only Rust\n./tools/lint.js --rs\n```\n\nThe formatter (`tools/format.js`) runs `dprint` via `npm:dprint@0.47.2`. It\nformats TypeScript, JavaScript, JSON, Markdown, YAML, and Rust (via `rustfmt`).\nConfiguration is in `.dprint.json`.\n\nThe linter (`tools/lint.js`) runs `deno lint` for JS/TS and `cargo clippy` for\nRust.\n\n## Testing\n\n```bash\n# Run all tests\ncargo test\n\n# Filter tests by name\ncargo test \n\n# Run tests in a specific package\ncargo test -p deno_core\n\n# Run just the CLI integration tests\ncargo test --bin deno\n\n# Run spec tests only\ncargo test specs\n\n# Run a specific spec test\ncargo test spec::test_name\n```\n\n### Test Organization\n\n- **Spec tests** (`tests/specs/`) — Main integration tests\n- **Unit tests** — Inline with source code in each module\n- **Integration tests** (`tests/integration/`) — Additional integration tests\n- **WPT** (`tests/wpt/`) — Web Platform Tests for web standards compliance\n\n### Spec Tests\n\nThe main form of integration test is the \"spec\" test in `tests/specs/`. Each\ntest has a `__test__.jsonc` file describing CLI commands to run and expected\noutput. The schema is in `tests/specs/schema.json`.\n\nExample `__test__.jsonc`:\n\n```jsonc\n{\n \"tests\": {\n \"basic_case\": {\n \"args\": \"run main.ts\",\n \"output\": \"expected.out\"\n }\n }\n}\n```\n\nOutput assertions support wildcards:\n\n- `[WILDCARD]` — matches 0 or more characters (crosses newlines)\n- `[WILDLINE]` — matches to end of line\n- `[WILDCHAR]` — matches one character\n- `[WILDCHARS(N)]` — matches N characters\n- `[UNORDERED_START]` / `[UNORDERED_END]` — matches lines in any order\n\n## Git Workflow and Pull Requests\n\n### PR Title Linting\n\nPR titles are validated by CI (see `.github/workflows/pr.ts`). The title must\nfollow [Conventional Commits](https://www.conventionalcommits.org) and start\nwith one of these prefixes:\n\n- `feat:` — new features\n- `fix:` — bug fixes\n- `chore:` — maintenance tasks\n- `perf:` — performance improvements\n- `ci:` — CI changes\n- `cleanup:` — code cleanup\n- `docs:` — documentation\n- `bench:` — benchmarks\n- `build:` — build system changes\n- `refactor:` — refactoring\n- `test:` — test changes\n- `Revert` — reverting a previous commit\n- `Reland` — relanding a reverted commit\n- `BREAKING` — breaking changes\n\nAdditionally, deno_core/v8 upgrades must NOT use `chore:` — use `feat:`, `fix:`,\nor `refactor:` instead, with a title describing the actual change.\n\nRelease PRs (titles matching `X.Y.Z`) are also valid.\n\nThe validation script is at `tools/verify_pr_title.js`.\n\n### Workflow Rules\n\n- Create feature branches with descriptive names\n- Commit with clear, descriptive messages\n- Never force push — all commits are squashed on merge\n- Keep changes minimal and focused; avoid drive-by changes\n- Before committing, run `tools/format.js` and `tools/lint.js`\n\n## Development Workflows\n\n### Adding a New CLI Subcommand\n\n1. Define the command structure in `cli/args/flags.rs`\n2. Add the command handler in `cli/tools/.rs` or\n `cli/tools//mod.rs`\n3. Wire it up in `cli/main.rs`\n4. Add spec tests in `tests/specs//`\n\n### Modifying or Adding an Extension\n\n1. Navigate to `ext//`\n2. Rust code provides the ops exposed to JavaScript\n3. JavaScript code in the extension provides higher-level APIs\n4. Update `runtime/worker.rs` to register a new extension\n5. Add tests in the extension's directory\n\n## Debugging\n\n```bash\n# Verbose logging\nDENO_LOG=debug ./target/debug/deno run script.ts\n\n# Module-specific logging\nDENO_LOG=deno_core=debug ./target/debug/deno run script.ts\n\n# Full backtrace on panic\nRUST_BACKTRACE=1 ./target/debug/deno run script.ts\n\n# V8 inspector\n./target/debug/deno run --inspect-brk script.ts\n```\n\nIn Rust code: `eprintln!(\"Debug: {:?}\", var);` or `dbg!(var);`\n\n## Pull Request Reviews\n\n### Before commenting, verify your claims\n\n- If you claim something is missing (a stub, a test, error handling), search the\n full diff AND the existing codebase before commenting. Do not flag missing\n code that already exists elsewhere in the PR or the repository.\n- If you suggest a code change, verify it compiles and does not break the\n intended behavior. Do not suggest fixes that contradict the PR's stated goal.\n- Do not duplicate your own comments. If you already flagged an issue, do not\n post a second comment about the same thing.\n\n### Focus on high-value issues\n\nPrioritize these (in order):\n\n1. **Correctness bugs** — logic errors, race conditions (e.g. spurious wakeups\n on `Condvar`), use-after-free, null derefs\n2. **Public API leaks** — internal fields accidentally exposed in public return\n types\n3. **Security** — unsafe blocks with incorrect safety invariants, unsanitized\n inputs at system boundaries\n4. **Missing error handling** — errors silently swallowed where they should\n propagate, or propagated where they should be caught\n\nDo NOT comment on:\n\n- Style preferences already enforced by the project's formatter (dprint) and\n linter (clippy + deno lint)\n- Suggesting longer timeouts or shorter delays in tests without evidence of\n flakiness\n- Minor documentation wording unless it is actively misleading\n- Hypothetical edge cases that cannot realistically occur (e.g. a process having\n > 256 direct children)\n\n### Understand the runtime model before suggesting fixes\n\nDeno embeds V8 and uses a single-threaded async event loop (tokio). Code that\nlooks like a busy-spin may actually be required because:\n\n- `poll_sessions(None)` in the inspector drives async I/O — parking the thread\n prevents WebSocket close frames from being processed, causing deadlocks\n- The event loop must keep running for futures to make progress; blocking the\n main thread stops the I/O reactor\n- Some loops intentionally spin to allow the waker/poller to process events each\n iteration\n\nBefore suggesting `sleep`, `park`, or backoff in a polling loop, check whether\nthe loop body drives async I/O that would stall if the thread were blocked.\n\n### Trace through the actual code path, not just the function signature\n\nA common review mistake is looking at a function's local behavior without\ntracing its callers and the runtime context. For example:\n\n- A function that \"doesn't check field X\" may not need to because callers\n guarantee X is consumed before the check runs (e.g., `handshake` is always\n `take()`n at the top of `poll_sessions` before any session-count checks)\n- A heuristic that \"doesn't handle case Y\" may already handle it through a\n different code path (e.g., dotenv comment detection via `#` prefix check\n happens before the inner-quote fallback is reached)\n\n### Don't suggest fixes that introduce circular dependencies\n\nIn parsers and state machines, be careful not to suggest fixes that require\nknowing the answer to the question being solved. For example, suggesting \"detect\nwhere the comment starts before matching quotes\" is circular when the quote\nmatching is what determines where the value (and thus the comment) begins.\n\n### Verify suggestions against existing tests\n\nBefore suggesting a change, check whether the codebase already has test coverage\nfor the case in question. The `test_valid_env` test in `libs/dotenv/lib.rs`\ncovers many edge cases including inline comments with quotes\n(`EDGE_CASE_INLINE_COMMENTS`). Running existing tests before and after a\nsuggested change catches regressions.\n\n### Match existing patterns in the codebase\n\nWhen suggesting changes to a function, look for similar functions nearby that\nsolve analogous problems. If the existing pattern (e.g., `wait_for_session`)\nuses a specific flag/mechanism, understand why before suggesting a different\napproach for a similar function (e.g., `wait_for_sessions_disconnect`). The\ndifference may be intentional.\n\n### Deno-specific conventions\n\n- Ops use the `#[op2]` macro. Fast ops use `#[op2(fast)]`.\n- Internal symbols in JS (`ext/process/40_process.js`, `ext/node/polyfills/`)\n use the `k` prefix convention: `kIpc`, `kSerialization`, `kInputOption`. Flag\n deviations.\n- Node.js compatibility code is in `ext/node/polyfills/`. When reviewing these\n files, check behavior against Node.js docs, not just Deno conventions. Some\n patterns (like synchronous `throw` in `spawn()` for EPERM but async error\n event for ENOENT) are intentional Node.js compatibility.\n\n### When suggesting error handling changes\n\n- Check whether the function's callers expect the error to propagate or be\n swallowed. Do not suggest propagating errors in paths that are intentionally\n best-effort (e.g. killing already-exited processes).\n- When suggesting a specific error variant or code change, verify the types\n actually match. For example, `Option::or_else` takes `FnOnce() -> Option`,\n not `FnOnce(E) -> ...`.\n- If a Rust function returns `Result` and an `Option` is needed, use `.ok()`\n before `.or_else()` or `.unwrap_or()`.\n\n### Platform-specific code\n\n- `#[cfg(unix)]` code that calls `find_descendant_pids` or similar must have\n stubs for non-Linux/non-macOS Unix targets. Check that\n `#[cfg(all(unix, not(target_os = \"linux\"), not(target_os = \"macos\")))]` stubs\n exist before flagging missing platform support.\n- Windows `unsafe` blocks using `windows_sys` are common for process management.\n Verify handle cleanup (`CloseHandle`) but do not flag the `unsafe` usage\n itself.\n\n## Troubleshooting\n\n- **Slow compile times**: Use `cargo check`, `--bin deno`, or `sccache`\n- **Build failures on macOS**: Run `xcode-select --install`\n- **Build failures on Linux**: Install `build-essential`\n- **Spec test failures**: Check output diffs, use `[WILDCARD]` for\n non-deterministic parts\n- **Permission errors**: Ensure test files have correct permissions\n\n\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/marketplace.json)\n\n\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.claude-plugin/plugin.json)\n\n\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/denoland/deno/HEAD/.cursor/mcp.json)\n\n\n---\ndescription: \"Cursor rules for Deno development with integration techniques.\"\nglobs: **/*\nalwaysApply: false\n---\nThis project contains automation scripts and workflows for the @findhow packages, based on the original Deno automation repository. The goal is to provide consistent and efficient automation for the @findhow ecosystem.\n\nThe purpose of this project is to refactor and adapt the automation scripts from [denoland/automation](https://github.com/denoland/automation) for use with the configured @findhow package repositories.\n\nWhen working on this project, Cursor AI should:\n\nWhen making changes:\n\nWhen updating documentation:\n\nWhen creating or modifying automation scripts:\n\nRemember to thoroughly test all modifications to ensure they work correctly with the @findhow ecosystem before merging changes into the main branch.\n"}