@booklib/skills 1.8.0 → 1.10.0

package/hooks/suggest.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * booklib-suggest.js
+ * Claude Code UserPromptSubmit hook — suggests a relevant @booklib/skills skill
+ * when the prompt contains a review intent AND a language/domain signal.
+ *
+ * Install: copy (or symlink) this file to ~/.claude/booklib-suggest.js
+ * Hook config (hooks.json):
+ *   { "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node \"$HOME/.claude/booklib-suggest.js\"" }] }] }
+ */
+
+"use strict";
+
+process.exitCode = 0;
+
+const REVIEW_KEYWORDS = [
+  "review", "check", "improve", "refactor", "fix", "audit",
+  "analyse", "analyze", "critique", "lint",
+];
+
+const LANGUAGE_SIGNALS = {
+  python_async: [".py", "asyncio", "async def", "await "],
+  python_scraping: [".py", "python", "beautifulsoup", "scrapy", "requests.get", "web scraping"],
+  python: [".py", "python", "def ", "async def", "import ", "asyncio", "beautifulsoup", "scrapy"],
+  typescript: [".ts", ".tsx", ".js", "typescript", "interface ", "type ", "const ", "function "],
+  java: [".java", "java", "class ", "@override", "public static"],
+  kotlin: [".kt", "kotlin", "fun ", "val ", "var ", "data class"],
+  rust: [".rs", "rust", "fn ", "impl ", "struct ", "enum ", "let mut"],
+  ui_animation: [".css", ".scss", "animation", "transition", "@keyframes", "styled", "tailwind"],
+  ui: [".css", ".scss", "animation", "transition", "@keyframes", "styled", "tailwind"],
+  data: ["pipeline", "etl", "dataframe", "schema", "migration", "replication"],
+  architecture: ["microservice", "aggregate", "bounded context", "saga", "event sourcing"],
+};
+
+const SKILL_MAP = {
+  python_async: { skill: "/using-asyncio-python", reason: "Async patterns and asyncio best practices in Python" },
+  python_scraping: { skill: "/web-scraping-python", reason: "Web scraping techniques and patterns with Python" },
+  python: { skill: "/effective-python", reason: "Pythonic idioms and best practices" },
+  typescript: { skill: "/effective-typescript", reason: "TypeScript type safety and idiomatic patterns" },
+  java: { skill: "/effective-java", reason: "Effective Java patterns and API design" },
+  kotlin: { skill: "/effective-kotlin", reason: "Idiomatic Kotlin and best practices" },
+  rust: { skill: "/programming-with-rust", reason: "Rust ownership, safety, and idiomatic patterns" },
+  ui_animation: { skill: "/animation-at-work", reason: "Web animation principles and best practices" },
+  ui: { skill: "/refactoring-ui", reason: "UI design principles and visual hierarchy" },
+  data: { skill: "/data-pipelines", reason: "Data pipeline design and ETL best practices" },
+  architecture: { skill: "/skill-router", reason: "Routes to the right skill for architecture concerns" },
+};
+
+function extractPrompt(raw) {
+  if (!raw || raw.trim() === "") return "";
+  try {
+    const parsed = JSON.parse(raw);
+    // Claude Code may send { prompt: "..." } or { message: "..." }
+    if (parsed && typeof parsed === "object") {
+      return String(parsed.prompt || parsed.message || parsed.text || "");
+    }
+  } catch (_) {
+    // Not JSON — treat as raw prompt text
+  }
+  return raw;
+}
+
+function hasReviewIntent(text) {
+  const lower = text.toLowerCase();
+  return REVIEW_KEYWORDS.some((kw) => lower.includes(kw));
+}
+
+/**
+ * Returns the most specific language key that matches, or null.
+ * Order matters: more specific keys (python_async, python_scraping) are checked first.
+ */
+function detectLanguage(text) {
+  const lower = text.toLowerCase();
+
+  const orderedKeys = [
+    "python_async",
+    "python_scraping",
+    "python",
+    "typescript",
+    "java",
+    "kotlin",
+    "rust",
+    "ui_animation",
+    "ui",
+    "data",
+    "architecture",
+  ];
+
+  for (const key of orderedKeys) {
+    const signals = LANGUAGE_SIGNALS[key];
+    // For compound keys, require at least 2 signals to avoid false positives
+    // (e.g. python_async needs both a python marker AND an async marker)
+    if (key === "python_async") {
+      const hasPython = [".py", "python", "def ", "import "].some((s) => lower.includes(s));
+      const hasAsync = ["asyncio", "async def", "await "].some((s) => lower.includes(s));
+      if (hasPython && hasAsync) return key;
+      continue;
+    }
+    if (key === "python_scraping") {
+      const hasPython = [".py", "python", "def ", "import "].some((s) => lower.includes(s));
+      const hasScraping = ["beautifulsoup", "scrapy", "web scraping", "requests.get"].some((s) => lower.includes(s));
+      if (hasPython && hasScraping) return key;
+      continue;
+    }
+    if (signals.some((s) => lower.includes(s.toLowerCase()))) {
+      return key;
+    }
+  }
+
+  return null;
+}
+
+function main() {
+  let raw = "";
+  try {
+    // Read all of stdin synchronously
+    const fd = require("fs").openSync("/dev/stdin", "r");
+    const chunks = [];
+    const buf = Buffer.alloc(4096);
+    let bytesRead;
+    while ((bytesRead = require("fs").readSync(fd, buf, 0, buf.length, null)) > 0) {
+      chunks.push(buf.slice(0, bytesRead));
+    }
+    require("fs").closeSync(fd);
+    raw = Buffer.concat(chunks).toString("utf8");
+  } catch (_) {
+    // stdin unavailable or empty — exit silently
+    process.exit(0);
+  }
+
+  const prompt = extractPrompt(raw);
+  if (!prompt) process.exit(0);
+
+  if (!hasReviewIntent(prompt)) process.exit(0);
+
+  const langKey = detectLanguage(prompt);
+
+  if (!langKey) {
+    // Review intent but no specific language — suggest clean-code-reviewer
+    process.stdout.write(
+      "💡 booklib: try /clean-code-reviewer — General clean code review principles\n"
+    );
+    process.exit(0);
+  }
+
+  const match = SKILL_MAP[langKey];
+  if (!match) process.exit(0);
+
+  process.stdout.write(`💡 booklib: try ${match.skill} — ${match.reason}\n`);
+  process.exit(0);
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booklib/skills",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Book knowledge distilled into structured AI skills for Claude Code and other AI assistants",
   "bin": {
     "skills": "bin/skills.js"

package/rules/common/clean-code.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Clean Code standards from Robert C. Martin. Apply to all code regardless of language.
+---
+
+# Clean Code Standards
+
+Apply these principles from *Clean Code* (Robert C. Martin) to all code you write or review.
+
+## Names
+
+- Use intention-revealing names — if the name needs a comment to explain it, rename it
+- Avoid abbreviations unless universally understood (`url`, `id`, `ctx` are fine; `mgr`, `proc` are not)
+- Classes and types are nouns; methods and functions are verb phrases
+- Avoid noise words that add no meaning: `Manager`, `Data`, `Info`, `Handler` in type names usually signal a missing concept
+- Boolean variables and functions read as assertions: `isEnabled`, `hasPermission`, `canRetry`
+
+## Functions
+
+- Functions do one thing; if you can extract a meaningful sub-function with a non-trivial name, the function does too much
+- Keep functions short — aim for under 20 lines; over 40 is a smell
+- Max 3 parameters; group related parameters into a value object when you need more
+- Avoid boolean flag parameters — they signal the function does two things; split it
+- No side effects in functions that return values
+
+## Comments
+
+- Comments compensate for failure to express intent in code — prefer renaming over commenting
+- Never commit commented-out code; use version control
+- `// TODO:` is acceptable only when tracked in an issue; delete stale TODOs
+- Document *why*, not *what* — the code shows what; the comment explains a non-obvious reason
+
+## Structure
+
+- Group related code together; put high-level concepts at the top, details below
+- Functions in a file should be ordered so callers appear before callees
+- Avoid deep nesting — if `if`/`else` chains exceed 3 levels, extract or invert conditions
+
+## Error handling
+
+- Prefer exceptions over error codes for exceptional conditions
+- Handle errors at the appropriate abstraction level — don't catch and re-throw unless you add context
+- Never swallow exceptions silently; at minimum log before ignoring

package/rules/java/effective-java.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Effective Java standards from Joshua Bloch. Apply when writing or reviewing Java code.
+---
+
+# Effective Java Standards
+
+Apply these principles from *Effective Java* (Joshua Bloch, 3rd edition) to all Java code.
+
+## Object creation
+
+- Prefer static factory methods over constructors — they have names, can return subtypes, and can cache instances
+- Use a builder when a constructor or factory would have more than 3 parameters
+- Never create unnecessary objects; reuse `String` literals, prefer `Boolean.valueOf(x)` over `new Boolean(x)`
+
+## Classes and mutability
+
+- Minimize mutability — all fields `private final` by default; add setters only when needed
+- Favor composition over inheritance; explicitly document classes designed for extension or mark them `final`
+- Override `@Override` on every method that overrides or implements; the annotation catches typos at compile time
+
+## Methods
+
+- Validate parameters at entry; throw `IllegalArgumentException`, `NullPointerException`, or `IndexOutOfBoundsException` with a message
+- Return empty collections or `Optional`, never `null`, from methods with a non-primitive return type
+- Use `Optional` for return values that may be absent; don't use it for fields or parameters
+
+## Exceptions
+
+- Use checked exceptions for recoverable conditions; unchecked (`RuntimeException`) for programming errors
+- Prefer standard exceptions: `IllegalArgumentException`, `IllegalStateException`, `UnsupportedOperationException`, `NullPointerException`
+- Don't swallow exceptions — at minimum log with context before ignoring; never `catch (Exception e) {}`
+
+## Generics and collections
+
+- Use generic types and methods; avoid raw types (`List` → `List<E>`)
+- Use bounded wildcards (`? extends T` for producers, `? super T` for consumers — PECS)
+- Prefer `List` over arrays for type safety; use arrays only for performance-sensitive low-level code
+
+## Concurrency
+
+- Synchronize all accesses to shared mutable state; prefer `java.util.concurrent` utilities over `synchronized`
+- Prefer immutable objects and thread confinement over shared mutable state

package/rules/kotlin/effective-kotlin.md

@@ -0,0 +1,37 @@
+---
+description: Always-on Effective Kotlin standards from Marcin Moskała. Apply when writing or reviewing Kotlin code.
+---
+
+# Effective Kotlin Standards
+
+Apply these principles from *Effective Kotlin* (Marcin Moskała, 2nd edition) to all Kotlin code.
+
+## Safety
+
+- Prefer `val` over `var`; use `var` only when mutation is genuinely required
+- Use nullable types explicitly (`T?`); avoid `!!` — narrow with `?.`, `?:`, `let`, or `checkNotNull()`
+- Use `require()` for argument preconditions and `check()` for state preconditions at function entry
+
+## Functions
+
+- Use named arguments when passing more than 2 parameters, especially when they share the same type
+- Use default arguments instead of overloads for optional behavior
+- Prefer extension functions over utility classes for domain operations on a type you own
+
+## Classes and design
+
+- Use data classes for value objects — they get `equals`, `hashCode`, `copy`, and `toString` for free
+- Prefer sealed classes over open hierarchies when the set of subtypes is finite and known
+- Use `object` for singletons, `companion object` for factory methods and class-level constants
+
+## Collections
+
+- Use functional operators (`map`, `filter`, `fold`, `groupBy`) over manual loops
+- Prefer `Sequence` for large collections or multi-step pipelines — avoids intermediate lists
+- Use `buildList { }` / `buildMap { }` instead of a mutable variable followed by `.toList()`
+
+## Coroutines
+
+- Launch coroutines in a structured `CoroutineScope`; never use `GlobalScope` in production
+- Use `withContext(Dispatchers.IO)` for blocking I/O; never block the main/UI thread
+- Prefer `Flow` over callbacks for asynchronous streams; use `StateFlow` for observable state

package/rules/python/effective-python.md

@@ -0,0 +1,38 @@
+---
+description: Always-on Effective Python standards from Brett Slatkin. Apply when writing or reviewing Python code.
+---
+
+# Effective Python Standards
+
+Apply these principles from *Effective Python* (Brett Slatkin, 3rd edition) to all Python code.
+
+## Pythonic style
+
+- Use `enumerate()` over `range(len(...))` for indexed iteration
+- Use f-strings for interpolation; avoid `%` formatting and `.format()`
+- Prefer unpacking over indexing: `first, *rest = items` instead of `items[0]` and `items[1:]`
+- Use `zip()` to iterate two sequences together; use `zip(strict=True)` when lengths must match
+
+## Data structures
+
+- Use `list` for ordered mutable sequences, `tuple` for immutable positional data, `set` for membership tests
+- Use `collections.defaultdict` or `Counter` instead of manual dict initialization
+- Prefer `dataclasses` over plain dicts or namedtuples for structured data with methods
+
+## Functions
+
+- Use keyword-only arguments (`def f(a, *, b)`) for optional parameters that benefit from names at the call site
+- Never use mutable default arguments — use `None` and assign inside the function body
+- Prefer generator expressions `(x for x in ...)` over list comprehensions when you don't need the full list in memory
+
+## Type annotations
+
+- Annotate all public functions and class attributes
+- Use `X | None` (Python 3.10+) or `Optional[X]` for nullable types; never return `None` silently from a typed function
+- Avoid `Any` except at system boundaries (external APIs, deserialized JSON)
+
+## Error handling
+
+- Catch specific exception types; never use bare `except:`
+- Use `contextlib.suppress(ExceptionType)` for intentionally ignored exceptions — makes the intent explicit
+- Use `__all__` in every module to declare its public API

package/rules/rust/rust.md

@@ -0,0 +1,37 @@
+---
+description: Always-on Rust standards from Programming with Rust and Rust in Action. Apply when writing or reviewing Rust code.
+---
+
+# Rust Standards
+
+Apply these principles from *Programming with Rust* (Donis Marshall) and *Rust in Action* (Tim McNamara) to all Rust code.
+
+## Ownership and borrowing
+
+- Use owned values (`String`, `Vec<T>`) for data you own; borrow (`&str`, `&[T]`) when you only need to read
+- Prefer passing `&T` or `&mut T` over cloning; clone only when ownership transfer is required
+- Use `Rc<T>` for single-threaded shared ownership, `Arc<T>` for multi-threaded; use `RefCell<T>` / `Mutex<T>` for interior mutability
+
+## Error handling
+
+- Return `Result<T, E>` from all fallible functions; propagate with `?`
+- Use `thiserror` to define library errors with `#[derive(Error)]`; use `anyhow` for application-level error context
+- Avoid `.unwrap()` in library code; use `.expect("clear message")` in application code where panicking is intentional
+
+## Types and traits
+
+- Use `struct` for data, `enum` for variants with payloads, `trait` for shared behaviour
+- Implement standard traits where appropriate: `Debug` always, `Display` for user-facing types, `Clone`, `PartialEq`, `Hash` as needed
+- Use `impl Trait` in argument position for static dispatch; `Box<dyn Trait>` only when you need runtime dispatch
+
+## Idiomatic patterns
+
+- Use `Iterator` adapters (`map`, `filter`, `flat_map`, `collect`) over manual loops — the compiler optimizes them equally
+- Use `Option` methods (`map`, `unwrap_or`, `and_then`, `ok_or`) over `match` for simple transformations
+- Use `if let` for single-variant matching; use `match` for exhaustive handling
+
+## Naming and style
+
+- Types: `PascalCase`; functions, variables, modules: `snake_case`; constants and statics: `SCREAMING_SNAKE_CASE`
+- Lifetime names: `'a`, `'b` for simple cases; descriptive names (`'arena`, `'cx`) for complex lifetimes
+- Mark all public items in a library crate with doc comments (`///`)

package/rules/typescript/effective-typescript.md

@@ -0,0 +1,42 @@
+---
+description: Always-on Effective TypeScript standards from Dan Vanderkam. Apply when writing or reviewing TypeScript or JavaScript code.
+---
+
+# Effective TypeScript Standards
+
+Apply these principles from *Effective TypeScript* (Dan Vanderkam, 2nd edition) to all TypeScript code.
+
+## Types
+
+- Prefer union types over enums for simple sets of values: `type Direction = 'N' | 'S' | 'E' | 'W'`
+- Use `interface` for extensible object shapes that others may augment; use `type` for unions, intersections, and computed types
+- Avoid `any`; use `unknown` when the type is genuinely unknown, then narrow with guards before use
+- Avoid type assertions (`as T`) — prefer type narrowing, overloads, or generics
+
+## Type inference
+
+- Let TypeScript infer return types on internal functions; explicitly annotate public API return types
+- Annotate a variable at declaration if it cannot be initialized immediately
+- Use `as const` to preserve literal types; don't use it just to silence widening errors
+
+## Null safety
+
+- Enable `strict` mode (which includes `strictNullChecks`) — treat every `T | undefined` as requiring explicit handling
+- Use optional chaining `?.` and nullish coalescing `??` over `&&` and `||` chains
+- Never use non-null assertion (`!`) — narrow instead
+
+## Structural typing
+
+- TypeScript checks shapes, not nominal types — understand that duck typing applies
+- Use discriminated unions with a `kind` or `type` literal field for exhaustive `switch` / narrowing
+- Avoid class hierarchies for data shapes — prefer interfaces and composition
+
+## Generics
+
+- Constrain generics to the minimum required: `<T extends string>` not `<T>`
+- Use descriptive generic names for complex types (`<TItem, TKey>`) and single letters for simple transforms (`<T>`, `<K, V>`)
+
+## Functions
+
+- Prefer function overloads over union parameter types to express the relationship between input and output
+- Keep functions pure where possible; extract side effects to the call site