@nockdev/awf 6.2.0

package/.agent/skills/languages/zig/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: zig
+detect: ["*.zig", "build.zig", "build.zig.zon"]
+version: "6.1.2"
+category: systems
+tier: 2
+---
+
+# Zig Patterns — DOMYH Awesome Code
+
+> **Version**: Zig 0.13+ (2025-2026)
+> **Focus**: Systems programming, C interop, WebAssembly
+> **Philosophy**: Simple, explicit, no hidden control flow
+
+---
+
+## 🎯 When to Use This Skill
+
+Use for: Systems programming, game engines, embedded, C replacement.
+**NOT for**: Web APIs (→ go), ML (→ python), mobile (→ flutter).
+
+---
+
+## 📦 Why Zig?
+
+| Feature        | Zig            | C          | Rust           |
+| -------------- | -------------- | ---------- | -------------- |
+| Memory safety  | Runtime checks | None       | Compile-time   |
+| C interop      | Native 🏆      | N/A        | FFI            |
+| Compile time   | Comptime 🏆    | Macros     | Const generics |
+| Build system   | Built-in 🏆    | Make/CMake | Cargo          |
+| Learning curve | Low            | Low        | High           |
+
+---
+
+## 🔧 Project Setup
+
+```bash
+# Create new project
+mkdir my-project && cd my-project
+zig init
+
+# Project structure
+my-project/
+├── build.zig         # Build configuration
+├── build.zig.zon     # Dependencies
+└── src/
+    └── main.zig      # Entry point
+```
+
+### build.zig
+
+```zig
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe = b.addExecutable(.{
+        .name = "myapp",
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    b.installArtifact(exe);
+
+    // Run step
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+
+    const run_step = b.step("run", "Run the app");
+    run_step.dependOn(&run_cmd.step);
+
+    // Test step
+    const tests = b.addTest(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const test_step = b.step("test", "Run tests");
+    test_step.dependOn(&b.addRunArtifact(tests).step);
+}
+```
+
+---
+
+## 🔄 Core Patterns
+
+### Error Handling
+
+```zig
+const std = @import("std");
+
+// ✅ Error union return type
+fn readFile(path: []const u8) ![]u8 {
+    const file = try std.fs.cwd().openFile(path, .{});
+    defer file.close();
+
+    return try file.readToEndAlloc(std.heap.page_allocator, 1024 * 1024);
+}
+
+// ✅ Custom error sets
+const FileError = error{
+    NotFound,
+    PermissionDenied,
+    TooBig,
+};
+
+fn processFile(path: []const u8) FileError!void {
+    const stat = std.fs.cwd().statFile(path) catch |err| {
+        return switch (err) {
+            error.FileNotFound => error.NotFound,
+            error.AccessDenied => error.PermissionDenied,
+            else => error.NotFound,
+        };
+    };
+
+    if (stat.size > 100 * 1024 * 1024) {
+        return error.TooBig;
+    }
+}
+
+// ✅ Error handling patterns
+pub fn main() !void {
+    // Try with fallback
+    const data = readFile("config.json") catch |err| {
+        std.debug.print("Error: {}\n", .{err});
+        return;
+    };
+    defer std.heap.page_allocator.free(data);
+
+    // Propagate error
+    const result = try processFile("input.txt");
+    _ = result;
+}
+```
+
+### Memory Management
+
+```zig
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+
+// ✅ Explicit allocator pattern
+const User = struct {
+    name: []const u8,
+    email: []const u8,
+    allocator: Allocator,
+
+    pub fn init(allocator: Allocator, name: []const u8, email: []const u8) !User {
+        return User{
+            .name = try allocator.dupe(u8, name),
+            .email = try allocator.dupe(u8, email),
+            .allocator = allocator,
+        };
+    }
+
+    pub fn deinit(self: *User) void {
+        self.allocator.free(self.name);
+        self.allocator.free(self.email);
+    }
+};
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    var user = try User.init(allocator, "John", "john@example.com");
+    defer user.deinit();
+
+    std.debug.print("User: {s}\n", .{user.name});
+}
+```
+
+### Comptime (Compile-Time Execution)
+
+```zig
+const std = @import("std");
+
+// ✅ Compile-time type generation
+fn Matrix(comptime T: type, comptime rows: usize, comptime cols: usize) type {
+    return struct {
+        data: [rows][cols]T,
+
+        const Self = @This();
+
+        pub fn init() Self {
+            return .{ .data = std.mem.zeroes([rows][cols]T) };
+        }
+
+        pub fn get(self: Self, row: usize, col: usize) T {
+            return self.data[row][col];
+        }
+
+        pub fn set(self: *Self, row: usize, col: usize, value: T) void {
+            self.data[row][col] = value;
+        }
+    };
+}
+
+// ✅ Compile-time string processing
+fn parseFormatString(comptime fmt: []const u8) usize {
+    var count: usize = 0;
+    var i: usize = 0;
+    while (i < fmt.len) : (i += 1) {
+        if (fmt[i] == '{' and i + 1 < fmt.len and fmt[i + 1] == '}') {
+            count += 1;
+            i += 1;
+        }
+    }
+    return count;
+}
+
+// Usage
+const Mat3x3 = Matrix(f32, 3, 3);
+const arg_count = parseFormatString("Hello {} from {}!");  // 2 at compile time
+
+pub fn main() void {
+    var m = Mat3x3.init();
+    m.set(1, 1, 5.0);
+    std.debug.print("Value: {}\n", .{m.get(1, 1)});
+    std.debug.print("Args: {}\n", .{arg_count});
+}
+```
+
+---
+
+## 🔗 C Interop
+
+```zig
+const std = @import("std");
+const c = @cImport({
+    @cInclude("stdio.h");
+    @cInclude("stdlib.h");
+});
+
+pub fn main() void {
+    // ✅ Call C functions directly
+    _ = c.printf("Hello from C!\n");
+
+    // ✅ Use C types
+    const ptr: [*c]c.char = c.malloc(100);
+    defer c.free(ptr);
+
+    // ✅ Pass Zig strings to C
+    const message = "Zig to C";
+    _ = c.printf("%s\n", message.ptr);
+}
+```
+
+### Linking C Libraries
+
+```zig
+// build.zig
+exe.linkLibC();
+exe.linkSystemLibrary("sqlite3");
+exe.addIncludePath("/usr/include");
+```
+
+---
+
+## 🌐 WebAssembly
+
+```zig
+// src/wasm.zig
+
+// Export function to JavaScript
+export fn add(a: i32, b: i32) i32 {
+    return a + b;
+}
+
+export fn greet(name_ptr: [*]const u8, name_len: usize) void {
+    const name = name_ptr[0..name_len];
+    // Process name...
+}
+
+// Import from JavaScript
+extern fn consoleLog(ptr: [*]const u8, len: usize) void;
+
+fn log(message: []const u8) void {
+    consoleLog(message.ptr, message.len);
+}
+```
+
+```bash
+# Build for WASM
+zig build-lib src/wasm.zig -target wasm32-freestanding -O ReleaseSmall
+```
+
+---
+
+## 🧪 Testing
+
+```zig
+const std = @import("std");
+const testing = std.testing;
+
+fn add(a: i32, b: i32) i32 {
+    return a + b;
+}
+
+test "add positive numbers" {
+    try testing.expectEqual(@as(i32, 5), add(2, 3));
+}
+
+test "add negative numbers" {
+    try testing.expectEqual(@as(i32, -1), add(1, -2));
+}
+
+test "memory allocation" {
+    const allocator = testing.allocator;
+    const list = try allocator.alloc(u8, 100);
+    defer allocator.free(list);
+
+    try testing.expect(list.len == 100);
+}
+```
+
+```bash
+# Run tests
+zig build test
+```
+
+---
+
+## ✅ Production Checklist
+
+### Code Quality
+
+- [ ] No undefined behavior
+- [ ] All allocations paired with free
+- [ ] Error handling complete
+- [ ] Comptime where possible
+
+### Performance
+
+- [ ] Release build optimized
+- [ ] No debug allocator in prod
+- [ ] Profile with `-O ReleaseFast`
+- [ ] SIMD for hot paths
+
+### Safety
+
+- [ ] Bounds checks appropriate
+- [ ] No use-after-free
+- [ ] Null checks on optionals
+
+---
+
+_DOMYH Awesome Code • Zig 0.13+_

package/.agent/skills/languages/zig/data/async.yaml

@@ -0,0 +1,314 @@
+# =============================================================================
+# Zig Async Patterns (Feb 2026)
+# Version: Zig 0.14+
+# =============================================================================
+
+metadata:
+  skill: zig
+  domain: async
+  version: "0.14"
+  updated: "2026-02-05"
+  patterns_count: 5
+
+patterns:
+  - id: zig101
+    name: Async/Await (deprecated)
+    category: concurrency
+    version: "Zig 0.11"
+    description: |
+      NOTE: Async removed in 0.12. Use threads or io_uring.
+      Legacy pattern for reference.
+    text: async await suspend resume frame
+    example: |
+      // ⚠️ ASYNC REMOVED in Zig 0.12+
+      // This is legacy code for reference only
+
+      // ✅ Modern alternative: io_uring or threads
+      const std = @import("std");
+
+      // Use std.Thread for concurrency
+      fn modernConcurrency() !void {
+          var threads: [4]std.Thread = undefined;
+          
+          for (&threads, 0..) |*thread, i| {
+              thread.* = try std.Thread.spawn(.{}, worker, .{i});
+          }
+          
+          for (threads) |thread| {
+              thread.join();
+          }
+      }
+
+      fn worker(id: usize) void {
+          std.debug.print("Worker {} running\n", .{id});
+      }
+
+      // ✅ For high-performance I/O, use io_uring (Linux)
+      // or platform-specific async I/O
+
+      // ✅ Alternative: Zig's std.event.Loop (being redesigned)
+      // Check latest Zig documentation for updates
+    severity: LOW
+    docs_url: https://ziglang.org/documentation/master/
+
+  - id: zig102
+    name: Build System
+    category: build
+    version: "Zig"
+    description: |
+      build.zig for project configuration.
+      Dependencies, cross-compilation.
+    text: build.zig build system package dependencies
+    example: |
+      const std = @import("std");
+
+      pub fn build(b: *std.Build) void {
+          // ✅ Standard target and optimization
+          const target = b.standardTargetOptions(.{});
+          const optimize = b.standardOptimizeOption(.{});
+          
+          // ✅ Main executable
+          const exe = b.addExecutable(.{
+              .name = "myapp",
+              .root_source_file = b.path("src/main.zig"),
+              .target = target,
+              .optimize = optimize,
+          });
+          
+          // ✅ Link C library
+          exe.linkSystemLibrary("sqlite3");
+          exe.linkLibC();
+          
+          // ✅ Add dependency (build.zig.zon)
+          const clap = b.dependency("clap", .{
+              .target = target,
+              .optimize = optimize,
+          });
+          exe.root_module.addImport("clap", clap.module("clap"));
+          
+          // ✅ Install artifact
+          b.installArtifact(exe);
+          
+          // ✅ Run step
+          const run_cmd = b.addRunArtifact(exe);
+          run_cmd.step.dependOn(b.getInstallStep());
+          
+          if (b.args) |args| {
+              run_cmd.addArgs(args);
+          }
+          
+          const run_step = b.step("run", "Run the app");
+          run_step.dependOn(&run_cmd.step);
+          
+          // ✅ Test step
+          const tests = b.addTest(.{
+              .root_source_file = b.path("src/main.zig"),
+              .target = target,
+              .optimize = optimize,
+          });
+          
+          const test_step = b.step("test", "Run tests");
+          test_step.dependOn(&b.addRunArtifact(tests).step);
+      }
+    severity: HIGH
+    docs_url: https://ziglang.org/documentation/master/#Build-System
+
+  - id: zig103
+    name: C Interop
+    category: ffi
+    version: "Zig"
+    description: |
+      Seamless C library integration.
+      @cImport, translate-c, linking.
+    text: c interop ffi cimport translate extern
+    example: |
+      const std = @import("std");
+
+      // ✅ Import C headers directly
+      const c = @cImport({
+          @cInclude("stdio.h");
+          @cInclude("stdlib.h");
+          @cInclude("mylib.h");
+      });
+
+      pub fn main() void {
+          // ✅ Call C functions
+          _ = c.printf("Hello from C!\n");
+          
+          // ✅ Use C types
+          var ptr: [*c]c.char = c.malloc(100);
+          defer c.free(ptr);
+          
+          // ✅ Pass Zig strings to C
+          const zig_str = "Hello";
+          _ = c.puts(zig_str.ptr);  // .ptr gives [*:0]u8
+      }
+
+      // ✅ Export Zig functions to C
+      export fn add_numbers(a: c_int, b: c_int) c_int {
+          return a + b;
+      }
+
+      // ✅ Extern C function declarations
+      extern "c" fn external_func(x: c_int) c_int;
+
+      // ✅ Packed structs for C compatibility
+      const CStruct = extern struct {
+          field1: c_int,
+          field2: c_uint,
+          field3: [32]u8,
+      };
+
+      // ✅ Build.zig linking
+      // exe.linkSystemLibrary("openssl");
+      // exe.addIncludePath(.{ .path = "/usr/include" });
+      // exe.addLibraryPath(.{ .path = "/usr/lib" });
+
+      // ✅ Translate-c output
+      // zig translate-c header.h > bindings.zig
+    severity: HIGH
+    docs_url: https://ziglang.org/documentation/master/#C-Interop
+
+  - id: zig104
+    name: Thread Pool
+    category: concurrency
+    version: "Zig"
+    description: |
+      Standard library thread pool.
+      Parallel work distribution.
+    text: thread pool parallel concurrent worker
+    example: |
+      const std = @import("std");
+
+      // ✅ Use standard library thread pool
+      pub fn parallelProcess(items: []Item) !void {
+          var pool: std.Thread.Pool = undefined;
+          try pool.init(.{
+              .allocator = allocator,
+              .n_jobs = null,  // Uses available CPUs
+          });
+          defer pool.deinit();
+          
+          // ✅ Spawn parallel work
+          for (items, 0..) |item, i| {
+              pool.spawn(processItem, .{item, i});
+          }
+          
+          // Wait for completion
+          pool.wait();
+      }
+
+      fn processItem(item: Item, index: usize) void {
+          std.debug.print("Processing item {}\n", .{index});
+          // Do work...
+      }
+
+      // ✅ Manual thread management
+      fn manualThreads() !void {
+          const cpu_count = try std.Thread.getCpuCount();
+          var threads = try allocator.alloc(std.Thread, cpu_count);
+          defer allocator.free(threads);
+          
+          for (threads, 0..) |*t, i| {
+              t.* = try std.Thread.spawn(.{}, worker, .{i});
+          }
+          
+          for (threads) |t| {
+              t.join();
+          }
+      }
+
+      // ✅ Thread-safe data with Mutex
+      var mutex = std.Thread.Mutex{};
+      var shared_data: u64 = 0;
+
+      fn safeIncrement() void {
+          mutex.lock();
+          defer mutex.unlock();
+          shared_data += 1;
+      }
+
+      // ✅ Atomic operations
+      var counter = std.atomic.Value(u64).init(0);
+
+      fn atomicIncrement() void {
+          _ = counter.fetchAdd(1, .seq_cst);
+      }
+    severity: MEDIUM
+    docs_url: https://ziglang.org/documentation/master/#Thread-Pool
+
+  - id: zig105
+    name: I/O Patterns
+    category: io
+    version: "Zig"
+    description: |
+      File and network I/O patterns.
+      Buffered I/O, memory mapping.
+    text: io file network buffered reader writer
+    example: |
+      const std = @import("std");
+
+      // ✅ File I/O
+      fn readFile(path: []const u8) ![]u8 {
+          const file = try std.fs.cwd().openFile(path, .{});
+          defer file.close();
+          
+          // Read entire file
+          return file.readToEndAlloc(allocator, 10 * 1024 * 1024);
+      }
+
+      // ✅ Buffered writer
+      fn writeBuffered(path: []const u8, data: []const u8) !void {
+          const file = try std.fs.cwd().createFile(path, .{});
+          defer file.close();
+          
+          var buffered = std.io.bufferedWriter(file.writer());
+          try buffered.writer().writeAll(data);
+          try buffered.flush();
+      }
+
+      // ✅ Line-by-line reading
+      fn processLines(path: []const u8) !void {
+          const file = try std.fs.cwd().openFile(path, .{});
+          defer file.close();
+          
+          var reader = std.io.bufferedReader(file.reader());
+          var line_buf: [4096]u8 = undefined;
+          
+          while (reader.reader().readUntilDelimiter(&line_buf, '\n')) |line| {
+              std.debug.print("{s}\n", .{line});
+          } else |err| {
+              if (err != error.EndOfStream) return err;
+          }
+      }
+
+      // ✅ TCP client
+      fn tcpClient(host: []const u8, port: u16) !void {
+          const stream = try std.net.tcpConnectToHost(allocator, host, port);
+          defer stream.close();
+          
+          try stream.writer().writeAll("GET / HTTP/1.1\r\n\r\n");
+          
+          var buf: [4096]u8 = undefined;
+          const n = try stream.read(&buf);
+          std.debug.print("Received: {s}\n", .{buf[0..n]});
+      }
+
+      // ✅ TCP server
+      fn tcpServer(port: u16) !void {
+          var server = std.net.StreamServer.init(.{});
+          defer server.deinit();
+          
+          try server.listen(std.net.Address.parseIp("0.0.0.0", port) catch unreachable);
+          
+          while (true) {
+              if (server.accept()) |conn| {
+                  defer conn.stream.close();
+                  // Handle connection
+              } else |err| {
+                  std.debug.print("Accept error: {}\n", .{err});
+              }
+          }
+      }
+    severity: MEDIUM
+    docs_url: https://ziglang.org/documentation/master/#IO