@kb-labs/shared 1.1.0

package/docs/adr/0000-template.md

@@ -0,0 +1,52 @@
+# ADR-XXXX: [Brief Decision Title]
+
+**Date:** YYYY-MM-DD
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Deciders:** KB Labs Team
+**Last Reviewed:** YYYY-MM-DD
+**Reviewers:** [Optional list of reviewers]
+**Tags:** [tag1, tag2, tag3]
+
+> **Note:** Tags are mandatory. Minimum 1 tag, maximum 5 tags. See approved tags list in [DOCUMENTATION.md](../DOCUMENTATION.md#adr-tags).
+
+## Context
+
+_Describe the problem or situation that necessitated this decision._  
+_What alternatives were considered? What constraints exist?_
+
+## Decision
+
+_Describe the decision that was made. Key aspects: structure, tools, practices._  
+_Include diagrams or schemas if applicable._
+
+## Consequences
+
+### Positive
+
+- Benefits of the chosen solution
+
+### Negative
+
+- Drawbacks and risks
+
+### Alternatives Considered
+
+- Why other options were rejected
+
+## Implementation
+
+_What changes after this decision is made? What processes or code need to be updated?_  
+_Will this decision be revisited in the future?_
+
+## References
+
+- [Discussion / Pull Request](url)
+- [Related ADRs](./0000-other-decision.md)
+
+---
+
+**Last Updated:** YYYY-MM-DD  
+**Next Review:** YYYY-MM-DD (if scheduled)
+
+
+

package/docs/adr/0001-architecture-and-repository-layout.md

@@ -0,0 +1,31 @@
+# ADR-0001: Architecture and Repository Layout
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [architecture, tooling]
+
+## Context
+
+KB Labs products must be consistent across repositories. Each repository should follow the same monorepo-style layout to support apps, packages, and fixtures.
+
+## Decision
+
+- Use PNPM workspaces for package management
+- Repository root must contain:
+  - `/apps` — example/demo apps or product UI
+  - `/packages` — core logic, reusable libraries, domain modules
+  - `/fixtures` — sample diffs, test inputs, reference data
+  - `/docs` — ADRs, handbook, guides
+- Shared configs (tsconfig, eslint, prettier, vitest) live in root
+
+## Consequences
+
+**Positive:**
+- Consistent developer experience across products
+- Easy onboarding: all repositories look alike
+- Enables cross-product reuse of tools/scripts
+
+**Negative:**
+- Initial setup complexity for new repositories

package/docs/adr/0002-plugins-and-extensibility.md

@@ -0,0 +1,44 @@
+# ADR-0002: Plugins and Extensibility
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [architecture, api]  
+
+## Context
+
+KB Labs products are designed to be reusable across different stacks, domains, and teams. To ensure long-term scalability, all products (AI Review, AI Docs, AI Tests, etc.) must support a flexible plugin & extension system. Without this, every new feature would require hardcoding into the core, increasing maintenance burden and reducing adaptability.
+
+## Decision
+
+- Each KB Labs product must expose a plugin API that allows third-party developers (or other KB Labs packages) to extend behavior without modifying the core
+- The plugin system must be:
+  1. **Isolated** — Plugins run in a sandboxed scope and cannot break the core
+  2. **Composable** — Multiple plugins can be combined in one pipeline
+  3. **Discoverable** — Plugins are registered via a central registry (`plugins/index.ts`) or a configuration file (`.kblabsrc.json`)
+  4. **Typed** — All plugin interfaces must be defined in `@kb-labs/core` using TypeScript types and Zod schemas
+  5. **Cross-product** — The same plugin (e.g., a Slack notifier) can be reused in AI Review, AI Docs, and AI Tests without rewriting
+
+## Examples
+
+- **AI Review** — rule providers, LLM strategies, custom output formatters
+- **AI Docs** — content generators, format exporters (Markdown, HTML, Confluence)
+- **AI Tests** — test strategy plugins, snapshot comparators
+- **Shared** — analytics/logging, secret providers, budget control
+
+## Consequences
+
+**Positive:**
+- Easier to onboard contributors: they extend via plugins instead of modifying the core
+- Ensures product consistency: every KB Labs product has the same extensibility model
+- Avoids long-term lock-in
+
+**Negative:**
+- Core complexity increases slightly
+- Additional abstraction layer to maintain
+
+## Alternatives Considered
+
+- **Hardcoded integrations** — rejected (not scalable, not reusable)
+- **Separate extension repositories** — rejected (too fragmented, harder to maintain)

package/docs/adr/0003-package-and-module-boundaries.md

@@ -0,0 +1,35 @@
+# ADR-0003: Package and Module Boundaries
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [architecture, process]  
+
+## Context
+
+Products in KB Labs often require multiple internal packages. Without strict boundaries, cross-dependencies can grow messy and unmaintainable.
+
+## Decision
+
+- Every package under `/packages` must define:
+  - `src/` — implementation
+  - `index.ts` — public entry point
+  - `types/` — exported types & schemas
+- Packages must only depend on public exports of other packages
+- Cross-package imports must use workspace aliases (`@kb-labs/<pkg>`)
+- Domain rules:
+  - Core logic in `@kb-labs/core`
+  - Product-specific code in `@kb-labs/<product>`
+  - Experimental code → feature packages, not core
+
+## Consequences
+
+**Positive:**
+- Prevents tight coupling
+- Core remains minimal and reusable
+- Easier to extract packages as standalone OSS later
+
+**Negative:**
+- Requires discipline to maintain boundaries
+- More complex dependency management

package/docs/adr/0004-versioning-and-release-policy.md

@@ -0,0 +1,36 @@
+# ADR-0004: Versioning and Release Policy
+
+**Date:** 2025-09-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-11-03
+**Tags:** [process, deployment]  
+
+## Context
+
+The KB Labs ecosystem must stay consistent, while still allowing individual products to evolve.
+
+## Decision
+
+- Use Semantic Versioning (SemVer) for all published packages
+- Core (`@kb-labs/core`) follows stricter rules:
+  - **MAJOR:** breaking changes in APIs/schemas
+  - **MINOR:** new features, backward-compatible
+  - **PATCH:** bugfixes
+- Products (`ai-review`, `ai-docs`, `ai-tests`, etc.) can release independently, but must pin to compatible core versions
+- Changelog generation automated via changesets or `@kb-labs/changelog-generator`
+- Release flow:
+  1. Pull request → CI check (lint, type-check, test)
+  2. Merge → changeset entry created
+  3. Release pipeline tags version, publishes to npm, updates changelog
+
+## Consequences
+
+**Positive:**
+- Predictable updates across ecosystem
+- Users know when breaking changes occur
+- Easy adoption of multiple products without fear of hidden breakage
+
+**Negative:**
+- Requires careful coordination for major releases
+- More complex release automation setup

package/docs/adr/0005-reactive-loader-pattern.md

@@ -0,0 +1,179 @@
+# ADR-0005: Reactive Loader Pattern for CLI Spinners
+
+**Date:** 2025-12-13
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-12-13
+**Tags:** [ui, architecture, performance, simplicity]
+
+## Context
+
+CLI loaders (spinners) need to update text dynamically while maintaining a single-line animation. The original implementation had issues:
+
+1. **Animation duplication** - When updating text, multiple lines appeared instead of a single updating line
+2. **Complex control flow** - Stopping and restarting `setInterval` on each update added unnecessary complexity
+3. **Performance overhead** - Clearing intervals and creating new ones every 200ms was wasteful
+4. **Child process stdout buffering** - In forked child processes, frequent interval restarts could cause buffering issues
+
+### Initial Approach (Problematic)
+
+```typescript
+update(options: Partial<LoaderOptions>): void {
+  // Stop current interval
+  if (this.intervalId) {
+    clearInterval(this.intervalId);
+    this.intervalId = undefined;
+  }
+
+  // Update options
+  this.options = { ...this.options, ...options };
+
+  // Restart interval with new text
+  this.intervalId = setInterval(() => {
+    const text = this.options.text ?? 'Loading...';
+    process.stdout.write(`\r${SPINNER_CHARS[frame]} ${text}`);
+  }, 200);
+}
+```
+
+**Problems:**
+- ❌ Animation flickers on updates
+- ❌ Interval restart overhead every update
+- ❌ Race conditions between stop/start
+- ❌ Line duplication in child processes
+
+## Decision
+
+Implement a **reactive variable pattern** (Vue-style) where `setInterval` runs continuously and reads a mutable text variable:
+
+```typescript
+class Loader {
+  private currentText: string;  // ← Reactive variable
+  private intervalId?: NodeJS.Timeout;
+
+  start(): void {
+    this.isActive = true;
+
+    // Start interval once - reads currentText continuously
+    this.intervalId = setInterval(() => {
+      if (!this.isActive) {
+        this.clearInterval();
+        return;
+      }
+
+      const char = SPINNER_CHARS[this.frameIndex % SPINNER_CHARS.length];
+      process.stdout.write(`\r${char} ${this.currentText}`);  // ← Read reactive text
+      this.frameIndex++;
+    }, 200);
+  }
+
+  update(options: Partial<LoaderOptions>): void {
+    this.options = { ...this.options, ...options };
+
+    // Just update the variable - setInterval picks it up on next tick!
+    if (options.text !== undefined) {
+      this.currentText = options.text;  // ← Simple variable assignment
+    }
+  }
+}
+```
+
+**Key insight:** `setInterval` callback has closure access to `this.currentText`. When we update the variable, the next interval tick automatically reads the new value - **no restart needed**.
+
+## Consequences
+
+### Positive
+
+- ✅ **Single-line animation** - No more line duplication
+- ✅ **Zero overhead updates** - Just variable assignment (O(1) vs interval restart overhead)
+- ✅ **Simple mental model** - "Text is reactive, interval reads it" (Vue-style)
+- ✅ **No race conditions** - No concurrent interval management
+- ✅ **Child process friendly** - Continuous stdout writes work with piping
+- ✅ **Performance** - Eliminates ~50% of interval operations (no stop/start)
+
+### Negative
+
+- ⚠️ **Requires understanding closures** - Developers must understand how setInterval captures `this`
+- ⚠️ **Not obvious from API** - `update()` looks like it does nothing, but it's reactive
+
+### Alternatives Considered
+
+**1. Message Queue Pattern**
+```typescript
+private textQueue: string[] = [];
+update(text: string) { this.textQueue.push(text); }
+```
+❌ Rejected: Adds complexity, doesn't solve fundamental issue
+
+**2. requestAnimationFrame (browser-style)**
+❌ Rejected: Not available in Node.js
+
+**3. Observable/RxJS**
+❌ Rejected: Overkill dependency for simple text updates
+
+**4. Event Emitter**
+```typescript
+private emitter = new EventEmitter();
+update(text: string) { this.emitter.emit('text', text); }
+```
+❌ Rejected: More complex than needed, adds event listener overhead
+
+## Implementation
+
+### Files Changed
+
+1. **`kb-labs-shared/packages/shared-cli-ui/src/loader.ts`**
+   - Added `private currentText: string` reactive variable
+   - Modified `start()` to read `currentText` in interval callback
+   - Simplified `update()` to just assign `currentText`
+
+2. **`kb-labs-sdk/packages/sdk/src/ui.ts`**
+   - Exported `useLoader` hook for plugin consumption
+
+3. **`kb-labs-plugin/packages/plugin-runtime/src/presenter/presenter-facade.ts`**
+   - Removed `spinner()` method from UIFacade interface
+
+### Migration Guide
+
+**Before (deprecated):**
+```typescript
+const spinner = ctx.ui.spinner('Loading...');
+spinner.start();
+spinner.update({ text: 'Processing...' });  // ❌ Stop/restart interval
+spinner.succeed('Done!');
+```
+
+**After (recommended):**
+```typescript
+import { useLoader } from '@kb-labs/sdk';
+
+const loader = useLoader('Loading...');
+loader.start();
+loader.update({ text: 'Processing...' });  // ✅ Just update reactive variable
+loader.succeed('Done!');
+```
+
+### Testing
+
+Verified with `plugin-template:test-loader` command:
+- ✅ Single continuous loader (4 updates in 2s) - single line, no duplication
+- ✅ Multi-stage progress (3 stages × 4 updates) - clean stage transitions
+- ✅ Rapid updates (10 updates in 100ms) - smooth animation
+- ✅ Child process execution (verified via PID logging)
+
+### Future Considerations
+
+- Consider TypeScript `readonly` modifier to document reactive variables
+- Add JSDoc comment explaining reactive pattern
+- Benchmark memory usage vs previous implementation (expected: identical)
+
+## References
+
+- [Vue.js Reactivity Fundamentals](https://vuejs.org/guide/essentials/reactivity-fundamentals.html) - Inspiration for pattern
+- Implementation: `kb-labs-shared/packages/shared-cli-ui/src/loader.ts`
+- Test: `kb-labs-plugin-template/packages/plugin-template-core/src/cli/commands/test-loader.ts`
+
+---
+
+**Last Updated:** 2025-12-13
+**Next Review:** 2026-01-13 (1 month - verify no regressions)