@kb-labs/shared 1.1.0

package/packages/shared-command-kit/docs/HIGH-LEVEL-API.md

@@ -0,0 +1,89 @@
+# High-level API
+
+Complete wrapper for building commands with zero boilerplate.
+
+## defineCommand
+
+The `defineCommand` function handles all boilerplate automatically:
+
+- Flag validation
+- Logging
+- Analytics
+- Error handling
+- Output formatting
+- Timing tracking
+
+### Basic Example
+
+```typescript
+import { defineCommand } from '@kb-labs/cli-command-kit';
+
+export const myCommand = defineCommand({
+  name: 'my-command',
+  flags: {
+    scope: { type: 'string', required: true },
+    'dry-run': { type: 'boolean', default: false },
+  },
+  async handler(ctx, argv, flags) {
+    ctx.logger?.info('Command started', { scope: flags.scope });
+    ctx.tracker.checkpoint('start');
+    
+    // Business logic
+    
+    return { ok: true };
+  },
+});
+```
+
+### With Analytics
+
+```typescript
+export const myCommand = defineCommand({
+  name: 'my-command',
+  flags: { /* ... */ },
+  analytics: {
+    startEvent: 'MY_COMMAND_STARTED',
+    finishEvent: 'MY_COMMAND_FINISHED',
+    includeFlags: true,
+  },
+  async handler(ctx, argv, flags) {
+    // Analytics events are sent automatically
+    return { ok: true };
+  },
+});
+```
+
+### With Custom Formatter
+
+```typescript
+export const myCommand = defineCommand({
+  name: 'my-command',
+  flags: { /* ... */ },
+  async handler(ctx, argv, flags) {
+    return { ok: true, data: 'result' };
+  },
+  formatter(result, ctx, flags) {
+    if (flags.json) {
+      ctx.output?.json(result);
+    } else {
+      ctx.output?.write(`✓ Success: ${result.data}`);
+    }
+  },
+});
+```
+
+## Enhanced Context
+
+The handler receives an enhanced context with:
+
+- `ctx.tracker` - TimingTracker instance
+- All original `ctx` properties (logger, output, etc.)
+
+## Return Values
+
+Handler can return:
+
+- `number` - Exit code (0 = success, non-zero = error)
+- `{ ok: boolean, ... }` - Result object (ok: true = success, ok: false = error)
+- Defaults to `{ ok: true }` if nothing returned
+

package/packages/shared-command-kit/docs/LOW-LEVEL-API.md

@@ -0,0 +1,105 @@
+# Low-level API
+
+Atomic utilities for building commands manually.
+
+## Flag Validation
+
+### defineFlags
+
+Define a flag schema with automatic type inference.
+
+```typescript
+import { defineFlags } from '@kb-labs/cli-command-kit/flags';
+
+const schema = defineFlags({
+  scope: {
+    type: 'string',
+    required: true,
+    pattern: /^[@a-z0-9-/]+$/i,
+  },
+  'dry-run': {
+    type: 'boolean',
+    default: false,
+  },
+});
+
+type Flags = typeof schema.infer;
+```
+
+### validateFlags
+
+Validate flags against schema.
+
+```typescript
+import { validateFlags } from '@kb-labs/cli-command-kit/flags';
+
+const flags = await validateFlags(rawFlags, schema);
+```
+
+### validateFlagsSafe
+
+Safe version that doesn't throw.
+
+```typescript
+import { validateFlagsSafe } from '@kb-labs/cli-command-kit/flags';
+
+const result = await validateFlagsSafe(rawFlags, schema);
+if (!result.success) {
+  // Handle errors
+}
+```
+
+## Analytics
+
+### trackCommand
+
+Wrapper around analytics SDK.
+
+```typescript
+import { trackCommand } from '@kb-labs/cli-command-kit/analytics';
+
+const { emit, scope } = trackCommand(ctx.analytics, {
+  command: 'my-command',
+  startEvent: 'MY_COMMAND_STARTED',
+  finishEvent: 'MY_COMMAND_FINISHED',
+});
+
+return await scope(async () => {
+  await emit('started', { flags });
+  // business logic
+  await emit('finished', { result: 'success' });
+});
+```
+
+## Error Formatting
+
+### formatError
+
+Format errors for display.
+
+```typescript
+import { formatError } from '@kb-labs/cli-command-kit/errors';
+
+const formatted = formatError(error, {
+  jsonMode: Boolean(flags.json),
+  showStack: Boolean(flags.debug),
+  timingMs: tracker.total(),
+});
+```
+
+## Timing
+
+### TimingTracker
+
+Re-exported from `@kb-labs/shared-cli-ui`.
+
+```typescript
+import { TimingTracker } from '@kb-labs/cli-command-kit/helpers';
+
+const tracker = new TimingTracker();
+tracker.checkpoint('start');
+// ...
+tracker.checkpoint('complete');
+const total = tracker.total();
+```
+

package/packages/shared-command-kit/docs/MIGRATION-GUIDE.md

@@ -0,0 +1,135 @@
+# Migration Guide
+
+Guide for migrating existing commands to use Command Kit.
+
+## Low-level Migration
+
+### Before
+
+```typescript
+export async function myHandler(
+  ctx: CliContext,
+  argv: string[],
+  rawFlags: Record<string, unknown>
+) {
+  const jsonMode = !!rawFlags.json;
+  const scope = rawFlags.scope as string;
+  
+  if (!scope) {
+    ctx.output?.error('--scope is required');
+    return 1;
+  }
+  
+  // business logic
+}
+```
+
+### After
+
+```typescript
+import { defineFlags, validateFlags } from '@kb-labs/cli-command-kit/flags';
+import { TimingTracker } from '@kb-labs/cli-command-kit/helpers';
+import { trackCommand } from '@kb-labs/cli-command-kit/analytics';
+import { formatError } from '@kb-labs/cli-command-kit/errors';
+
+const schema = defineFlags({
+  scope: { type: 'string', required: true },
+  json: { type: 'boolean', default: false },
+});
+
+export async function myHandler(
+  ctx: CliContext,
+  argv: string[],
+  rawFlags: Record<string, unknown>
+) {
+  const tracker = new TimingTracker();
+  
+  try {
+    const flags = await validateFlags(rawFlags, schema);
+    
+    const { emit, scope } = trackCommand(ctx.analytics, {
+      command: 'my-command',
+      startEvent: 'MY_COMMAND_STARTED',
+      finishEvent: 'MY_COMMAND_FINISHED',
+    });
+    
+    return await scope(async () => {
+      await emit('started', { scope: flags.scope });
+      
+      // business logic
+      
+      await emit('finished', { result: 'success' });
+      return 0;
+    });
+  } catch (error) {
+    const formatted = formatError(error, { jsonMode: Boolean(rawFlags.json) });
+    if (rawFlags.json) {
+      ctx.output?.json(formatted.json);
+    } else {
+      ctx.output?.error(formatted.message);
+    }
+    return 1;
+  }
+}
+```
+
+## High-level Migration
+
+### Before
+
+```typescript
+export const run: Command = {
+  name: 'release:run',
+  category: 'release',
+  describe: 'Execute release process',
+  async run(ctx, argv, flags) {
+    const jsonMode = !!flags.json;
+    // ... lots of boilerplate
+  },
+};
+
+export async function runCommand(ctx, argv, flags) {
+  return run.run(ctx, argv, flags);
+}
+```
+
+### After
+
+```typescript
+import { defineCommand } from '@kb-labs/cli-command-kit';
+
+export const runCommand = defineCommand({
+  name: 'release:run',
+  flags: {
+    scope: { type: 'string' },
+    'dry-run': { type: 'boolean', default: false },
+    json: { type: 'boolean', default: false },
+  },
+  analytics: {
+    startEvent: 'RELEASE_RUN_STARTED',
+    finishEvent: 'RELEASE_RUN_FINISHED',
+  },
+  async handler(ctx, argv, flags) {
+    // flags are typed and validated automatically
+    // ctx.tracker is available
+    // analytics is handled automatically
+    
+    ctx.logger?.info('Release started', { scope: flags.scope });
+    ctx.tracker.checkpoint('planning');
+    
+    // business logic
+    
+    return { ok: true, published: 5 };
+  },
+});
+```
+
+## Key Changes
+
+1. **Remove Command object wrapper** - Export function directly
+2. **Use defineFlags** - Get type-safe flags
+3. **Use defineCommand** - Get all boilerplate handled automatically
+4. **Remove manual validation** - Handled by kit
+5. **Remove manual analytics** - Handled by kit
+6. **Remove manual error handling** - Handled by kit
+

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

@@ -0,0 +1,14 @@
+import preset from '@kb-labs/devkit/eslint/node';
+
+export default [
+  ...preset,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        allowDefaultProject: true,
+      },
+    },
+  },
+];
+

package/packages/shared-command-kit/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@kb-labs/shared-command-kit",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Command Kit for KB Labs CLI - utilities and high-level API for building commands",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./flags": {
+      "import": "./dist/flags/index.js",
+      "types": "./dist/flags/index.d.ts"
+    },
+    "./analytics": {
+      "import": "./dist/analytics/index.js",
+      "types": "./dist/analytics/index.d.ts"
+    },
+    "./errors": {
+      "import": "./dist/errors/index.js",
+      "types": "./dist/errors/index.d.ts"
+    },
+    "./helpers": {
+      "import": "./dist/helpers/index.js",
+      "types": "./dist/helpers/index.d.ts"
+    },
+    "./studio": {
+      "import": "./dist/studio/index.js",
+      "types": "./dist/studio/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@kb-labs/core-platform": "link:../../../kb-labs-core/packages/core-platform",
+    "@kb-labs/core-resource-broker": "link:../../../kb-labs-core/packages/core-resource-broker",
+    "@kb-labs/core-runtime": "link:../../../kb-labs-core/packages/core-runtime",
+    "@kb-labs/plugin-contracts": "link:../../../../infra/kb-labs-plugin/packages/plugin-contracts",
+    "@kb-labs/plugin-runtime": "link:../../../../infra/kb-labs-plugin/packages/plugin-runtime",
+    "@kb-labs/shared-cli-ui": "workspace:*",
+    "zod": "^3.23.8",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "@types/node": "^24.3.3",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@9.11.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/shared-command-kit/prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "extends": "@kb-labs/devkit/prettier/index.json"
+}
+