aigroup-workflow 2.1.2 → 2.2.1

package/skills/go-rust-cpp/rust-engineer/references/traits.md

@@ -0,0 +1,413 @@
+# Traits, Generics, and Type System
+
+## Basic Trait Definition
+
+```rust
+// Simple trait
+trait Drawable {
+    fn draw(&self);
+}
+
+// Trait with default implementation
+trait Describable {
+    fn describe(&self) -> String {
+        String::from("No description available")
+    }
+}
+
+// Implementing traits
+struct Circle {
+    radius: f64,
+}
+
+impl Drawable for Circle {
+    fn draw(&self) {
+        println!("Drawing circle with radius {}", self.radius);
+    }
+}
+
+impl Describable for Circle {
+    fn describe(&self) -> String {
+        format!("A circle with radius {}", self.radius)
+    }
+}
+```
+
+## Associated Types
+
+```rust
+// Associated types vs generic parameters
+trait Container {
+    type Item;
+
+    fn add(&mut self, item: Self::Item);
+    fn get(&self, index: usize) -> Option<&Self::Item>;
+}
+
+impl Container for Vec<i32> {
+    type Item = i32;
+
+    fn add(&mut self, item: i32) {
+        self.push(item);
+    }
+
+    fn get(&self, index: usize) -> Option<&i32> {
+        self.get(index)
+    }
+}
+
+// Iterator trait (standard library example)
+trait MyIterator {
+    type Item;
+
+    fn next(&mut self) -> Option<Self::Item>;
+}
+```
+
+## Generic Traits and Bounds
+
+```rust
+// Generic trait with multiple bounds
+fn print_info<T>(item: &T)
+where
+    T: std::fmt::Display + std::fmt::Debug,
+{
+    println!("Display: {}", item);
+    println!("Debug: {:?}", item);
+}
+
+// Generic struct with trait bounds
+struct Pair<T: PartialOrd> {
+    first: T,
+    second: T,
+}
+
+impl<T: PartialOrd> Pair<T> {
+    fn new(first: T, second: T) -> Self {
+        Self { first, second }
+    }
+
+    fn larger(&self) -> &T {
+        if self.first > self.second {
+            &self.first
+        } else {
+            &self.second
+        }
+    }
+}
+
+// Blanket implementation
+trait MyTrait {
+    fn do_something(&self);
+}
+
+impl<T: std::fmt::Display> MyTrait for T {
+    fn do_something(&self) {
+        println!("Value: {}", self);
+    }
+}
+```
+
+## Trait Objects (Dynamic Dispatch)
+
+```rust
+// Static dispatch (monomorphization)
+fn static_dispatch<T: Drawable>(item: &T) {
+    item.draw();
+}
+
+// Dynamic dispatch (trait objects)
+fn dynamic_dispatch(item: &dyn Drawable) {
+    item.draw();
+}
+
+// Storing trait objects
+struct Canvas {
+    shapes: Vec<Box<dyn Drawable>>,
+}
+
+impl Canvas {
+    fn new() -> Self {
+        Self { shapes: Vec::new() }
+    }
+
+    fn add_shape(&mut self, shape: Box<dyn Drawable>) {
+        self.shapes.push(shape);
+    }
+
+    fn draw_all(&self) {
+        for shape in &self.shapes {
+            shape.draw();
+        }
+    }
+}
+
+// Object safety: traits must meet criteria
+trait ObjectSafe {
+    fn method(&self);  // OK: takes &self
+}
+
+trait NotObjectSafe {
+    fn generic<T>(&self);  // NOT OK: generic method
+    fn by_value(self);     // NOT OK: takes self by value
+}
+```
+
+## Derive Macros
+
+```rust
+// Standard derive macros
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct User {
+    id: u64,
+    name: String,
+}
+
+// Deriving more traits
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+struct Point {
+    x: i32,
+    y: i32,
+}
+
+// Custom derive with serde
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+struct Config {
+    host: String,
+    port: u16,
+}
+```
+
+## Advanced Trait Patterns
+
+```rust
+// Extension trait pattern
+trait StringExt {
+    fn truncate_to(&self, max_len: usize) -> String;
+}
+
+impl StringExt for str {
+    fn truncate_to(&self, max_len: usize) -> String {
+        if self.len() <= max_len {
+            self.to_string()
+        } else {
+            format!("{}...", &self[..max_len])
+        }
+    }
+}
+
+// Sealed trait pattern (prevent external implementation)
+mod sealed {
+    pub trait Sealed {}
+}
+
+pub trait MySealed: sealed::Sealed {
+    fn method(&self);
+}
+
+struct MyType;
+impl sealed::Sealed for MyType {}
+impl MySealed for MyType {
+    fn method(&self) {
+        println!("Implemented");
+    }
+}
+
+// Supertraits
+trait Printable {
+    fn print(&self);
+}
+
+trait Loggable: Printable {  // Supertrait: must also impl Printable
+    fn log(&self) {
+        self.print();  // Can call supertrait methods
+    }
+}
+```
+
+## Associated Constants
+
+```rust
+trait Config {
+    const MAX_SIZE: usize;
+    const DEFAULT_TIMEOUT: u64;
+}
+
+struct ServerConfig;
+
+impl Config for ServerConfig {
+    const MAX_SIZE: usize = 1024;
+    const DEFAULT_TIMEOUT: u64 = 30;
+}
+
+fn use_config<T: Config>() {
+    println!("Max size: {}", T::MAX_SIZE);
+}
+```
+
+## Generic Associated Types (GATs)
+
+```rust
+// GATs allow generics in associated types
+trait LendingIterator {
+    type Item<'a> where Self: 'a;
+
+    fn next<'a>(&'a mut self) -> Option<Self::Item<'a>>;
+}
+
+struct WindowsMut<'data, T> {
+    data: &'data mut [T],
+    index: usize,
+}
+
+impl<'data, T> LendingIterator for WindowsMut<'data, T> {
+    type Item<'a> = &'a mut [T] where Self: 'a;
+
+    fn next<'a>(&'a mut self) -> Option<Self::Item<'a>> {
+        if self.index >= self.data.len() {
+            return None;
+        }
+
+        let start = self.index;
+        self.index += 2;
+
+        Some(&mut self.data[start..start.min(self.data.len())])
+    }
+}
+```
+
+## Marker Traits
+
+```rust
+use std::marker::{PhantomData, Send, Sync};
+
+// Send: type can be transferred across thread boundaries
+// Sync: type can be shared between threads (&T is Send)
+
+// Custom marker trait
+trait Trusted {}
+
+struct TrustedData<T> {
+    data: T,
+    _marker: PhantomData<T>,
+}
+
+impl<T: Trusted> TrustedData<T> {
+    fn new(data: T) -> Self {
+        Self {
+            data,
+            _marker: PhantomData,
+        }
+    }
+}
+```
+
+## Operator Overloading
+
+```rust
+use std::ops::{Add, Mul};
+
+#[derive(Debug, Clone, Copy)]
+struct Vector2D {
+    x: f64,
+    y: f64,
+}
+
+impl Add for Vector2D {
+    type Output = Self;
+
+    fn add(self, other: Self) -> Self {
+        Self {
+            x: self.x + other.x,
+            y: self.y + other.y,
+        }
+    }
+}
+
+impl Mul<f64> for Vector2D {
+    type Output = Self;
+
+    fn mul(self, scalar: f64) -> Self {
+        Self {
+            x: self.x * scalar,
+            y: self.y * scalar,
+        }
+    }
+}
+
+// Usage
+let v1 = Vector2D { x: 1.0, y: 2.0 };
+let v2 = Vector2D { x: 3.0, y: 4.0 };
+let v3 = v1 + v2;
+let v4 = v1 * 2.5;
+```
+
+## From/Into Conversion Traits
+
+```rust
+struct UserId(u64);
+
+impl From<u64> for UserId {
+    fn from(id: u64) -> Self {
+        UserId(id)
+    }
+}
+
+// Into is automatically implemented
+fn accept_user_id(id: impl Into<UserId>) {
+    let user_id = id.into();
+    println!("User ID: {}", user_id.0);
+}
+
+// TryFrom for fallible conversions
+use std::convert::TryFrom;
+
+impl TryFrom<i64> for UserId {
+    type Error = &'static str;
+
+    fn try_from(value: i64) -> Result<Self, Self::Error> {
+        if value < 0 {
+            Err("User ID cannot be negative")
+        } else {
+            Ok(UserId(value as u64))
+        }
+    }
+}
+```
+
+## Const Traits (Nightly)
+
+```rust
+// Const trait implementations (requires nightly)
+#![feature(const_trait_impl)]
+
+#[const_trait]
+trait ConstAdd {
+    fn add(self, other: Self) -> Self;
+}
+
+impl const ConstAdd for i32 {
+    fn add(self, other: Self) -> Self {
+        self + other
+    }
+}
+
+const fn compute() -> i32 {
+    5.add(10)  // Can use in const context
+}
+```
+
+## Best Practices
+
+- Prefer associated types when there's one clear type per implementation
+- Use generic parameters when multiple types might be used simultaneously
+- Keep traits small and focused (single responsibility)
+- Use extension traits to add functionality to existing types
+- Document trait requirements and invariants
+- Use marker traits for compile-time guarantees
+- Prefer static dispatch for performance, dynamic dispatch for flexibility
+- Use #[derive] when possible instead of manual implementations
+- Implement standard traits (Debug, Clone, etc.) for better ecosystem integration
+- Use sealed traits to prevent external implementations when needed

package/skills/infra/cli-developer/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: cli-developer
+description: Use when building CLI tools, implementing argument parsing, or adding interactive prompts. Invoke for parsing flags and subcommands, displaying progress bars and spinners, generating bash/zsh/fish completion scripts, CLI design, shell completions, and cross-platform terminal applications using commander, click, typer, or cobra.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: devops
+  triggers: CLI, command-line, terminal app, argument parsing, shell completion, interactive prompt, progress bar, commander, click, typer, cobra
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: devops-engineer
+---
+
+# CLI Developer
+
+## Core Workflow
+
+1. **Analyze UX** — Identify user workflows, command hierarchy, common tasks. Validate by listing all commands and their expected `--help` output before writing code.
+2. **Design commands** — Plan subcommands, flags, arguments, configuration. Confirm flag naming is consistent and no existing signatures are broken.
+3. **Implement** — Build with the appropriate CLI framework for the language (see Reference Guide below). After wiring up commands, run `<cli> --help` to verify help text renders correctly and `<cli> --version` to confirm version output.
+4. **Polish** — Add completions, help text, error messages, progress indicators. Verify TTY detection for color output and graceful SIGINT handling.
+5. **Test** — Run cross-platform smoke tests; benchmark startup time (target: <50ms).
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Design Patterns | `references/design-patterns.md` | Subcommands, flags, config, architecture |
+| Node.js CLIs | `references/node-cli.md` | commander, yargs, inquirer, chalk |
+| Python CLIs | `references/python-cli.md` | click, typer, argparse, rich |
+| Go CLIs | `references/go-cli.md` | cobra, viper, bubbletea |
+| UX Patterns | `references/ux-patterns.md` | Progress bars, colors, help text |
+
+## Quick-Start Example
+
+### Node.js (commander)
+
+```js
+#!/usr/bin/env node
+// npm install commander
+const { program } = require('commander');
+
+program
+  .name('mytool')
+  .description('Example CLI')
+  .version('1.0.0');
+
+program
+  .command('greet <name>')
+  .description('Greet a user')
+  .option('-l, --loud', 'uppercase the greeting')
+  .action((name, opts) => {
+    const msg = `Hello, ${name}!`;
+    console.log(opts.loud ? msg.toUpperCase() : msg);
+  });
+
+program.parse();
+```
+
+For Python (click/typer) and Go (cobra) quick-start examples, see `references/python-cli.md` and `references/go-cli.md`.
+
+## Constraints
+
+### MUST DO
+- Keep startup time under 50ms
+- Provide clear, actionable error messages
+- Support `--help` and `--version` flags
+- Use consistent flag naming conventions
+- Handle SIGINT (Ctrl+C) gracefully
+- Validate user input early
+- Support both interactive and non-interactive modes
+- Test on Windows, macOS, and Linux
+
+### MUST NOT DO
+
+- **Block on synchronous I/O unnecessarily** — use async reads or stream processing instead.
+- **Print to stdout when output will be piped** — write logs/diagnostics to stderr.
+- **Use colors when output is not a TTY** — detect before applying color:
+  ```js
+  // Node.js
+  const useColor = process.stdout.isTTY;
+  ```
+  ```python
+  # Python
+  import sys
+  use_color = sys.stdout.isatty()
+  ```
+  ```go
+  // Go
+  import "golang.org/x/term"
+  useColor := term.IsTerminal(int(os.Stdout.Fd()))
+  ```
+- **Break existing command signatures** — treat flag/subcommand renames as breaking changes.
+- **Require interactive input in CI/CD environments** — always provide non-interactive fallbacks via flags or env vars.
+- **Hardcode paths or platform-specific logic** — use `os.homedir()` / `os.UserHomeDir()` / `Path.home()` instead.
+- **Ship without shell completions** — all three frameworks above have built-in completion generation.
+
+## Output Templates
+
+When implementing CLI features, provide:
+1. Command structure (main entry point, subcommands)
+2. Configuration handling (files, env vars, flags)
+3. Core implementation with error handling
+4. Shell completion scripts if applicable
+5. Brief explanation of UX decisions
+
+## Knowledge Reference
+
+CLI frameworks (commander, yargs, oclif, click, typer, argparse, cobra, viper), terminal UI (chalk, inquirer, rich, bubbletea), testing (snapshot testing, E2E), distribution (npm, pip, homebrew, releases), performance optimization