@kb-labs/shared 1.1.0

package/packages/shared-cli-ui/src/timing-tracker.ts

@@ -0,0 +1,68 @@
+/**
+ * Timing tracker utility for CLI commands
+ * Provides checkpoint-based timing measurement
+ */
+
+export class TimingTracker {
+  private start: number;
+  private checkpoints: Record<string, number> = {};
+  
+  constructor() {
+    this.start = Date.now();
+  }
+  
+  /**
+   * Record a timing checkpoint
+   */
+  checkpoint(name: string): void {
+    this.checkpoints[name] = Date.now() - this.start;
+  }
+  
+  /**
+   * Get total elapsed time in milliseconds
+   */
+  total(): number {
+    return Date.now() - this.start;
+  }
+  
+  /**
+   * Get timing breakdown including total
+   */
+  breakdown(): Record<string, number> {
+    return { ...this.checkpoints, total: this.total() };
+  }
+  
+  /**
+   * Get timing breakdown without total
+   */
+  checkpointsOnly(): Record<string, number> {
+    return { ...this.checkpoints };
+  }
+  
+  /**
+   * Reset the timer
+   */
+  reset(): void {
+    this.start = Date.now();
+    this.checkpoints = {};
+  }
+  
+  /**
+   * Get elapsed time since last checkpoint or start
+   */
+  sinceLastCheckpoint(): number {
+    const lastCheckpointTime = Math.max(...Object.values(this.checkpoints), 0);
+    return Date.now() - this.start - lastCheckpointTime;
+  }
+  
+  /**
+   * Get elapsed time since a specific checkpoint
+   */
+  sinceCheckpoint(checkpointName: string): number | null {
+    const checkpointTime = this.checkpoints[checkpointName];
+    if (checkpointTime === undefined) {
+      return null;
+    }
+    return Date.now() - this.start - checkpointTime;
+  }
+}

package/packages/shared-cli-ui/src/utils/context.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the current working directory from a CLI context-like object.
+ * Falls back to the process cwd when the context does not provide one.
+ */
+export function getContextCwd(input: { cwd?: string } | undefined): string {
+  if (input && typeof input.cwd === "string" && input.cwd.length > 0) {
+    return input.cwd;
+  }
+  return process.cwd();
+}
+
+

package/packages/shared-cli-ui/src/utils/env.ts

@@ -0,0 +1,164 @@
+/**
+ * Environment variable system for declarative env definition with type safety
+ *
+ * Usage:
+ * ```typescript
+ * // In contracts
+ * export const myEnv = defineEnv({
+ *   MY_API_KEY: { type: 'string', description: 'API key for service' },
+ *   MY_ENABLED: { type: 'boolean', default: true },
+ *   MY_TIMEOUT: { type: 'number', default: 5000 },
+ * });
+ *
+ * // In command
+ * export default defineCommand({
+ *   handler: {
+ *     async execute(ctx, input) {
+ *       const env = myEnv.parse(ctx.runtime);
+ *       console.log(env.MY_API_KEY); // string | undefined
+ *       console.log(env.MY_ENABLED); // boolean
+ *     }
+ *   }
+ * });
+ * ```
+ */
+
+import {
+  type FlagSpec,
+  type FlagsSchema,
+  type InferFlagsType,
+  parseBoolean,
+  parseString,
+  parseNumber,
+} from './flags.js';
+
+/**
+ * Runtime API interface (minimal for env parsing)
+ * Avoids dependency on @kb-labs/plugin-contracts
+ */
+export interface RuntimeLike {
+  env(key: string): string | undefined;
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Environment variable schema (reuses FlagSpec types)
+ */
+export type EnvSchema = FlagsSchema;
+
+/**
+ * Environment variable definition with parse method
+ */
+export interface EnvDefinition<T extends EnvSchema> {
+  /** Schema for documentation and validation */
+  schema: T;
+  /** Inferred TypeScript type */
+  type: InferFlagsType<T>;
+  /** Parse environment variables from RuntimeLike */
+  parse: (runtime: RuntimeLike) => InferFlagsType<T>;
+}
+
+// ============================================================================
+// defineEnv - main API
+// ============================================================================
+
+/**
+ * Define environment variables with type safety and validation
+ *
+ * @example
+ * ```typescript
+ * export const commitEnv = defineEnv({
+ *   KB_COMMIT_LLM_ENABLED: {
+ *     type: 'boolean',
+ *     default: true,
+ *     description: 'Enable LLM analysis',
+ *   },
+ *   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');
+ *     },
+ *   },
+ * });
+ *
+ * // Use in command
+ * const env = commitEnv.parse(ctx.runtime);
+ * // Type: { KB_COMMIT_LLM_ENABLED: boolean; KB_COMMIT_LLM_TEMPERATURE: number }
+ * ```
+ */
+export function defineEnv<T extends EnvSchema>(schema: T): EnvDefinition<T> {
+  return {
+    schema,
+    type: {} as InferFlagsType<T>,
+    parse: (runtime: RuntimeLike) => parseEnvFromRuntime(runtime, schema),
+  };
+}
+
+// ============================================================================
+// Runtime parsing
+// ============================================================================
+
+/**
+ * Parse environment variables from RuntimeLike with validation and defaults
+ */
+export function parseEnvFromRuntime<T extends EnvSchema>(
+  runtime: RuntimeLike,
+  schema: T
+): InferFlagsType<T> {
+  const result: any = {};
+
+  for (const [key, spec] of Object.entries(schema)) {
+    const rawValue = runtime.env(key);
+
+    // Apply default if undefined
+    if (rawValue === undefined) {
+      if ('default' in spec) {
+        result[key] = spec.default;
+      }
+      continue;
+    }
+
+    // Parse based on type (reuse parsers from flags)
+    result[key] = parseEnvValue(rawValue, key, spec);
+  }
+
+  return result;
+}
+
+/**
+ * Parse single env value with type validation
+ */
+function parseEnvValue(value: string | undefined, key: string, spec: FlagSpec): any {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  switch (spec.type) {
+    case 'boolean':
+      return parseBoolean(value, key);
+
+    case 'string':
+      const strValue = parseString(value, key);
+      // Custom validation for string
+      if (spec.validate) {
+        spec.validate(strValue);
+      }
+      return strValue;
+
+    case 'number':
+      const numValue = parseNumber(value, key);
+      // Custom validation for number
+      if (spec.validate) {
+        spec.validate(numValue);
+      }
+      return numValue;
+
+    default:
+      return value;
+  }
+}

package/packages/shared-cli-ui/src/utils/flags.ts

@@ -0,0 +1,269 @@
+/**
+ * Flag system for declarative CLI flag definition with type safety
+ *
+ * Usage:
+ * ```typescript
+ * // In contracts
+ * export const myFlags = defineFlags({
+ *   scope: { type: 'string', description: 'Filter by scope' },
+ *   verbose: { type: 'boolean', default: false },
+ * });
+ *
+ * // In command
+ * export default defineCommand({
+ *   flags: myFlags,
+ *   handler: {
+ *     async execute(ctx, input: typeof myFlags.type) {
+ *       const { scope, verbose } = input;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type FlagType = 'string' | 'boolean' | 'number';
+
+export interface BaseFlagSpec<T extends FlagType> {
+  type: T;
+  description?: string;
+  examples?: string[];
+  deprecated?: boolean | string;
+}
+
+export interface StringFlagSpec extends BaseFlagSpec<'string'> {
+  default?: string;
+  validate?: (value: string) => void | Promise<void>;
+}
+
+export interface BooleanFlagSpec extends BaseFlagSpec<'boolean'> {
+  default?: boolean;
+}
+
+export interface NumberFlagSpec extends BaseFlagSpec<'number'> {
+  default?: number;
+  validate?: (value: number) => void | Promise<void>;
+}
+
+export type FlagSpec = StringFlagSpec | BooleanFlagSpec | NumberFlagSpec;
+
+export type FlagsSchema = Record<string, FlagSpec>;
+
+// ============================================================================
+// Type inference
+// ============================================================================
+
+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]>;
+};
+
+// ============================================================================
+// defineFlags - main API
+// ============================================================================
+
+export interface FlagsDefinition<T extends FlagsSchema> {
+  /** Schema for manifest */
+  schema: T;
+  /** Inferred TypeScript type */
+  type: InferFlagsType<T>;
+  /** Parse and validate flags from raw input */
+  parse: (input: unknown) => InferFlagsType<T>;
+}
+
+/**
+ * Define CLI flags with type safety and validation
+ *
+ * @example
+ * ```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,
+ *   },
+ * });
+ *
+ * // Use in command
+ * type MyInput = typeof commitFlags.type;
+ * // Result: { scope?: string; 'dry-run': boolean }
+ * ```
+ */
+export function defineFlags<T extends FlagsSchema>(schema: T): FlagsDefinition<T> {
+  return {
+    schema,
+    type: {} as InferFlagsType<T>,
+    parse: (input: unknown) => parseFlagsFromInput(input, schema),
+  };
+}
+
+// ============================================================================
+// Runtime parsing and validation
+// ============================================================================
+
+/**
+ * Parse flags from raw input with type validation and defaults
+ */
+export function parseFlagsFromInput<T extends FlagsSchema>(
+  input: unknown,
+  schema: T
+): InferFlagsType<T> {
+  const result: any = {};
+  const rawInput = input as Record<string, unknown>;
+
+  for (const [key, spec] of Object.entries(schema)) {
+    const value = rawInput?.[key];
+
+    // Apply default if value is undefined
+    if (value === undefined) {
+      if ('default' in spec) {
+        result[key] = spec.default;
+      }
+      continue;
+    }
+
+    // Type validation and coercion
+    switch (spec.type) {
+      case 'boolean':
+        result[key] = parseBoolean(value, key);
+        break;
+      case 'string':
+        result[key] = parseString(value, key);
+        // Custom validation for string
+        if (spec.validate && result[key] !== undefined) {
+          spec.validate(result[key]);
+        }
+        break;
+      case 'number':
+        result[key] = parseNumber(value, key);
+        // Custom validation for number
+        if (spec.validate && result[key] !== undefined) {
+          spec.validate(result[key]);
+        }
+        break;
+    }
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Type parsers (exported for reuse in env.ts)
+// ============================================================================
+
+export function parseBoolean(value: unknown, flagName: string): boolean {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    const lower = value.toLowerCase();
+    if (lower === 'true' || lower === '1' || lower === 'yes') {return true;}
+    if (lower === 'false' || lower === '0' || lower === 'no') {return false;}
+  }
+
+  throw new Error(
+    `Flag "${flagName}" must be boolean, got ${typeof value}. ` +
+    `Use true/false or 1/0 or yes/no.`
+  );
+}
+
+export function parseString(value: unknown, flagName: string): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  // Coerce number to string
+  if (typeof value === 'number') {
+    return String(value);
+  }
+
+  throw new Error(
+    `Flag "${flagName}" must be string, got ${typeof value}.`
+  );
+}
+
+export function parseNumber(value: unknown, flagName: string): number {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new Error(`Flag "${flagName}" must be finite number, got ${value}.`);
+    }
+    return value;
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed)) {
+      throw new Error(
+        `Flag "${flagName}" must be number, got invalid string "${value}".`
+      );
+    }
+    return parsed;
+  }
+
+  throw new Error(
+    `Flag "${flagName}" must be number, got ${typeof value}.`
+  );
+}
+
+// ============================================================================
+// Legacy helper (keep for backward compatibility)
+// ============================================================================
+
+export function parseNumberFlag(value: unknown): number | undefined {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      return undefined;
+    }
+
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+
+  return undefined;
+}
+
+// ============================================================================
+// Utility: Merge input.flags into input (for V3 compatibility)
+// ============================================================================
+
+/**
+ * Merge input.flags into input root (V3 compatibility helper)
+ *
+ * @example
+ * ```typescript
+ * const raw = { scope: 'old', flags: { scope: 'new', json: true } };
+ * const merged = mergeFlags(raw);
+ * // Result: { scope: 'new', json: true, flags: {...} }
+ * ```
+ */
+export function mergeFlags<T extends Record<string, unknown>>(input: T): T {
+  if (!input.flags || typeof input.flags !== 'object') {
+    return input;
+  }
+
+  // Merge: root values first, then flags override
+  return { ...input, ...input.flags };
+}

package/packages/shared-cli-ui/src/utils/path.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalize filesystem paths to POSIX (forward-slash) form.
+ */
+export function toPosixPath(input: string): string {
+  return input.replace(/\\/g, "/");
+}
+
+

package/packages/shared-cli-ui/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/shared-cli-ui/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/shared-cli-ui/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+import dualPreset from '@kb-labs/devkit/tsup/dual';
+
+export default defineConfig({
+  ...dualPreset,
+  entry: {
+    index: "src/index.ts",
+    debug: "src/debug/index.ts",
+  },
+  tsconfig: "tsconfig.build.json", // Use build-specific tsconfig without paths
+});

package/packages/shared-cli-ui/vitest.config.ts

@@ -0,0 +1,15 @@
+import preset from '@kb-labs/devkit/vitest/node'
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  ...preset,
+  test: {
+    ...preset.test,
+    include: [
+      'src/**/*.spec.ts',
+      'src/**/*.test.ts',
+      'src/**/__tests__/**/*.spec.ts',
+      'src/**/__tests__/**/*.test.ts',
+    ],
+  },
+})

package/packages/shared-command-kit/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.

package/packages/shared-command-kit/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 KB Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+