novahiz 0.1.0

package/bundled-skills/dart-use-doc-examples/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: dart-use-doc-examples
+description: "How to inject external code examples into Dartdoc using the {@example} directive, and how to filter those files using #hide, #region, and #endregion tags."
+---
+
+# Using Examples in Dartdoc
+
+## Contents
+*   [1. The `{@example}` Directive](#1-the-example-directive)
+*   [2. Using Regions](#2-using-regions)
+*   [3. Hiding Setup Code](#3-hiding-setup-code)
+*   [4. Marker Filtering Rules](#4-marker-filtering-rules)
+*   [5. Placement and Path Resolution](#5-placement-and-path-resolution)
+*   [6. Verification](#6-verification)
+
+When writing documentation that requires multi-line code examples, you should generally extract those examples into standalone `.dart` files and inject them using the `{@example}` directive, rather than writing them inline inside `///` comments. This ensures the examples can be analyzed, linted, and executed.
+
+## 1. The `{@example}` Directive
+The `{@example}` directive parses an external file and resolves it into a fenced Markdown code block in the generated documentation.
+
+**Syntax:** `{@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}`
+
+*   **`<path>`**: The path to the file. A leading `/` evaluates from the package root. Otherwise, it is relative to the current file.
+*   **`lang`**: The language for the markdown fence. Auto-detected from the file extension (e.g., `dart`), but can be explicit (e.g., `lang=text`).
+*   **`indent`**: `strip` (default) aggressively removes shared leading indentation from the code block.
+
+*Bad (Inline Markdown):*
+```dart
+/// Makes a client service request to the backend.
+///
+/// ```dart
+/// final client = Client();
+/// client.send();
+/// ```
+```
+
+*Good (External File Injection):*
+```dart
+/// Makes a client service request to the backend.
+///
+/// {@example /example/client_request.dart}
+```
+
+## 2. Using Regions
+Often, an external example file contains imports, setup, or `void main()` wrappers that you don't want to show in the documentation. You can extract a specific block of code by appending `#<region>` to the `{@example}` directive path, and wrapping that code with `#region` and `#endregion` comments in the target file.
+
+**Dart Code (e.g., `/example/client.dart`):**
+```dart
+import 'package:http/http.dart';
+
+void main() {
+  // #region request_snippet
+  final client = Client();
+  client.send();
+  // #endregion request_snippet
+}
+```
+
+**Dartdoc Usage:**
+```dart
+/// Connects the client to the server and sends a request.
+///
+/// {@example /example/client.dart#request_snippet}
+```
+
+## 3. Hiding Setup Code
+If there is a specific line of code within your extracted region that is necessary for the compiler/analyzer to pass but irrelevant (or distracting) for the documentation reader, append `#hide` to that line.
+
+**Dart Code:**
+```dart
+final mockServer = startServer(); // #hide
+final data = await fetch(mockServer.url);
+```
+In the generated documentation, only `final data = await fetch(mockServer.url);` will be visible. The line with `#hide` is completely dropped.
+
+## 4. Marker Filtering Rules
+When working with `#hide`, `#region`, and `#endregion` markers, you must follow these two technical constraints:
+
+*   **Region Required:** The markers are only processed and stripped when you target a specific region suffix (e.g., `{@example file.dart#region_name}`). If you inject an entire file without a region suffix, the file is embedded exactly as it appears in the source, including any marker text like `// #hide`.
+*   **Format Agnosticism:** The marker system is completely format-agnostic. Dartdoc simply runs a regex to strip lines containing the marker strings, meaning it works identically in non-Dart files (e.g., inside YAML comments `# #region` or HTML comments `<!-- #region -->`).
+
+## 5. Placement and Path Resolution
+The `{@example}` directive is a block-level directive. It must appear on its own line prefixed with `///`. Its internal `<path>` parser follows strict URI reference rules:
+
+*   **Package-Root Paths (`/`)**: Paths starting with a leading slash automatically resolve directly to the root of the Dart package. Use this when the destination file is deep.
+    *   *Example:* `{@example /test/data/sample.txt}` exactly maps to `<package_root>/test/data/sample.txt`.
+*   **Relative Paths**: Paths without a leading slash resolve relative to the directory of the file containing the doc comment.
+    *   *Example:* `{@example ../utils/demo.dart}`
+*   **Boundary Enforcement:** Using `..` segments to traverse upward is perfectly acceptable, but dartdoc natively stops directory traversal at the package root (it will never escape the package).
+*   **No Network URLs:** Absolute URIs (e.g., starting with `https://`) are strictly not supported. The example file *must* sit natively somewhere in the local filesystem.
+*   **Separators & Encoding:** Because dartdoc resolves the path as a URI, you must always use forward slashes (`/`) as folder separators (even on Windows). You can natively include URI-encoded characters (like `%20` for spaces) as permitted by URI reference rules.
+
+## 6. Verification
+After injecting examples:
+1.  Run `dart analyze` on the example files to ensure the hidden setup code compiles.
+2.  (Optional) Run `dart doc` to verify that dartdoc successfully parsed the directive without throwing a "Failed to read file" or "missing region" warning.

package/bundled-skills/dart-use-ffigen/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: dart-use-ffigen
+description: Guide agents to use `package:ffigen` to automatically generate FFI bindings instead of writing them manually. Use this skill when a task involves writing new FFI bindings, extending C/Objective-C/Swift integrations, or replacing hand-crafted `dart:ffi` setups.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 28 May 2026 07:21:07 GMT
+---
+# Generating FFI Bindings using package:ffigen
+
+## Contents
+- [Introduction](#introduction)
+- [Constraints](#constraints)
+- [FFIgen Overview](#ffigen-overview)
+- [Step-by-Step Workflow](#step-by-step-workflow)
+- [Concrete Example: Binding a C Library](#concrete-example-binding-a-c-library)
+- [Verification Checklist](#verification-checklist)
+
+## Introduction
+
+Automate and standardize the generation of FFI bindings using `package:ffigen` (`FfiGenerator`). Writing FFI bindings by hand is error-prone, brittle, and highly discouraged.
+
+## Constraints
+
+*   **No Hand-Written FFI Bindings**: If native headers (`.h` files) exist or are generated by a build step, never write manual `DynamicLibrary.lookup`, `@Native` external functions, or raw struct classes. Always use `FfiGenerator` to generate them.
+*   **Generator Location**: The generator script should be located at `tool/ffigen.dart` within the target package root.
+*   **Header Location**: If the native header files are third-party, they should be located in `third_party/` within the target package (otherwise placing them in a `src/` directory at the package root is also acceptable). If the headers are not in one of these standard locations, notify the user that it would be cleaner to move the header files to the standard location (e.g., `third_party/`).
+*   **Targeted Inclusion Filters**: Avoid importing an entire native library unless specifically needed. Always apply precise inclusion lists using positive matches to minimize the size and cognitive load of the generated code (e.g., using `Functions.includeSet` or filtering matches in `include` closures).
+*   **Output Setup**: If the generated FFI bindings interface with a third-party library (or reference third-party headers), the generated files must always be placed under `lib/src/third_party/`. The primary generated FFI bindings file must strictly use the `.g.dart` extension (e.g. `sqlite3.g.dart`).
+*   **Preamble & License Headers**: Always supply a premium `preamble` in the `Output` class to specify the license. This must match the native third-party library's license, explicitly include the copyright header of the target native header file, and contain an automatic generation warning (e.g. `// Generated by package:ffigen. Do not edit manually.`).
+*   **No Unnecessary Commits of Stale Bindings**: Ensure you run the generator script and check if the generated files have changed *before* finishing your task. Always verify the package by running `dart analyze`.
+*   **Record Usage and Tree Shaking**: If the package is integrated into standard runtime execution or compiles native assets via native hooks:
+    *   Enable recorded usage on all functions by setting `recordUse: (_) => true` under `Functions`.
+    *   Specify the `recordUseMapping` target in `Output` (which must strictly be a `.g.dart` file under `lib/src/third_party/`, e.g. `lib/src/third_party/sqlite3.record_use_mapping.g.dart`) to register bindings for symbol tree shaking.
+
+## FFIgen Overview
+
+To construct the programmatic generator, use the core configuration objects imported from `package:ffigen/ffigen.dart`:
+
+### 1. `FfiGenerator`
+The parent class that orchestrates the configuration, parsing, and code generation.
+```dart
+FfiGenerator({
+  Headers headers = const Headers(),
+  Enums enums = Enums.excludeAll,
+  Functions functions = Functions.excludeAll,
+  Globals globals = Globals.excludeAll,
+  Integers integers = const Integers(),
+  Macros macros = Macros.excludeAll,
+  Structs structs = Structs.excludeAll,
+  Typedefs typedefs = Typedefs.excludeAll,
+  Unions unions = Unions.excludeAll,
+  UnnamedEnums unnamedEnums = UnnamedEnums.excludeAll,
+  ObjectiveC? objectiveC,
+  required Output output,
+}).generate();
+```
+
+### 2. `Headers`
+Configures Clang header parsing targets and compiler flags.
+*   `entryPoints`: A list of target header `Uri` inputs.
+*   `include`: A filter function `bool Function(Uri header)` that handles transitive header imports.
+*   `compilerOptions`: Custom preprocessor/include compiler flags to pass directly to libclang.
+*   `ignoreSourceErrors`: Set to `true` to silence errors occurring inside third-party headers during parsing.
+
+### 3. `Functions`
+Specifies which native C/C++ functions to expose in Dart.
+*   `include`: A matcher function (e.g. `(decl) => {'my_func'}.contains(decl.originalName)` or `Functions.includeSet({'my_func'})`).
+*   `isLeaf`: Declares functions as leaf functions (`(decl) => true`) if they do not call back into Dart or block thread execution.
+*   `recordUse`: Enables metadata generation for native asset tree shaking (essential in `dart-lang/native`). Set to `(_) => true`.
+
+### 4. `Output`
+Configures target generated files.
+*   `dartFile`: Target `Uri` where the primary FFI bindings will be written.
+*   `recordUseMapping`: Target `Uri` for recorded usage metadata maps (crucial for linking-time tree shaking).
+*   `preamble`: Text inserted at the top of the generated file (licensing, annotations).
+*   `format`: Set to `true` to run the Dart formatter automatically.
+
+## Step-by-Step Workflow
+
+### Step 1: Check/Add Dependencies
+Open the package's `pubspec.yaml` and verify the `dev_dependencies` contains `ffigen`. Use the Dart MCP server or look up the latest version on [pub.dev](https://pub.dev/packages/ffigen) (e.g., `^20.1.1`).
+
+You can add it automatically using the CLI:
+```bash
+dart pub add dev:ffigen
+```
+
+### Step 2: Formulate Paths Dynamically
+Create a programmatic generator script under the package's `tool/` directory (e.g., `tool/ffigen.dart`).
+Resolve paths relative to `Platform.script` to make sure it runs successfully from any working directory:
+
+```dart
+final packageRoot = Platform.script.resolve('../');
+final headerFile = packageRoot.resolve('third_party/library.h');
+final targetBindings = packageRoot.resolve('lib/src/third_party/bindings.g.dart');
+```
+
+### Step 3: Write the Script (`tool/ffigen.dart`)
+Define `void main()` and run `FfiGenerator` with dynamic options (see complete example below).
+
+### Step 4: Run Code Generation
+Execute the script from the terminal inside the target package folder:
+```bash
+dart run tool/ffigen.dart
+```
+
+### Step 5: Static Analysis
+Verify that the generated bindings are correct and resolve any analysis issues. FFIgen automatically runs the Dart formatter on the output file (via `format: true` configuration), so manual formatting is not required.
+
+1.  Run the static analyzer inside the target package:
+    ```bash
+    dart analyze
+    ```
+2.  **Addressing Warnings/Lints**: If `dart analyze` reports style or lint warnings inside the generated file, append the corresponding warning codes to the `ignore_for_file:` list in your generator script's `preamble` configuration (e.g., adding `camel_case_types`, `non_constant_identifier_names`, etc.). Do not modify the package's global rules.
+3.  **Addressing Compilation Errors**: If `dart analyze` reports actual compiler or analysis errors (not warnings) inside the generated file, do not attempt to edit the generated file manually. Report these error details directly to the user so they can file an issue on the repository at [github.com/dart-lang/native](https://github.com/dart-lang/native).
+
+
+## Concrete Example: Binding a C Library
+
+Let's assume we are working with the SQLite package under `pkgs/code_assets/example/sqlite`, which embeds SQLite C library sources inside `third_party/sqlite/` and accesses it via FFI.
+
+### The C Header File (`third_party/sqlite/sqlite3.h`)
+```c
+// The author disclaims copyright to this source code.
+
+#ifndef SQLITE3_H_
+#define SQLITE3_H_
+
+const char *sqlite3_libversion(void);
+
+#endif // SQLITE3_H_
+```
+
+### BEFORE: Manual FFI Binding (The Anti-Pattern)
+A developer might attempt to handcraft this integration. It is fragile, blocks tree-shaking metadata, and is highly prone to ABI and structural mapping issues:
+
+```dart
+// lib/src/sqlite3_manual.dart
+import 'dart:ffi' as ffi;
+import 'package:ffi/ffi.dart';
+
+// Flaw 1: Hardcoded DynamicLibrary lookup blocks integration with modern native asset compilation.
+final ffi.DynamicLibrary _dylib = ffi.DynamicLibrary.open('libsqlite3.so');
+
+// Flaw 2: Manual function type matching requires writing redundant dynamic lookup boilerplate and lacks tree-shaking metadata.
+typedef _sqlite3_libversion_C = ffi.Pointer<ffi.Char> Function();
+typedef _sqlite3_libversion_Dart = ffi.Pointer<ffi.Char> Function();
+
+final _sqlite3_libversion_Dart sqlite3LibVersion = _dylib
+    .lookup<ffi.NativeFunction<_sqlite3_libversion_C>>('sqlite3_libversion')
+    .asFunction();
+```
+
+### AFTER: Generating via FFIgen (The Correct Pattern)
+
+Create a programmatic script at `tool/ffigen.dart`:
+
+```dart
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+import 'package:ffigen/ffigen.dart';
+
+void main() {
+  // Resolve paths dynamically relative to Platform.script
+  final packageRoot = Platform.script.resolve('../');
+  final entryHeader = packageRoot.resolve('third_party/sqlite/sqlite3.h');
+  final bindingsOutput = packageRoot.resolve('lib/src/third_party/sqlite3.g.dart');
+  final treeShakeMapping = packageRoot.resolve('lib/src/third_party/sqlite3.record_use_mapping.g.dart');
+
+  FfiGenerator(
+    headers: Headers(
+      entryPoints: [entryHeader],
+    ),
+    functions: Functions(
+      include: (decl) => {'sqlite3_libversion'}.contains(decl.originalName),
+      // Essential for package optimization and tree-shaking
+      recordUse: (_) => true,
+    ),
+    output: Output(
+      dartFile: bindingsOutput,
+      recordUseMapping: treeShakeMapping,
+      format: true,
+      preamble: '''
+
+// AUTO-GENERATED FILE - DO NOT MODIFY.
+// Generated via ffigen.
+// To regenerate: dart run tool/ffigen.dart
+
+// ignore_for_file: type=lint, unused_import, unused_element, deprecated_member_use_from_same_package, experimental_member_use
+''',
+    ),
+  ).generate();
+
+  print('Successfully generated sqlite3 FFI bindings.');
+}
+```
+
+### Running the Generator script
+Run this in the package root directory:
+```bash
+dart run tool/ffigen.dart
+```
+
+This will automatically create:
+1.  `lib/src/third_party/sqlite3.g.dart`
+2.  `lib/src/third_party/sqlite3.record_use_mapping.g.dart`
+
+## Verification Checklist
+
+Always perform the following verification before completing a binding generation task:
+
+1.  **Correct Setup**: Verify the target generated files are inside `lib/src/third_party/` (required for third-party licensed code) and the primary FFI bindings file strictly uses the `.g.dart` extension.
+2.  **Static Analysis**: Run `dart analyze` and ensure there are zero compiler/analyzer errors or warnings in the package.
+    *   If static warnings are reported in the generated bindings, suppress them by adding `ignore_for_file` rules to the generator's `preamble` configuration (do not modify global package rules).
+    *   If actual compiler or analyzer errors are reported in the generated bindings, do not edit the generated file manually. Report the details to the user and direct them to file an issue at [github.com/dart-lang/native](https://github.com/dart-lang/native).

package/bundled-skills/dart-use-pattern-matching/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: dart-use-pattern-matching
+description: Use switch expressions and pattern matching where appropriate
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Fri, 24 Apr 2026 15:08:55 GMT
+---
+# Implementing Dart Patterns
+
+## Contents
+- [Pattern Selection Strategy](#pattern-selection-strategy)
+- [Switch Statements vs. Expressions](#switch-statements-vs-expressions)
+- [Core Pattern Implementations](#core-pattern-implementations)
+- [Workflows](#workflows)
+- [Examples](#examples)
+
+## Pattern Selection Strategy
+
+Apply specific pattern types based on the data structure and desired outcome. Follow these conditional guidelines:
+
+*   **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns to simultaneously check structure and destructure key-value pairs.
+*   **If handling multiple return values:** Use Record patterns to destructure fields directly into local variables.
+*   **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns combined with `sealed` classes to ensure exhaustiveness.
+*   **If matching numeric ranges or conditions:** Use Relational (`>=`, `<=`) and Logical-and (`&&`) patterns.
+*   **If multiple cases share logic:** Use Logical-or (`||`) patterns to share a single case body or guard clause.
+*   **If ignoring specific values:** Use the Wildcard pattern (`_`) or a non-matching Rest element (`...`) in collections.
+
+## Switch Statements vs. Expressions
+
+Select the appropriate switch construct based on the execution context:
+
+*   **If producing a value:** Use a **switch expression**.
+    *   Syntax: `switch (value) { pattern => expression, }`
+    *   Rule: Each case must be a single expression. No implicit fallthrough. Must be exhaustive.
+*   **If executing statements or side effects:** Use a **switch statement**.
+    *   Syntax: `switch (value) { case pattern: statements; }`
+    *   Rule: Empty cases fall through to the next case. Non-empty cases implicitly break (no `break` keyword required).
+
+## Core Pattern Implementations
+
+Implement patterns using the following syntax and rules:
+
+*   **Logical-or (`||`):** `pattern1 || pattern2`. Both branches must define the exact same set of variables.
+*   **Logical-and (`&&`):** `pattern1 && pattern2`. Branches must *not* define overlapping variables.
+*   **Relational:** `==`, `!=`, `<`, `>`, `<=`, `>=` followed by a constant expression.
+*   **Cast (`as`):** `pattern as Type`. Throws if the value does not match the type. Use to forcibly assert types during destructuring.
+*   **Null-check (`?`):** `pattern?`. Fails the match if the value is null. Binds the variable to the non-nullable base type.
+*   **Null-assert (`!`):** `pattern!`. Throws if the value is null.
+*   **Variable:** `var name` or `Type name`. Binds the matched value to a new local variable.
+*   **Wildcard (`_`):** Matches any value and discards it.
+*   **List:** `[pattern1, pattern2]`. Matches lists of exact length unless a Rest element (`...` or `...var rest`) is used.
+*   **Map:** `{"key": pattern}`. Matches maps containing the specified keys. Ignores unmatched keys.
+*   **Record:** `(pattern1, named: pattern2)`. Matches records of the exact shape. Use `:var name` to infer the getter name.
+*   **Object:** `ClassName(field: pattern)`. Matches instances of `ClassName`. Use `:var field` to infer the getter name.
+
+## Workflows
+
+### Task Progress: Implementing Pattern Matching
+Copy this checklist to track progress when implementing complex pattern matching logic:
+
+- [ ] Identify the data structure being evaluated (JSON, Record, Class, Enum).
+- [ ] Select the appropriate switch construct (Expression for values, Statement for side-effects).
+- [ ] Define the required patterns (Object, Map, List, Record).
+- [ ] Extract required data using Variable patterns (`var x`, `:var y`).
+- [ ] Apply Guard clauses (`when condition`) for logic that cannot be expressed via patterns.
+- [ ] Handle unmatched cases using a Wildcard (`_`) or `default` clause (if not using a sealed class).
+- [ ] Run exhaustiveness validator.
+
+### Feedback Loop: Exhaustiveness Checking
+When switching over `sealed` classes or enums, you must ensure all subtypes are handled.
+
+1. **Run validator:** Execute `dart analyze`.
+2. **Review errors:** Look for "The type 'X' is not exhaustively matched by the switch cases" errors.
+3. **Fix:** Add the missing Object patterns for the unhandled subtypes, or add a Wildcard (`_`) case if a default fallback is acceptable.
+
+## Examples
+
+### JSON Validation and Destructuring
+Use Map and List patterns to validate structure and extract data in a single step.
+
+**Input:**
+```dart
+var data = {
+  'user': ['Lily', 13],
+};
+```
+
+**Implementation:**
+```dart
+if (data case {'user': [String name, int age]}) {
+  print('User $name is $age years old.');
+} else {
+  print('Invalid JSON structure.');
+}
+```
+
+### Algebraic Data Types (Sealed Classes)
+Use Object patterns with switch expressions to handle family types exhaustively.
+
+**Implementation:**
+```dart
+sealed class Shape {}
+
+class Square implements Shape {
+  final double length;
+  Square(this.length);
+}
+
+class Circle implements Shape {
+  final double radius;
+  Circle(this.radius);
+}
+
+// Switch expression guarantees exhaustiveness due to `sealed` modifier.
+double calculateArea(Shape shape) => switch (shape) {
+  Square(length: var l) => l * l,
+  Circle(:var radius)   => math.pi * radius * radius,
+};
+```
+
+### Variable Swapping and Destructuring
+Use variable assignment patterns to swap values or extract record fields without temporary variables.
+
+**Implementation:**
+```dart
+var (a, b) = ('left', 'right');
+(b, a) = (a, b); // Swap values
+
+// Destructuring a function return
+var (name, age) = getUserInfo();
+```
+
+### Guard Clauses and Logical-or
+Use `when` to evaluate arbitrary conditions after a pattern matches.
+
+**Implementation:**
+```dart
+switch (shape) {
+  case Square(size: var s) || Circle(size: var s) when s > 0:
+    print('Valid symmetric shape with size $s');
+  case Square() || Circle():
+    print('Invalid or empty shape');
+  default:
+    print('Unknown shape');
+}
+```