@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/cli/cli-shell-integration.md

@@ -0,0 +1,130 @@
+---
+name: cli-shell-integration
+description: Shell completion generation for bash/zsh/fish, man page generation, dotfile conventions, PATH management, and shell aliases
+topics: [cli, shell-integration, completion, man-pages, dotfiles, path-management, aliases]
+---
+
+Shell integration is the difference between a CLI that feels native and one that feels like a foreign object. Completion, man pages, and dotfile patterns are not optional polish — they are the features that determine whether power users adopt the tool or abandon it for something that respects their shell workflow.
+
+## Summary
+
+Shell integration — completion scripts, man pages, dotfile modifications, and PATH management — determines whether power users adopt the tool or abandon it. Generate completion scripts from the CLI definition for bash, zsh, and fish. Provide an `install-completions` subcommand. When modifying shell startup files, use clearly marked comment blocks and always provide an uninstall command.
+
+## Deep Guidance
+
+### Shell Completion Generation
+
+Provide completion scripts for bash, zsh, and fish. Generate them from the CLI definition rather than hand-writing them — they will stay in sync as commands and flags evolve:
+
+**Node.js (yargs)**
+```bash
+my-cli completion     # Outputs bash/zsh completion script
+my-cli completion >> ~/.bashrc
+```
+
+**Cobra (Go)**
+```bash
+my-cli completion bash   # bash
+my-cli completion zsh    # zsh
+my-cli completion fish   # fish
+my-cli completion powershell
+```
+
+**clap (Rust)** with `clap_complete`:
+```rust
+// Generate at build time and install to /usr/local/share/bash-completion/completions/
+generate(Shell::Bash, &mut cmd, "my-cli", &mut io::stdout());
+```
+
+**click (Python)**: Use `click-completion` or the built-in `shell_complete` parameter.
+
+Completion installation patterns:
+- **bash**: Source from `~/.bashrc` or drop in `/etc/bash_completion.d/` or `~/.bash_completion.d/`
+- **zsh**: Drop in `$fpath` directory, e.g., `/usr/local/share/zsh/site-functions/_my-cli`
+- **fish**: Drop in `~/.config/fish/completions/my-cli.fish`
+
+Provide a `my-cli install-completions` subcommand that writes the correct file for the detected shell. Always print the path written and what the user must do to activate it (e.g., restart shell or run `source ~/.bashrc`).
+
+### Man Page Generation
+
+Man pages are the canonical reference documentation. Generate them from the CLI definition:
+
+**Go (cobra)**: `cobra-man` generates man pages from Cobra commands.
+
+**Node.js**: `marked-man` converts Markdown to man format. `ronn` (Ruby) converts richly formatted Markdown to man.
+
+**Rust (clap)**: `clap_mangen` generates man pages from clap definitions.
+
+Man page installation:
+- System-wide: `/usr/local/share/man/man1/my-cli.1`
+- User-local: `~/.local/share/man/man1/my-cli.1`
+- Run `mandb` (Linux) or ensure `$MANPATH` includes the directory
+
+Homebrew formulae automatically install man pages if placed in `share/man/man1/`. For npm packages, include a `man` field in `package.json`.
+
+### Dotfile Conventions
+
+When the CLI modifies shell startup files (`~/.bashrc`, `~/.zshrc`), follow these rules:
+
+- Never overwrite startup files — append only
+- Use clearly marked comment blocks:
+  ```bash
+  # >>> my-cli init >>>
+  export PATH="$HOME/.my-cli/bin:$PATH"
+  eval "$(my-cli shell-init)"
+  # <<< my-cli init <<<
+  ```
+- The markers enable the tool to detect existing installation and idempotently update the block
+- Always provide `my-cli uninstall` or `my-cli shell-remove` that removes exactly these markers
+- Never add content outside the marked block
+
+On first install, detect which shell config files exist and are writable: check `$SHELL`, then look for `~/.zshrc`, `~/.bashrc`, `~/.bash_profile` in that order.
+
+### PATH Management
+
+When the tool installs binaries or shims to a user-local directory:
+
+```bash
+# Typical user-local bin directory
+~/.local/bin/          # XDG standard (Linux/macOS)
+~/.my-cli/bin/         # Tool-specific (when multiple versions coexist)
+```
+
+Check if the directory is already on `$PATH` before suggesting the user add it. If not on `$PATH`, print the exact line to add and which file to add it to:
+
+```
+Add this to ~/.zshrc:
+  export PATH="$HOME/.local/bin:$PATH"
+```
+
+Do not silently modify PATH for the current process and assume it persists — shell environment changes only persist through startup file modification or explicit user action.
+
+### Shell Aliases
+
+Provide a mechanism to generate useful shell aliases for common command combinations:
+
+```bash
+# my-cli generates aliases for common workflows
+my-cli alias generate >> ~/.zshrc
+```
+
+Aliases should be documented and user-editable. Never require aliases for core functionality — they are convenience, not architecture.
+
+### Shell Detection
+
+Detect the user's shell reliably:
+
+```bash
+# Most reliable: check $SHELL environment variable
+SHELL_NAME=$(basename "$SHELL")
+
+# Fallback: check running process
+ps -p $PPID -o comm= | sed 's/^-//'
+```
+
+Map shell name to config file:
+- `zsh` → `~/.zshrc`
+- `bash` → `~/.bashrc` (Linux) or `~/.bash_profile` (macOS interactive login shells)
+- `fish` → `~/.config/fish/config.fish`
+
+When the shell cannot be detected, print instructions for all three common shells and let the user pick. Never guess and silently write to the wrong file.

package/content/knowledge/cli/cli-testing.md

@@ -0,0 +1,134 @@
+---
+name: cli-testing
+description: CLI integration testing by spawning processes, snapshot testing help text, mock filesystem, environment variable testing, and CI matrix testing
+topics: [cli, testing, integration-tests, snapshot-testing, mock-filesystem, ci-matrix, exit-codes]
+---
+
+CLI testing requires a different mindset than library testing. The contract being tested is behavioral: given this argv and environment, what does the tool write to stdout, what does it write to stderr, and what exit code does it return? Unit tests for business logic are necessary but not sufficient — integration tests that spawn the actual binary catch the class of bugs that only appear at the boundary between argument parsing and execution.
+
+## Summary
+
+CLI testing requires spawning the actual binary and asserting on stdout, stderr, and exit code. Snapshot test help text to catch accidental regressions. Isolate filesystem tests with temporary directories and mock `$HOME`/`XDG_CONFIG_HOME`. Test across OS/runtime matrices in CI including Windows.
+
+## Deep Guidance
+
+### Integration Testing by Spawning the Process
+
+The most valuable CLI test spawns the actual binary and asserts on stdout, stderr, and exit code:
+
+**Node.js (vitest or jest)**
+```typescript
+import { execSync } from 'child_process';
+
+test('build succeeds with valid input', () => {
+  const result = execSync('node bin/my-cli build --input fixture.txt', {
+    encoding: 'utf8',
+    env: { ...process.env, XDG_CONFIG_HOME: tmpDir }
+  });
+  expect(result).toContain('Build complete');
+});
+
+test('exits 2 on unknown flag', () => {
+  expect(() =>
+    execSync('node bin/my-cli --unknown-flag', { encoding: 'utf8', stdio: 'pipe' })
+  ).toThrow('exit code 2');
+});
+```
+
+**Rust**
+```rust
+use assert_cmd::Command;
+
+#[test]
+fn build_succeeds() {
+    Command::cargo_bin("my-cli")
+        .unwrap()
+        .arg("build")
+        .assert()
+        .success()
+        .stdout(predicates::str::contains("Build complete"));
+}
+```
+
+**Bats (shell)**
+```bash
+@test "exits 2 on missing required argument" {
+  run my-cli deploy
+  [ "$status" -eq 2 ]
+  [[ "$output" =~ "required" ]]
+}
+```
+
+Always test exit codes. Always test that error output goes to stderr. Always test the success path and the most common failure paths.
+
+### Snapshot Testing for Help Text
+
+Help text is part of the public API — changes should be intentional. Snapshot tests catch accidental regressions:
+
+```typescript
+test('help text matches snapshot', () => {
+  const { stdout } = execSync('node bin/my-cli --help', { encoding: 'utf8' });
+  expect(stdout).toMatchSnapshot();
+});
+```
+
+Update snapshots intentionally when help text changes. In CI, fail on unexpected snapshot drift. This also catches typos and formatting issues in help output.
+
+### Mock Filesystem
+
+Tests that interact with the filesystem must be isolated. Use temporary directories or a mock filesystem:
+
+**Node.js**
+```typescript
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+
+let tmpDir: string;
+beforeEach(() => { tmpDir = mkdtempSync(tmpdir() + '/my-cli-test-'); });
+afterEach(() => { rmSync(tmpDir, { recursive: true }); });
+```
+
+For unit tests that don't need real disk I/O, `memfs` provides an in-memory filesystem that satisfies the Node.js `fs` module interface.
+
+**Rust**: Use `tempfile::TempDir`. Tests run in parallel by default — each test gets its own temp directory to avoid interference.
+
+**Key rule**: Never write to `$HOME`, `~/.config`, or any real user directory in tests. Set `HOME` and `XDG_CONFIG_HOME` to the temp directory.
+
+### Environment Variable Testing
+
+Test behavior driven by environment variables:
+
+```typescript
+test('respects NO_COLOR', () => {
+  const result = execSync('node bin/my-cli status', {
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1' }
+  });
+  // Assert no ANSI escape sequences in output
+  expect(result).not.toMatch(/\x1b\[/);
+});
+```
+
+Test the full env var precedence chain: flag overrides env var, env var overrides config file. Each level should be independently testable.
+
+### CI Matrix Testing
+
+Test across multiple operating systems and runtime versions:
+
+```yaml
+# GitHub Actions
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+    node: ['18', '20', '22']
+```
+
+Windows-specific concerns: path separators (`\` vs `/`), line endings (`\r\n` vs `\n`), `%APPDATA%` vs `$HOME/.config`, and `PATHEXT` for binary extension handling. Test on Windows even if you do not primarily develop on it.
+
+### Test Pyramid for CLIs
+
+- **Unit tests (fast)**: Business logic in `utils/`, pure functions, config parsing, output formatters
+- **Integration tests (medium)**: Spawn the CLI process, assert stdout/stderr/exit code for key scenarios
+- **End-to-end tests (slow, optional)**: Full workflow against real external services — run in CI on schedule, not on every PR
+
+Keep integration tests fast by using fixtures (pre-created files) rather than generating test input dynamically. A full integration test suite should complete in under 30 seconds.

package/content/knowledge/library/library-api-design.md

@@ -0,0 +1,306 @@
+---
+name: library-api-design
+description: Public surface design, method signatures, error contracts, and extension points for published library APIs
+topics: [library, api-design, public-surface, method-signatures, error-contracts, extension-points]
+---
+
+Library API design is the highest-leverage activity in library development. A well-designed API makes correct usage easy and incorrect usage hard, survives multiple major versions without fundamental restructuring, and communicates intent through its shape alone. Poor API design cannot be fixed without breaking changes — every naming mistake, parameter order error, and missing overload becomes permanent once consumers adopt it. Design APIs from the consumer's perspective first, implementation second.
+
+## Summary
+
+Design APIs by writing consumer call sites before writing implementation. Prefer named options objects over positional parameters beyond two arguments. Return values should be typed as specifically as possible — avoid returning `any` or overly wide union types. Error contracts must be explicit: document what each function throws, when, and why. Provide extension points through composition (options injection, middleware, plugins) rather than inheritance. Make the happy path obvious and the error path impossible to ignore.
+
+Core principles:
+- Pit-of-success design: the obvious way to use the API is the correct way
+- Named options objects for 3+ parameters
+- Explicit error contracts (typed throws, documented in JSDoc)
+- Overloads for genuinely different call signatures
+- Consistent return type patterns (never `T | undefined` when you can overload)
+
+## Deep Guidance
+
+### Write Call Sites First
+
+Before implementing any function, write the code that will call it:
+
+```typescript
+// Step 1: Write how consumers will use this
+import { parseConfig } from 'my-library'
+
+// Use case 1: parse a string, get typed config
+const config = parseConfig(rawString)
+
+// Use case 2: parse with strict mode
+const config = parseConfig(rawString, { strict: true })
+
+// Use case 3: parse a file path (different input)
+const config = await parseConfigFile('./config.toml')
+
+// Use case 4: handle parse errors gracefully
+try {
+  const config = parseConfig(rawString)
+} catch (err) {
+  if (err instanceof ParseError) {
+    console.error(`Parse failed at line ${err.line}: ${err.message}`)
+  }
+}
+
+// Step 2: Now design the API to make this work naturally
+export function parseConfig(input: string, options?: ParseOptions): Config
+export async function parseConfigFile(path: string, options?: ParseOptions): Promise<Config>
+```
+
+This technique reveals usability issues before any code is written.
+
+### Options Object Pattern
+
+Positional parameters beyond two create cognitive load and fragile call sites:
+
+```typescript
+// BAD: positional parameters — order is arbitrary, easy to mix up
+function connect(host: string, port: number, timeout: number, ssl: boolean, retries: number): Client
+
+// Called as: connect('localhost', 5432, 30000, true, 3)
+// Which is timeout and which is retries? Must check signature every time.
+
+// GOOD: named options object
+interface ConnectOptions {
+  host: string
+  port: number
+  timeout?: number     // ms, default: 30000
+  ssl?: boolean        // default: false
+  retries?: number     // default: 3
+}
+
+function connect(options: ConnectOptions): Client
+// connect({ host: 'localhost', port: 5432, ssl: true })
+// Self-documenting call site. New options add without breaking callers.
+```
+
+**Options object rules:**
+- All options beyond the first two required parameters go in an options object
+- Options should have sensible defaults (document the defaults in JSDoc)
+- Required options stay required; don't make everything optional
+- Never use boolean flags that change behavior fundamentally — use discriminated unions
+
+```typescript
+// BAD: boolean flag that means completely different behavior
+function parse(input: string, isFile: boolean): Config
+
+// GOOD: separate functions or discriminated union
+function parseString(input: string): Config
+function parseFile(path: string): Promise<Config>
+// Or:
+type ParseInput = { type: 'string'; value: string } | { type: 'file'; path: string }
+function parse(input: ParseInput): Config | Promise<Config>
+```
+
+### Method Signature Design
+
+**Overloads for genuinely different signatures:**
+```typescript
+// Overloads allow TypeScript to narrow the return type based on input
+function parse(input: string): Config
+function parse(input: string, options: { async: true }): Promise<Config>
+function parse(input: string, options: { async: false }): Config
+function parse(input: string, options?: ParseOptions): Config | Promise<Config> {
+  // implementation
+}
+```
+
+Use overloads sparingly. Each overload is a commitment to maintain that signature. If you find yourself needing many overloads, reconsider whether the API should be split into separate functions.
+
+**Generic constraints — add them when they add value:**
+```typescript
+// Good: generic constraint enables type narrowing
+function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>
+
+// Bad: generic without constraint is less type-safe
+function pick<T, K>(obj: T, keys: K[]): any
+
+// Bad: generic where it adds no value (always the same type)
+function identity<T>(value: T): T  // Fine for teaching, rarely needed in practice
+```
+
+**Return type specificity:**
+```typescript
+// BAD: too wide
+function getUser(id: string): object
+
+// BAD: any
+function parseYAML(input: string): any
+
+// GOOD: specific types
+function getUser(id: string): User | null  // null when not found
+function parseYAML<T = unknown>(input: string): T  // generic with default
+
+// BEST when the shape is known:
+interface User {
+  id: string
+  name: string
+  email: string
+  createdAt: Date
+}
+function getUser(id: string): User | null
+```
+
+### Error Contracts
+
+Every public function must have a documented error contract. Document errors in JSDoc and in a separate errors section of the API documentation.
+
+**JSDoc error documentation:**
+```typescript
+/**
+ * Parse a configuration string into a typed Config object.
+ *
+ * @param input - TOML-formatted configuration string
+ * @param options - Parsing options
+ * @returns Parsed and validated Config object
+ *
+ * @throws {ParseError} If the input string is not valid TOML.
+ *   `ParseError.line` and `ParseError.column` indicate the error location.
+ * @throws {ValidationError} If the parsed config fails schema validation.
+ *   `ValidationError.errors` contains the list of validation failures.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const config = parseConfig('[server]\nhost = "localhost"')
+ * } catch (err) {
+ *   if (err instanceof ParseError) {
+ *     console.error(`Syntax error at line ${err.line}`)
+ *   }
+ * }
+ * ```
+ */
+export function parseConfig(input: string, options?: ParseOptions): Config
+```
+
+**Result type pattern (alternative to throws):**
+For APIs where errors are expected and should be handled inline, a Result type is cleaner than throws:
+
+```typescript
+export type Result<T, E extends Error = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E }
+
+export function tryParseConfig(input: string): Result<Config, ParseError | ValidationError> {
+  try {
+    return { ok: true, value: parseConfig(input) }
+  } catch (err) {
+    return { ok: false, error: err as ParseError | ValidationError }
+  }
+}
+
+// Consumer usage:
+const result = tryParseConfig(input)
+if (result.ok) {
+  console.log(result.value.server.host)
+} else {
+  console.error(result.error.message)
+}
+```
+
+Provide both patterns when the use case warrants: throwing for "should not fail" paths, Result type for "expected to sometimes fail" paths.
+
+### Extension Points
+
+Design extension points that don't require forking or subclassing:
+
+**Middleware pattern for transform pipelines:**
+```typescript
+export interface ParseMiddleware {
+  (input: string, next: (input: string) => Config): Config
+}
+
+export function createParser(middlewares: ParseMiddleware[] = []): Parser {
+  return {
+    parse(input: string): Config {
+      const chain = middlewares.reduceRight(
+        (next: (i: string) => Config, mw) => (i: string) => mw(i, next),
+        parseRaw
+      )
+      return chain(input)
+    }
+  }
+}
+
+// Consumer adds preprocessing:
+const parser = createParser([
+  (input, next) => next(input.trim().toLowerCase()),
+  (input, next) => {
+    const result = next(input)
+    return { ...result, source: 'custom' }
+  }
+])
+```
+
+**Hook pattern for lifecycle events:**
+```typescript
+export interface ClientHooks {
+  beforeRequest?: (req: Request) => Request | Promise<Request>
+  afterResponse?: (res: Response) => Response | Promise<Response>
+  onError?: (err: Error) => void
+}
+
+export function createClient(options: ClientOptions & { hooks?: ClientHooks }): Client
+```
+
+**Avoid class inheritance as extension:**
+```typescript
+// BAD: forces consumers to subclass
+class BaseClient {
+  protected abstract buildRequest(options: RequestOptions): Request
+  // Consumers must extend to customize
+}
+
+// GOOD: inject the behavior
+type RequestBuilder = (options: RequestOptions) => Request
+
+function createClient(options: {
+  buildRequest?: RequestBuilder
+}): Client
+```
+
+Subclassing creates tight coupling between the consumer and the library's internal class hierarchy. Every internal restructuring becomes a breaking change.
+
+### Fluent API Design
+
+Fluent APIs (method chaining) improve readability for configuration-heavy builders:
+
+```typescript
+// Query builder example
+export class QueryBuilder<T> {
+  private _where: WhereClause[] = []
+  private _orderBy: OrderClause[] = []
+  private _limit?: number
+
+  where(field: keyof T, op: Operator, value: unknown): this {
+    this._where.push({ field: field as string, op, value })
+    return this
+  }
+
+  orderBy(field: keyof T, direction: 'asc' | 'desc' = 'asc'): this {
+    this._orderBy.push({ field: field as string, direction })
+    return this
+  }
+
+  limit(n: number): this {
+    this._limit = n
+    return this
+  }
+
+  build(): Query<T> {
+    return { where: this._where, orderBy: this._orderBy, limit: this._limit }
+  }
+}
+
+// Consumer:
+const query = new QueryBuilder<User>()
+  .where('active', '=', true)
+  .orderBy('createdAt', 'desc')
+  .limit(10)
+  .build()
+```
+
+Use fluent APIs for builders and configuration DSLs. Avoid them for operational functions — `parseConfig(input).validate().execute()` is harder to debug than three explicit function calls.