@kb-labs/shared 1.1.0

package/docs/adr/0006-declarative-flags-and-env-systems.md

@@ -0,0 +1,376 @@
+# ADR-0006: Declarative Flags and Environment Variables Systems
+
+**Date:** 2025-12-19
+**Status:** Accepted
+**Deciders:** KB Labs Team
+**Last Reviewed:** 2025-12-19
+**Tags:** dx, type-safety, plugin-system, v3, developer-experience
+
+## Context
+
+V3 plugin commands had to manually extract and parse CLI flags and environment variables, leading to significant developer friction:
+
+### Problems
+
+1. **Excessive Boilerplate**: 5+ lines per command to extract env vars
+2. **No Type Safety**: Manual casting and parsing without compile-time checks
+3. **Inconsistent Patterns**: Different commands used different extraction approaches
+4. **Error-Prone**: Easy to forget validation or default values
+5. **Poor Maintainability**: Repetitive code across all commands
+
+### Example of Manual Approach
+
+```typescript
+// ❌ OLD: Manual extraction and parsing (5+ lines)
+const env: CommitEnv = {
+  KB_COMMIT_LLM_ENABLED: ctx.runtime.env('KB_COMMIT_LLM_ENABLED'),
+  KB_COMMIT_LLM_TEMPERATURE: ctx.runtime.env('KB_COMMIT_LLM_TEMPERATURE'),
+  KB_COMMIT_LLM_MAX_TOKENS: ctx.runtime.env('KB_COMMIT_LLM_MAX_TOKENS'),
+  KB_COMMIT_STORAGE_DIR: ctx.runtime.env('KB_COMMIT_STORAGE_DIR'),
+  KB_COMMIT_AUTO_STAGE: ctx.runtime.env('KB_COMMIT_AUTO_STAGE'),
+};
+
+// Manual parsing in config resolver (20+ lines)
+if (env.KB_COMMIT_LLM_TEMPERATURE !== undefined) {
+  const temp = parseFloat(env.KB_COMMIT_LLM_TEMPERATURE);
+  if (!isNaN(temp) && temp >= 0 && temp <= 1) {
+    config.llm.temperature = temp;
+  }
+}
+// ... repeat for every env var
+```
+
+### Impact
+
+- **Developer Velocity**: Slowed down plugin development
+- **Code Quality**: Inconsistent validation across commands
+- **Type Safety**: Runtime errors from incorrect parsing
+- **Maintenance**: Hard to refactor when changing env var types
+
+### Constraints
+
+- Must integrate with existing V3 plugin system
+- Must maintain backward compatibility
+- Cannot introduce heavy dependencies (Zod, class-validator, etc.)
+- Must support type inference for excellent IDE experience
+
+## Decision
+
+Implement two declarative systems for type-safe flag and env variable handling:
+
+### 1. `defineFlags()` — CLI Flags System
+
+Declarative CLI flag definitions with automatic type inference.
+
+**Location**: `@kb-labs/shared-cli-ui/src/utils/flags.ts`
+
+```typescript
+export const commitFlags = defineFlags({
+  scope: {
+    type: 'string',
+    description: 'Limit to package or path',
+    examples: ['@kb-labs/core', 'packages/**'],
+  },
+  'dry-run': {
+    type: 'boolean',
+    description: 'Preview without applying',
+    default: false,
+  },
+});
+
+export type CommitFlags = typeof commitFlags.type;
+// → { scope?: string; 'dry-run': boolean }
+```
+
+### 2. `defineEnv()` — Environment Variables System
+
+Declarative environment variable definitions with automatic type inference.
+
+**Location**: `@kb-labs/shared-cli-ui/src/utils/env.ts`
+
+```typescript
+export const commitEnv = defineEnv({
+  KB_COMMIT_LLM_TEMPERATURE: {
+    type: 'number',
+    default: 0.3,
+    description: 'LLM temperature (0-1)',
+    validate: (v) => {
+      if (v < 0 || v > 1) throw new Error('Must be 0-1');
+    },
+  },
+});
+
+export type CommitEnv = typeof commitEnv.type;
+// → { KB_COMMIT_LLM_TEMPERATURE: number }
+
+// Usage (1 line instead of 5+)
+const env = commitEnv.parse(ctx.runtime);
+```
+
+### Key Features
+
+**Type System**:
+- Supports `string`, `boolean`, `number` primitive types
+- Automatic type inference via TypeScript mapped types
+- Optional vs required based on `default` presence
+- Custom validation functions for strings and numbers
+
+**Runtime Parsing**:
+- Automatic type coercion and validation
+- Helpful error messages on parse failures
+- Default value application
+- Validation function execution
+
+**Shared Infrastructure**:
+- Both systems reuse same type parsers (`parseBoolean`, `parseString`, `parseNumber`)
+- Consistent API surface
+- No dependency duplication
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│              defineFlags / defineEnv                │
+│  Declarative schema with automatic type inference  │
+└─────────────────────────────────────────────────────┘
+                        │
+        ┌───────────────┴───────────────┐
+        │                               │
+        ▼                               ▼
+┌───────────────┐               ┌──────────────┐
+│ parseFlagsFrom│               │parseEnvFrom  │
+│     Input     │               │   Runtime    │
+└───────────────┘               └──────────────┘
+        │                               │
+        └───────────┬───────────────────┘
+                    ▼
+        ┌───────────────────────┐
+        │  Shared Type Parsers  │
+        │  - parseBoolean       │
+        │  - parseString        │
+        │  - parseNumber        │
+        └───────────────────────┘
+```
+
+### Type Inference
+
+```typescript
+// Flags with defaults are non-optional
+type InferFlagType<T extends FlagSpec> =
+  T extends StringFlagSpec
+    ? T extends { default: string } ? string : string | undefined
+    : T extends BooleanFlagSpec
+    ? T extends { default: boolean } ? boolean : boolean | undefined
+    : T extends NumberFlagSpec
+    ? T extends { default: number } ? number : number | undefined
+    : never;
+
+export type InferFlagsType<T extends FlagsSchema> = {
+  [K in keyof T]: InferFlagType<T[K]>;
+};
+```
+
+**Result**: Flags with defaults become `string`, without defaults become `string | undefined`.
+
+### Avoiding Circular Dependencies
+
+Problem: `shared-cli-ui` cannot depend on `@kb-labs/plugin-contracts`.
+
+Solution: Minimal `RuntimeLike` interface:
+
+```typescript
+/**
+ * Avoids dependency on @kb-labs/plugin-contracts
+ */
+export interface RuntimeLike {
+  env(key: string): string | undefined;
+}
+```
+
+## Consequences
+
+### Positive
+
+✅ **5+ lines → 1 line**: Massive reduction in boilerplate
+✅ **Type safety**: Automatic type inference, compile-time checks
+✅ **Validation**: Built-in type validation + custom validators
+✅ **Defaults**: Declarative defaults with proper type narrowing
+✅ **Consistency**: Same pattern across all commands
+✅ **Self-documenting**: Schema serves as documentation
+✅ **DX**: Excellent IDE autocomplete and type hints
+✅ **Backward compatible**: V3 bootstrap auto-merges `input.flags`
+
+### Negative
+
+⚠️ **Migration effort**: Existing commands need updating
+⚠️ **Learning curve**: Developers need to learn new pattern
+⚠️ **Schema duplication**: Flags in contracts + manifest (acceptable tradeoff)
+
+### Neutral
+
+🔹 **New dependency**: Commands depend on `@kb-labs/sdk` for `defineEnv()`
+🔹 **Type complexity**: Uses advanced TypeScript (mapped types, conditional types)
+🔹 **Runtime overhead**: Minimal (parsing happens once per command)
+
+### Before/After Comparison
+
+```typescript
+// ❌ BEFORE: Manual, error-prone, no type safety (25+ lines)
+const env: CommitEnv = {
+  KB_COMMIT_LLM_ENABLED: ctx.runtime.env('KB_COMMIT_LLM_ENABLED'),
+  KB_COMMIT_LLM_TEMPERATURE: ctx.runtime.env('KB_COMMIT_LLM_TEMPERATURE'),
+  KB_COMMIT_LLM_MAX_TOKENS: ctx.runtime.env('KB_COMMIT_LLM_MAX_TOKENS'),
+  KB_COMMIT_STORAGE_DIR: ctx.runtime.env('KB_COMMIT_STORAGE_DIR'),
+  KB_COMMIT_AUTO_STAGE: ctx.runtime.env('KB_COMMIT_AUTO_STAGE'),
+};
+
+// Manual parsing
+if (env.KB_COMMIT_LLM_TEMPERATURE !== undefined) {
+  const temp = parseFloat(env.KB_COMMIT_LLM_TEMPERATURE);
+  if (!isNaN(temp) && temp >= 0 && temp <= 1) {
+    config.llm.temperature = temp;
+  }
+}
+```
+
+```typescript
+// ✅ AFTER: Declarative, type-safe, DRY (1 line)
+const env = commitEnv.parse(ctx.runtime);
+// env.KB_COMMIT_LLM_TEMPERATURE → number (fully typed, validated)
+
+// Clean config resolution
+const config: CommitPluginConfig = {
+  llm: {
+    temperature: env.KB_COMMIT_LLM_TEMPERATURE ?? fileConfig.llm?.temperature ?? 0.3,
+  },
+};
+```
+
+## Alternatives Considered
+
+### 1. Zod Schemas
+
+```typescript
+const commitEnvSchema = z.object({
+  KB_COMMIT_LLM_TEMPERATURE: z.number().min(0).max(1).default(0.3),
+});
+```
+
+**Rejected**:
+- Too heavy (adds 14KB Zod dependency to shared-cli-ui)
+- Overkill for simple primitive types
+- More complex API surface
+
+### 2. Class-based Validators
+
+```typescript
+class CommitEnv {
+  @IsBoolean() KB_COMMIT_LLM_ENABLED = true;
+  @IsNumber() @Min(0) @Max(1) KB_COMMIT_LLM_TEMPERATURE = 0.3;
+}
+```
+
+**Rejected**:
+- Requires decorators (experimental TypeScript feature)
+- More boilerplate than declarative approach
+- Runtime reflection overhead
+
+### 3. Manual Helper Functions
+
+```typescript
+function useEnv<T>(schema: EnvSchema<T>): T {
+  // ...
+}
+```
+
+**Rejected**:
+- Similar complexity to our solution
+- Less declarative
+- Doesn't enable schema reuse for documentation
+
+## Implementation
+
+### Changes Made
+
+1. **`@kb-labs/shared-cli-ui`**:
+   - Added `src/utils/flags.ts` — `defineFlags()` system
+   - Added `src/utils/env.ts` — `defineEnv()` system
+   - Exported parsers for reuse
+
+2. **`@kb-labs/sdk`**:
+   - Re-exported `defineFlags`, `defineEnv`, and related types
+   - Added to public API for plugin developers
+
+3. **`@kb-labs/commit-contracts`**:
+   - Added `src/flags.ts` — flag definitions
+   - Added `src/env.ts` — env definitions
+   - Removed old `CommitEnv` interface
+   - Updated `resolveCommitConfig()` to use typed values
+
+4. **`@kb-labs/commit-cli`**:
+   - Migrated `run.ts` to use `commitEnv.parse()`
+   - Migrated `generate.ts` to use `commitEnv.parse()`
+   - Reduced boilerplate from 5+ lines to 1 line per command
+
+### Migration Path
+
+For existing plugins:
+
+1. Create flag definitions in contracts:
+   ```typescript
+   export const myFlags = defineFlags({
+     scope: { type: 'string', description: '...' },
+   });
+   ```
+
+2. Create env definitions in contracts:
+   ```typescript
+   export const myEnv = defineEnv({
+     MY_VAR: { type: 'boolean', default: true },
+   });
+   ```
+
+3. Update commands:
+   ```typescript
+   const env = myEnv.parse(ctx.runtime); // 1 line
+   ```
+
+### Testing
+
+Verified with commit plugin:
+
+```bash
+KB_COMMIT_LLM_TEMPERATURE=0.5 KB_COMMIT_LLM_MAX_TOKENS=3000 \
+  pnpm kb commit generate --scope="kb-labs-commit-plugin"
+```
+
+Results:
+- ✅ Env vars parsed correctly
+- ✅ Type validation passed
+- ✅ Command executed without errors
+- ✅ No runtime performance impact
+
+## Future Improvements
+
+1. **Auto-generate manifest**: Extract flag definitions for plugin manifest
+2. **CLI help generation**: Auto-generate `--help` text from flag descriptions
+3. **Env var docs**: Auto-generate documentation from env schema
+4. **Deprecation warnings**: Built-in support for deprecated flags/env vars
+5. **Schema validation**: Validate manifest against flag schema at build time
+
+## References
+
+- TypeScript: [Mapped Types](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html)
+- TypeScript: [Conditional Types](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html)
+- V3 Plugin System: [docs/V3-IMPLEMENTATION-SPEC.md](../V3-IMPLEMENTATION-SPEC.md)
+- Bootstrap Auto-Merge: `kb-labs-plugin/packages/plugin-runtime/src/v3/bootstrap.ts`
+
+---
+
+**Last Updated:** 2025-12-19
+**Implementation**: Complete
+**Packages Modified**:
+- `@kb-labs/shared-cli-ui` — Added `defineFlags()` and `defineEnv()`
+- `@kb-labs/sdk` — Re-exported utilities
+- `@kb-labs/commit-contracts` — Added definitions
+- `@kb-labs/commit-cli` — Migrated commands

package/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/kb-labs.config.json

@@ -0,0 +1,5 @@
+{
+  "sync": {
+    "enabled": true
+  }
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@kb-labs/shared",
+  "version": "1.1.0",
+  "description": "Shared utilities and contracts for KB Labs ecosystem",
+  "type": "module",
+  "author": {
+    "name": "Kirill Baranov",
+    "url": "https://github.com/kirill-baranov"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kirill-baranov/kb-labs-shared.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kirill-baranov/kb-labs-shared/issues"
+  },
+  "homepage": "https://github.com/kirill-baranov/kb-labs-shared#readme",
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
+  "scripts": {
+    "// ——— devkit": "────────────────────────────────────────",
+    "devkit:sync": "node scripts/devkit-sync.mjs",
+    "predevkit:sync": "pnpm devkit:paths",
+    "devkit:paths": "pnpm exec kb-devkit-paths",
+    "devkit:sync:ci": "node scripts/devkit-sync.mjs --ci-only",
+    "predevkit:sync:ci": "pnpm devkit:paths",
+    "devkit:check": "node scripts/devkit-sync.mjs --check",
+    "predevkit:check": "pnpm devkit:paths",
+    "devkit:force": "node scripts/devkit-sync.mjs --force",
+    "predevkit:force": "pnpm devkit:paths",
+    "devkit:help": "node scripts/devkit-sync.mjs --help",
+    "postinstall": "pnpm -s devkit:sync || true",
+    "// ——— core": "────────────────────────────────────────",
+    "build": "pnpm -r run build",
+    "build:clean": "pnpm -r run clean && pnpm -r run build",
+    "dev": "pnpm -r --parallel run dev",
+    "// ——— quality": "────────────────────────────────────────",
+    "lint": "pnpm -r --filter=\"./packages/*\" run lint",
+    "lint:fix": "pnpm -r --filter=\"./packages/*\" run lint:fix",
+    "test": "pnpm -r --if-present run test",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "pnpm -r --parallel --if-present run test:watch",
+    "type-check": "pnpm -r run type-check",
+    "format": "prettier -w .",
+    "format:check": "prettier -c .",
+    "// ——— ci/qa": "────────────────────────────────────────",
+    "check": "pnpm lint && pnpm type-check && pnpm test",
+    "ci": "pnpm clean && pnpm build && pnpm check",
+    "// ——— cleanup": "────────────────────────────────────────",
+    "clean": "pnpm -r run clean",
+    "clean:all": "rimraf node_modules packages/*/node_modules apps/*/node_modules dist"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json,md,yml,yaml}": [
+      "prettier -w"
+    ],
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix"
+    ]
+  },
+  "devDependencies": {
+    "@actions/core": "^1",
+    "@actions/github": "^6",
+    "@types/node": "^24.3.3",
+    "@types/picomatch": "^4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "better-sqlite3": "^12.2.0",
+    "colorette": "^2.0.20",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../infra/kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=18.18.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@9.11.0",
+  "dependencies": {
+    "@kb-labs/devkit": "^1.1.0",
+    "zod": "^4.1.5"
+  }
+}

package/package.json.bin

@@ -0,0 +1,25 @@
+{
+  "name": "@kb-labs/your-package",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Your package description",
+  "bin": {
+    "your-cli": "./dist/bin.cjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "test": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "workspace:*",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/package.json.lib

@@ -0,0 +1,30 @@
+{
+  "name": "@kb-labs/your-package",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Your package description",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "test": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@kb-labs/devkit": "workspace:*",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/packages/shared-cli-ui/CHANGELOG.md

@@ -0,0 +1,20 @@
+## [1.1.0] - 2026-03-24
+
+**5 packages** bumped to v1.1.0
+
+| Package | Previous | Bump |
+|---------|----------|------|
+| `@kb-labs/perm-presets` | 1.0.0 | minor |
+| `@kb-labs/shared-command-kit` | 1.0.0 | minor |
+| `@kb-labs/shared-tool-kit` | 1.0.0 | minor |
+| `@kb-labs/shared-cli-ui` | 1.0.0 | minor |
+| `@kb-labs/shared-testing` | 1.0.0 | minor |
+
+### ✨ New Features
+
+- **config**: Introduces new configuration files for package management, allowing users to easily manage dependencies and ensure consistent environments across projects.
+- **github**: Implements GitHub workflows for CI/CD, streamlining the development process and enabling quicker, more reliable software updates for users.
+
+### 🐛 Bug Fixes
+
+- **tests**: Improves code clarity by using an object type instead of a placeholder, which helps prevent misunderstandings in the codebase and enhances maintainability. Additionally, it resolves a linting issue that could lead to confusion when no value is returned from certain functions.