@kb-labs/commit-cli 0.5.0

package/README.md

@@ -0,0 +1,120 @@
+# @kb-labs/plugin-template-cli
+
+Reference CLI/REST/Studio plugin package for KB Labs Plugin Template.
+
+## Vision & Purpose
+
+**@kb-labs/plugin-template-cli** is the canonical example plugin package used by `@kb-labs/plugin-template`.  
+It shows how to implement a plugin that exposes:
+
+- a **CLI command** (Hello),
+- a **REST handler**, and
+- a **Studio widget**,
+
+all driven by a single manifest and contracts package.
+
+## Package Status
+
+- **Version**: 0.1.0  
+- **Stage**: Stable (template)  
+- **Status**: Reference Implementation ✅
+
+## Architecture
+
+### High-Level Overview
+
+```
+plugin-cli
+    │
+    ├──► contracts     (from @kb-labs/plugin-template-contracts)
+    ├──► shared        (constants/helpers)
+    ├──► domain        (Greeting entity and invariants)
+    ├──► application   (use-cases: create greeting, etc.)
+    ├──► cli           (Hello command wiring)
+    ├──► rest          (Hello REST handler + schema)
+    └──► studio        (Hello Studio widget)
+```
+
+### Key Components
+
+- `src/domain/`: `Greeting` entity and domain rules
+- `src/application/`: use-cases that orchestrate domain logic
+- `src/cli/commands/hello/*`: CLI command implementation
+- `src/rest/handlers/hello-handler.ts`: REST handler bound to manifest
+- `src/studio/widgets/hello-widget.tsx`: Studio widget implementation
+- `src/manifest.v2.ts`: Plugin manifest v2 (CLI/REST/Studio wiring)
+
+## Features
+
+- **Single-source manifest** for CLI/REST/Studio surfaces
+- **Layered architecture** (shared → domain → application → interface)
+- **Type-safe contracts** via `@kb-labs/plugin-template-contracts`
+- **Hello-world flow** demonstrating end-to-end plugin wiring
+
+## Exports
+
+From `src/index.ts`:
+
+- `manifest`: Plugin Manifest V2
+- All public surfaces:
+  - CLI command exports
+  - domain/application/shared re-exports
+
+## Dependencies
+
+### Runtime
+
+- `@kb-labs/setup-operations`: reusable setup operations
+- `@kb-labs/plugin-manifest`: manifest types and helpers
+- `@kb-labs/plugin-template-contracts`: public contracts for this template plugin
+- `@kb-labs/shared-cli-ui`: shared CLI UI helpers
+- `react`, `react-dom`, `zod`
+
+### Development
+
+- `@kb-labs/devkit`: shared TS/ESLint/Vitest/TSUP presets
+- `typescript`, `tsup`, `vitest`, `rimraf`
+
+## Scripts
+
+From `kb-labs-plugin-template` repo root:
+
+```bash
+pnpm install
+pnpm --filter @kb-labs/plugin-template-cli build
+pnpm --filter @kb-labs/plugin-template-cli test
+```
+
+To run sandboxes, see the root `README.md` (`pnpm sandbox:cli`, `sandbox:rest`, `sandbox:studio`).
+
+## Command Implementation
+
+This template demonstrates **three different approaches** to implementing CLI commands:
+
+1. **High-level wrapper (`defineCommand`)** - Recommended for most cases
+2. **Low-level atomic tools** - For maximum control
+3. **Hybrid approach** - Combining both
+
+See [`COMMAND_IMPLEMENTATION_GUIDE.md`](./COMMAND_IMPLEMENTATION_GUIDE.md) for detailed explanations and examples.
+
+### Quick Start
+
+The `template:hello` command in `src/cli/commands/hello/run.ts` shows all three approaches with working code examples. The default implementation uses Approach 1 (`defineCommand`), which provides:
+
+- ✅ Zero-boilerplate flag validation
+- ✅ Automatic analytics integration
+- ✅ Structured logging
+- ✅ Error handling
+- ✅ Timing tracking
+- ✅ JSON output mode
+
+## Customising for Your Plugin
+
+When using this as a starting point:
+
+- Rename the package in `package.json` (e.g. `@kb-labs/my-plugin-cli`)
+- Update manifest IDs and the contracts package
+- Replace the Hello flow with your own domain, use-cases, and surfaces
+- Choose the command implementation approach that fits your needs (see `COMMAND_IMPLEMENTATION_GUIDE.md`)
+
+

package/dist/cli/commands/apply.d.ts

@@ -0,0 +1,22 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+
+/**
+ * commit:apply command
+ * Apply current commit plan
+ */
+type ApplyInput = {
+    force?: boolean;
+    json?: boolean;
+    scope?: string;
+};
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, ApplyInput, {
+    commits: {
+        message: string;
+        id: string;
+        sha: string;
+    }[];
+    success: boolean;
+    errors: string[];
+}>;
+
+export { _default as default };

package/dist/cli/commands/apply.js

@@ -0,0 +1,132 @@
+import { defineCommand, findRepoRoot, useConfig, useLoader } from '@kb-labs/sdk';
+import { loadPlan, applyCommitPlan, saveToHistory, clearPlan } from '@kb-labs/commit-core';
+import { resolveCommitConfig } from '@kb-labs/commit-contracts';
+import * as path from 'path';
+
+// src/cli/commands/apply.ts
+function resolveScopePath(baseCwd, scopeId = "root", scopes) {
+  const scopeDef = scopes?.find((s) => s.id === scopeId);
+  const relativePath = scopeDef?.path ?? (scopeId === "root" ? "." : scopeId);
+  return relativePath === "." ? baseCwd : path.join(baseCwd, relativePath);
+}
+
+// src/cli/commands/apply.ts
+var apply_default = defineCommand({
+  id: "commit:apply",
+  description: "Apply current commit plan",
+  handler: {
+    async execute(ctx, input) {
+      const startTime = Date.now();
+      const cwd = await findRepoRoot(ctx.cwd || process.cwd()) ?? process.cwd();
+      const scope = input.scope ?? "root";
+      const fileConfig = await useConfig();
+      const config = resolveCommitConfig(fileConfig ?? {});
+      const scopeCwd = resolveScopePath(cwd, scope, config.scope?.scopes);
+      const loadLoader = useLoader("Loading commit plan...");
+      loadLoader.start();
+      const plan = await loadPlan(cwd, scope);
+      if (!plan) {
+        loadLoader.fail("No commit plan found");
+        ctx.ui?.error?.("Run `kb commit:generate` first.");
+        return {
+          exitCode: 1
+        };
+      }
+      if (plan.commits.length === 0) {
+        loadLoader.stop();
+        ctx.ui?.warn?.("Commit plan is empty. Nothing to apply.");
+        return {
+          exitCode: 0,
+          result: {
+            success: true,
+            commits: [],
+            errors: []
+          },
+          meta: {
+            timing: Date.now() - startTime
+          }
+        };
+      }
+      loadLoader.succeed(`Loaded plan with ${plan.commits.length} commit(s)`);
+      const applyLoader = useLoader(`Applying ${plan.commits.length} commit(s)...`);
+      applyLoader.start();
+      const result = await applyCommitPlan(scopeCwd, plan, {
+        force: input.force
+      });
+      if (result.success) {
+        await saveToHistory(cwd, plan, result, scope);
+        await clearPlan(cwd, scope);
+        applyLoader.succeed(`Applied ${result.appliedCommits.length} commit(s) successfully`);
+      } else {
+        applyLoader.fail("Failed to apply commits");
+      }
+      const output = {
+        success: result.success,
+        commits: result.appliedCommits.map((c) => ({
+          id: c.groupId,
+          sha: c.sha,
+          message: c.message
+        })),
+        errors: result.errors
+      };
+      if (input.json) {
+        ctx.ui?.json?.(output);
+      } else {
+        if (result.success) {
+          const commitsItems = result.appliedCommits.map((commit) => {
+            return `${commit.sha.substring(0, 7)} ${commit.message}`;
+          });
+          const sections = [];
+          if (commitsItems.length > 0) {
+            sections.push({
+              header: "Applied Commits",
+              items: commitsItems
+            });
+          }
+          const summaryItems = [
+            `Total commits: ${result.appliedCommits.length}`,
+            "Status: \u2705 Success"
+          ];
+          sections.unshift({
+            header: "Summary",
+            items: summaryItems
+          });
+          const timing = Date.now() - startTime;
+          ctx.ui?.success?.("Commits applied successfully", {
+            title: "Apply Commit Plan",
+            sections,
+            timing
+          });
+        } else {
+          const errorItems = result.errors.map((error) => error);
+          const timing = Date.now() - startTime;
+          ctx.ui?.error?.("Failed to apply commits", {
+            title: "Apply Commit Plan",
+            sections: [
+              {
+                header: "Summary",
+                items: [`Total errors: ${result.errors.length}`]
+              },
+              {
+                header: "Errors",
+                items: errorItems
+              }
+            ],
+            timing
+          });
+        }
+      }
+      return {
+        exitCode: result.success ? 0 : 1,
+        result: output,
+        meta: {
+          timing: Date.now() - startTime
+        }
+      };
+    }
+  }
+});
+
+export { apply_default as default };
+//# sourceMappingURL=apply.js.map
+//# sourceMappingURL=apply.js.map

package/dist/cli/commands/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/rest/handlers/scope-resolver.ts","../../../src/cli/commands/apply.ts"],"names":[],"mappings":";;;;;;AAaO,SAAS,gBAAA,CACd,OAAA,EACA,OAAA,GAAkB,MAAA,EAClB,MAAA,EACQ;AACR,EAAA,MAAM,WAAW,MAAA,EAAQ,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,OAAO,CAAA;AACrD,EAAA,MAAM,YAAA,GAAe,QAAA,EAAU,IAAA,KAAS,OAAA,KAAY,SAAS,GAAA,GAAM,OAAA,CAAA;AACnE,EAAA,OAAO,YAAA,KAAiB,GAAA,GAAM,OAAA,GAAe,IAAA,CAAA,IAAA,CAAK,SAAS,YAAY,CAAA;AACzE;;;ACOA,IAAO,gBAAQ,aAAA,CAAc;AAAA,EAC3B,EAAA,EAAI,cAAA;AAAA,EACJ,WAAA,EAAa,2BAAA;AAAA,EAEb,OAAA,EAAS;AAAA,IACP,MAAM,OAAA,CAAQ,GAAA,EAAsB,KAAA,EAAyC;AAC3E,MAAA,MAAM,SAAA,GAAY,KAAK,GAAA,EAAI;AAC3B,MAAA,MAAM,GAAA,GAAO,MAAM,YAAA,CAAa,GAAA,CAAI,GAAA,IAAO,QAAQ,GAAA,EAAK,CAAA,IAAM,OAAA,CAAQ,GAAA,EAAI;AAE1E,MAAA,MAAM,KAAA,GAAQ,MAAM,KAAA,IAAS,MAAA;AAC7B,MAAA,MAAM,UAAA,GAAa,MAAM,SAAA,EAAuC;AAChE,MAAA,MAAM,MAAA,GAAS,mBAAA,CAAoB,UAAA,IAAc,EAAE,CAAA;AACnD,MAAA,MAAM,WAAW,gBAAA,CAAiB,GAAA,EAAK,KAAA,EAAO,MAAA,CAAO,OAAO,MAAM,CAAA;AAGlE,MAAA,MAAM,UAAA,GAAa,UAAU,wBAAwB,CAAA;AACrD,MAAA,UAAA,CAAW,KAAA,EAAM;AACjB,MAAA,MAAM,IAAA,GAAO,MAAM,QAAA,CAAS,GAAA,EAAK,KAAK,CAAA;AAEtC,MAAA,IAAI,CAAC,IAAA,EAAM;AACT,QAAA,UAAA,CAAW,KAAK,sBAAsB,CAAA;AACtC,QAAA,GAAA,CAAI,EAAA,EAAI,QAAQ,iCAAiC,CAAA;AACjD,QAAA,OAAO;AAAA,UACL,QAAA,EAAU;AAAA,SACZ;AAAA,MACF;AAEA,MAAA,IAAI,IAAA,CAAK,OAAA,CAAQ,MAAA,KAAW,CAAA,EAAG;AAC7B,QAAA,UAAA,CAAW,IAAA,EAAK;AAChB,QAAA,GAAA,CAAI,EAAA,EAAI,OAAO,yCAAyC,CAAA;AACxD,QAAA,OAAO;AAAA,UACL,QAAA,EAAU,CAAA;AAAA,UACV,MAAA,EAAQ;AAAA,YACN,OAAA,EAAS,IAAA;AAAA,YACT,SAAS,EAAC;AAAA,YACV,QAAQ;AAAC,WACX;AAAA,UACA,IAAA,EAAM;AAAA,YACJ,MAAA,EAAQ,IAAA,CAAK,GAAA,EAAI,GAAI;AAAA;AACvB,SACF;AAAA,MACF;AACA,MAAA,UAAA,CAAW,OAAA,CAAQ,CAAA,iBAAA,EAAoB,IAAA,CAAK,OAAA,CAAQ,MAAM,CAAA,UAAA,CAAY,CAAA;AAGtE,MAAA,MAAM,cAAc,SAAA,CAAU,CAAA,SAAA,EAAY,IAAA,CAAK,OAAA,CAAQ,MAAM,CAAA,aAAA,CAAe,CAAA;AAC5E,MAAA,WAAA,CAAY,KAAA,EAAM;AAClB,MAAA,MAAM,MAAA,GAAS,MAAM,eAAA,CAAgB,QAAA,EAAU,IAAA,EAAM;AAAA,QACnD,OAAO,KAAA,CAAM;AAAA,OACd,CAAA;AAGD,MAAA,IAAI,OAAO,OAAA,EAAS;AAClB,QAAA,MAAM,aAAA,CAAc,GAAA,EAAK,IAAA,EAAM,MAAA,EAAQ,KAAK,CAAA;AAC5C,QAAA,MAAM,SAAA,CAAU,KAAK,KAAK,CAAA;AAC1B,QAAA,WAAA,CAAY,OAAA,CAAQ,CAAA,QAAA,EAAW,MAAA,CAAO,cAAA,CAAe,MAAM,CAAA,uBAAA,CAAyB,CAAA;AAAA,MACtF,CAAA,MAAO;AACL,QAAA,WAAA,CAAY,KAAK,yBAAyB,CAAA;AAAA,MAC5C;AAGA,MAAA,MAAM,MAAA,GAAsB;AAAA,QAC1B,SAAS,MAAA,CAAO,OAAA;AAAA,QAChB,OAAA,EAAS,MAAA,CAAO,cAAA,CAAe,GAAA,CAAI,CAAC,CAAA,MAAO;AAAA,UACzC,IAAI,CAAA,CAAE,OAAA;AAAA,UACN,KAAK,CAAA,CAAE,GAAA;AAAA,UACP,SAAS,CAAA,CAAE;AAAA,SACb,CAAE,CAAA;AAAA,QACF,QAAQ,MAAA,CAAO;AAAA,OACjB;AAEA,MAAA,IAAI,MAAM,IAAA,EAAM;AACd,QAAA,GAAA,CAAI,EAAA,EAAI,OAAO,MAAM,CAAA;AAAA,MACvB,CAAA,MAAO;AACL,QAAA,IAAI,OAAO,OAAA,EAAS;AAElB,UAAA,MAAM,YAAA,GAAe,MAAA,CAAO,cAAA,CAAe,GAAA,CAAI,CAAC,MAAA,KAAW;AACzD,YAAA,OAAO,CAAA,EAAG,OAAO,GAAA,CAAI,SAAA,CAAU,GAAG,CAAC,CAAC,CAAA,CAAA,EAAI,MAAA,CAAO,OAAO,CAAA,CAAA;AAAA,UACxD,CAAC,CAAA;AAED,UAAA,MAAM,WAAwD,EAAC;AAE/D,UAAA,IAAI,YAAA,CAAa,SAAS,CAAA,EAAG;AAC3B,YAAA,QAAA,CAAS,IAAA,CAAK;AAAA,cACZ,MAAA,EAAQ,iBAAA;AAAA,cACR,KAAA,EAAO;AAAA,aACR,CAAA;AAAA,UACH;AAEA,UAAA,MAAM,YAAA,GAAyB;AAAA,YAC7B,CAAA,eAAA,EAAkB,MAAA,CAAO,cAAA,CAAe,MAAM,CAAA,CAAA;AAAA,YAC9C;AAAA,WACF;AAEA,UAAA,QAAA,CAAS,OAAA,CAAQ;AAAA,YACf,MAAA,EAAQ,SAAA;AAAA,YACR,KAAA,EAAO;AAAA,WACR,CAAA;AAED,UAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAE5B,UAAA,GAAA,CAAI,EAAA,EAAI,UAAU,8BAAA,EAAgC;AAAA,YAChD,KAAA,EAAO,mBAAA;AAAA,YACP,QAAA;AAAA,YACA;AAAA,WACD,CAAA;AAAA,QACH,CAAA,MAAO;AACL,UAAA,MAAM,aAAa,MAAA,CAAO,MAAA,CAAO,GAAA,CAAI,CAAC,UAAU,KAAK,CAAA;AACrD,UAAA,MAAM,MAAA,GAAS,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAE5B,UAAA,GAAA,CAAI,EAAA,EAAI,QAAQ,yBAAA,EAA2B;AAAA,YACzC,KAAA,EAAO,mBAAA;AAAA,YACP,QAAA,EAAU;AAAA,cACR;AAAA,gBACE,MAAA,EAAQ,SAAA;AAAA,gBACR,OAAO,CAAC,CAAA,cAAA,EAAiB,MAAA,CAAO,MAAA,CAAO,MAAM,CAAA,CAAE;AAAA,eACjD;AAAA,cACA;AAAA,gBACE,MAAA,EAAQ,QAAA;AAAA,gBACR,KAAA,EAAO;AAAA;AACT,aACF;AAAA,YACA;AAAA,WACD,CAAA;AAAA,QACH;AAAA,MACF;AAEA,MAAA,OAAO;AAAA,QACL,QAAA,EAAU,MAAA,CAAO,OAAA,GAAU,CAAA,GAAI,CAAA;AAAA,QAC/B,MAAA,EAAQ,MAAA;AAAA,QACR,IAAA,EAAM;AAAA,UACJ,MAAA,EAAQ,IAAA,CAAK,GAAA,EAAI,GAAI;AAAA;AACvB,OACF;AAAA,IACF;AAAA;AAEJ,CAAC","file":"apply.js","sourcesContent":["import * as path from 'node:path';\nimport type { CommitScope } from '@kb-labs/commit-contracts';\n\n/**\n * Resolves a scope id to an absolute filesystem path.\n *\n * Looks up the scope in the provided scopes array by id.\n * Falls back to treating the id as a relative path from baseCwd (legacy compat).\n *\n * @param baseCwd  - Workspace root (ctx.cwd)\n * @param scopeId  - Scope identifier, e.g. \"root\", \"public/kb-labs\"\n * @param scopes   - Configured scopes from CommitPluginConfig.scope.scopes\n */\nexport function resolveScopePath(\n  baseCwd: string,\n  scopeId: string = 'root',\n  scopes?: CommitScope[],\n): string {\n  const scopeDef = scopes?.find((s) => s.id === scopeId);\n  const relativePath = scopeDef?.path ?? (scopeId === 'root' ? '.' : scopeId);\n  return relativePath === '.' ? baseCwd : path.join(baseCwd, relativePath);\n}\n","/**\n * commit:apply command\n * Apply current commit plan\n */\n\nimport { defineCommand, useLoader, useConfig, findRepoRoot, type PluginContextV3 } from '@kb-labs/sdk';\nimport {\n  applyCommitPlan,\n  loadPlan,\n  saveToHistory,\n  clearPlan,\n} from '@kb-labs/commit-core';\nimport type { ApplyOutput, CommitPluginConfig } from '@kb-labs/commit-contracts';\nimport { resolveCommitConfig } from '@kb-labs/commit-contracts';\nimport { resolveScopePath } from '../../rest/handlers/scope-resolver';\n\ntype ApplyInput = {\n  force?: boolean;\n  json?: boolean;\n  scope?: string;\n};\n\ntype ApplyResult = {\n  exitCode: number;\n  result?: ApplyOutput;\n  meta?: Record<string, unknown>;\n};\n\nexport default defineCommand({\n  id: 'commit:apply',\n  description: 'Apply current commit plan',\n\n  handler: {\n    async execute(ctx: PluginContextV3, input: ApplyInput): Promise<ApplyResult> {\n      const startTime = Date.now();\n      const cwd = (await findRepoRoot(ctx.cwd || process.cwd())) ?? process.cwd();\n\n      const scope = input.scope ?? 'root';\n      const fileConfig = await useConfig<Partial<CommitPluginConfig>>();\n      const config = resolveCommitConfig(fileConfig ?? {});\n      const scopeCwd = resolveScopePath(cwd, scope, config.scope?.scopes);\n\n      // Load current plan\n      const loadLoader = useLoader('Loading commit plan...');\n      loadLoader.start();\n      const plan = await loadPlan(cwd, scope);\n\n      if (!plan) {\n        loadLoader.fail('No commit plan found');\n        ctx.ui?.error?.('Run `kb commit:generate` first.');\n        return {\n          exitCode: 1,\n        };\n      }\n\n      if (plan.commits.length === 0) {\n        loadLoader.stop();\n        ctx.ui?.warn?.('Commit plan is empty. Nothing to apply.');\n        return {\n          exitCode: 0,\n          result: {\n            success: true,\n            commits: [],\n            errors: [],\n          },\n          meta: {\n            timing: Date.now() - startTime,\n          },\n        };\n      }\n      loadLoader.succeed(`Loaded plan with ${plan.commits.length} commit(s)`);\n\n      // Apply plan\n      const applyLoader = useLoader(`Applying ${plan.commits.length} commit(s)...`);\n      applyLoader.start();\n      const result = await applyCommitPlan(scopeCwd, plan, {\n        force: input.force,\n      });\n\n      // Save to history and clear current plan on success\n      if (result.success) {\n        await saveToHistory(cwd, plan, result, scope);\n        await clearPlan(cwd, scope);\n        applyLoader.succeed(`Applied ${result.appliedCommits.length} commit(s) successfully`);\n      } else {\n        applyLoader.fail('Failed to apply commits');\n      }\n\n      // Output\n      const output: ApplyOutput = {\n        success: result.success,\n        commits: result.appliedCommits.map((c) => ({\n          id: c.groupId,\n          sha: c.sha,\n          message: c.message,\n        })),\n        errors: result.errors,\n      };\n\n      if (input.json) {\n        ctx.ui?.json?.(output);\n      } else {\n        if (result.success) {\n          // Build commits section\n          const commitsItems = result.appliedCommits.map((commit) => {\n            return `${commit.sha.substring(0, 7)} ${commit.message}`;\n          });\n\n          const sections: Array<{ header?: string; items: string[] }> = [];\n\n          if (commitsItems.length > 0) {\n            sections.push({\n              header: 'Applied Commits',\n              items: commitsItems,\n            });\n          }\n\n          const summaryItems: string[] = [\n            `Total commits: ${result.appliedCommits.length}`,\n            'Status: ✅ Success',\n          ];\n\n          sections.unshift({\n            header: 'Summary',\n            items: summaryItems,\n          });\n\n          const timing = Date.now() - startTime;\n\n          ctx.ui?.success?.('Commits applied successfully', {\n            title: 'Apply Commit Plan',\n            sections,\n            timing,\n          });\n        } else {\n          const errorItems = result.errors.map((error) => error);\n          const timing = Date.now() - startTime;\n\n          ctx.ui?.error?.('Failed to apply commits', {\n            title: 'Apply Commit Plan',\n            sections: [\n              {\n                header: 'Summary',\n                items: [`Total errors: ${result.errors.length}`],\n              },\n              {\n                header: 'Errors',\n                items: errorItems,\n              },\n            ],\n            timing,\n          });\n        }\n      }\n\n      return {\n        exitCode: result.success ? 0 : 1,\n        result: output,\n        meta: {\n          timing: Date.now() - startTime,\n        },\n      };\n    },\n  },\n});\n"]}

package/dist/cli/commands/flags.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared command flags definitions
+ *
+ * DRY pattern: Define flags once, use in both manifest and command handlers.
+ */
+/**
+ * Flags for commit:generate command
+ */
+declare const generateFlags: {
+    readonly scope: {
+        readonly type: "string";
+        readonly description: "Filter by package name (@kb-labs/core), wildcard (@kb-labs/*), or path pattern (packages/**)";
+        readonly alias: "s";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON";
+        readonly default: false;
+    };
+};
+type GenerateFlags = typeof generateFlags;
+/**
+ * Flags for commit:apply command
+ */
+declare const applyFlags: {
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Apply even if working tree changed";
+        readonly default: false;
+        readonly alias: "f";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON";
+        readonly default: false;
+    };
+};
+type ApplyFlags = typeof applyFlags;
+/**
+ * Flags for commit:push command
+ */
+declare const pushFlags: {
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Force push (dangerous!)";
+        readonly default: false;
+        readonly alias: "f";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON";
+        readonly default: false;
+    };
+};
+type PushFlags = typeof pushFlags;
+/**
+ * Flags for commit (run) command - combines generate + apply + optional push
+ */
+declare const runFlags: {
+    readonly scope: {
+        readonly type: "string";
+        readonly description: "Filter by package name (@kb-labs/core), wildcard (@kb-labs/*), or path pattern (packages/**)";
+        readonly alias: "s";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON";
+        readonly default: false;
+    };
+    readonly 'dry-run': {
+        readonly type: "boolean";
+        readonly description: "Generate plan only, do not apply";
+        readonly default: false;
+    };
+    readonly 'with-push': {
+        readonly type: "boolean";
+        readonly description: "Push after apply";
+        readonly default: false;
+    };
+};
+type RunFlags = typeof runFlags;
+/**
+ * Common json-only flags for simple commands
+ */
+declare const jsonOnlyFlags: {
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON";
+        readonly default: false;
+    };
+};
+type JsonOnlyFlags = typeof jsonOnlyFlags;
+/**
+ * Empty flags for commands that take no arguments
+ */
+declare const emptyFlags: {};
+type EmptyFlags = typeof emptyFlags;
+
+export { type ApplyFlags, type EmptyFlags, type GenerateFlags, type JsonOnlyFlags, type PushFlags, type RunFlags, applyFlags, emptyFlags, generateFlags, jsonOnlyFlags, pushFlags, runFlags };

package/dist/cli/commands/flags.js

@@ -0,0 +1,73 @@
+// src/cli/commands/flags.ts
+var generateFlags = {
+  scope: {
+    type: "string",
+    description: "Filter by package name (@kb-labs/core), wildcard (@kb-labs/*), or path pattern (packages/**)",
+    alias: "s"
+  },
+  json: {
+    type: "boolean",
+    description: "Output JSON",
+    default: false
+  }
+};
+var applyFlags = {
+  force: {
+    type: "boolean",
+    description: "Apply even if working tree changed",
+    default: false,
+    alias: "f"
+  },
+  json: {
+    type: "boolean",
+    description: "Output JSON",
+    default: false
+  }
+};
+var pushFlags = {
+  force: {
+    type: "boolean",
+    description: "Force push (dangerous!)",
+    default: false,
+    alias: "f"
+  },
+  json: {
+    type: "boolean",
+    description: "Output JSON",
+    default: false
+  }
+};
+var runFlags = {
+  scope: {
+    type: "string",
+    description: "Filter by package name (@kb-labs/core), wildcard (@kb-labs/*), or path pattern (packages/**)",
+    alias: "s"
+  },
+  json: {
+    type: "boolean",
+    description: "Output JSON",
+    default: false
+  },
+  "dry-run": {
+    type: "boolean",
+    description: "Generate plan only, do not apply",
+    default: false
+  },
+  "with-push": {
+    type: "boolean",
+    description: "Push after apply",
+    default: false
+  }
+};
+var jsonOnlyFlags = {
+  json: {
+    type: "boolean",
+    description: "Output JSON",
+    default: false
+  }
+};
+var emptyFlags = {};
+
+export { applyFlags, emptyFlags, generateFlags, jsonOnlyFlags, pushFlags, runFlags };
+//# sourceMappingURL=flags.js.map
+//# sourceMappingURL=flags.js.map

package/dist/cli/commands/flags.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/cli/commands/flags.ts"],"names":[],"mappings":";AASO,IAAM,aAAA,GAAgB;AAAA,EAC3B,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,WAAA,EAAa,8FAAA;AAAA,IACb,KAAA,EAAO;AAAA,GACT;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,aAAA;AAAA,IACb,OAAA,EAAS;AAAA;AAEb;AAOO,IAAM,UAAA,GAAa;AAAA,EACxB,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,oCAAA;AAAA,IACb,OAAA,EAAS,KAAA;AAAA,IACT,KAAA,EAAO;AAAA,GACT;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,aAAA;AAAA,IACb,OAAA,EAAS;AAAA;AAEb;AAOO,IAAM,SAAA,GAAY;AAAA,EACvB,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,yBAAA;AAAA,IACb,OAAA,EAAS,KAAA;AAAA,IACT,KAAA,EAAO;AAAA,GACT;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,aAAA;AAAA,IACb,OAAA,EAAS;AAAA;AAEb;AAOO,IAAM,QAAA,GAAW;AAAA,EACtB,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,WAAA,EAAa,8FAAA;AAAA,IACb,KAAA,EAAO;AAAA,GACT;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,aAAA;AAAA,IACb,OAAA,EAAS;AAAA,GACX;AAAA,EACA,SAAA,EAAW;AAAA,IACT,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,kCAAA;AAAA,IACb,OAAA,EAAS;AAAA,GACX;AAAA,EACA,WAAA,EAAa;AAAA,IACX,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,kBAAA;AAAA,IACb,OAAA,EAAS;AAAA;AAEb;AAOO,IAAM,aAAA,GAAgB;AAAA,EAC3B,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,SAAA;AAAA,IACN,WAAA,EAAa,aAAA;AAAA,IACb,OAAA,EAAS;AAAA;AAEb;AAOO,IAAM,aAAa","file":"flags.js","sourcesContent":["/**\n * Shared command flags definitions\n *\n * DRY pattern: Define flags once, use in both manifest and command handlers.\n */\n\n/**\n * Flags for commit:generate command\n */\nexport const generateFlags = {\n  scope: {\n    type: 'string',\n    description: 'Filter by package name (@kb-labs/core), wildcard (@kb-labs/*), or path pattern (packages/**)',\n    alias: 's',\n  },\n  json: {\n    type: 'boolean',\n    description: 'Output JSON',\n    default: false,\n  },\n} as const;\n\nexport type GenerateFlags = typeof generateFlags;\n\n/**\n * Flags for commit:apply command\n */\nexport const applyFlags = {\n  force: {\n    type: 'boolean',\n    description: 'Apply even if working tree changed',\n    default: false,\n    alias: 'f',\n  },\n  json: {\n    type: 'boolean',\n    description: 'Output JSON',\n    default: false,\n  },\n} as const;\n\nexport type ApplyFlags = typeof applyFlags;\n\n/**\n * Flags for commit:push command\n */\nexport const pushFlags = {\n  force: {\n    type: 'boolean',\n    description: 'Force push (dangerous!)',\n    default: false,\n    alias: 'f',\n  },\n  json: {\n    type: 'boolean',\n    description: 'Output JSON',\n    default: false,\n  },\n} as const;\n\nexport type PushFlags = typeof pushFlags;\n\n/**\n * Flags for commit (run) command - combines generate + apply + optional push\n */\nexport const runFlags = {\n  scope: {\n    type: 'string',\n    description: 'Filter by package name (@kb-labs/core), wildcard (@kb-labs/*), or path pattern (packages/**)',\n    alias: 's',\n  },\n  json: {\n    type: 'boolean',\n    description: 'Output JSON',\n    default: false,\n  },\n  'dry-run': {\n    type: 'boolean',\n    description: 'Generate plan only, do not apply',\n    default: false,\n  },\n  'with-push': {\n    type: 'boolean',\n    description: 'Push after apply',\n    default: false,\n  },\n} as const;\n\nexport type RunFlags = typeof runFlags;\n\n/**\n * Common json-only flags for simple commands\n */\nexport const jsonOnlyFlags = {\n  json: {\n    type: 'boolean',\n    description: 'Output JSON',\n    default: false,\n  },\n} as const;\n\nexport type JsonOnlyFlags = typeof jsonOnlyFlags;\n\n/**\n * Empty flags for commands that take no arguments\n */\nexport const emptyFlags = {} as const;\n\nexport type EmptyFlags = typeof emptyFlags;\n"]}

package/dist/cli/commands/generate.d.ts

@@ -0,0 +1,45 @@
+import * as _kb_labs_shared_command_kit from '@kb-labs/shared-command-kit';
+
+/**
+ * commit:generate command
+ * Generate commit plan from git changes
+ */
+declare const _default: _kb_labs_shared_command_kit.CommandHandlerV3<unknown, any, {
+    plan: {
+        schemaVersion: "1.0";
+        createdAt: string;
+        repoRoot: string;
+        gitStatus: {
+            staged: string[];
+            unstaged: string[];
+            untracked: string[];
+        };
+        commits: {
+            message: string;
+            type: "feat" | "fix" | "refactor" | "chore" | "docs" | "test" | "build" | "ci" | "perf";
+            id: string;
+            files: string[];
+            releaseHint: "none" | "patch" | "minor" | "major";
+            breaking: boolean;
+            scope?: string | undefined;
+            body?: string | undefined;
+            reasoning?: {
+                newBehavior: boolean;
+                fixesBug: boolean;
+                internalOnly: boolean;
+                explanation: string;
+                confidence: number;
+            } | undefined;
+        }[];
+        metadata: {
+            totalFiles: number;
+            totalCommits: number;
+            llmUsed: boolean;
+            tokensUsed?: number | undefined;
+            escalated?: boolean | undefined;
+        };
+    };
+    planPath: string;
+}>;
+
+export { _default as default };

package/dist/cli/commands/generate.js

@@ -0,0 +1,149 @@
+import { defineCommand, useLLM, findRepoRoot, useConfig, useLoader, displayArtifacts } from '@kb-labs/sdk';
+import { stat } from 'fs/promises';
+import { getGitStatus, hasChanges, generateCommitPlan, savePlan, getCurrentPlanPath } from '@kb-labs/commit-core';
+import { commitEnv, resolveCommitConfig } from '@kb-labs/commit-contracts';
+import * as path from 'path';
+
+// src/cli/commands/generate.ts
+function resolveScopePath(baseCwd, scopeId = "root", scopes) {
+  const scopeDef = scopes?.find((s) => s.id === scopeId);
+  const relativePath = scopeDef?.path ?? (scopeId === "root" ? "." : scopeId);
+  return relativePath === "." ? baseCwd : path.join(baseCwd, relativePath);
+}
+
+// src/cli/commands/generate.ts
+var generate_default = defineCommand({
+  id: "commit:generate",
+  description: "Generate commit plan from git changes",
+  handler: {
+    async execute(ctx, input) {
+      const startTime = Date.now();
+      const llm = useLLM();
+      const cwd = await findRepoRoot(ctx.cwd || process.cwd()) ?? process.cwd();
+      const fileConfig = await useConfig();
+      const env = commitEnv.parse(ctx.runtime);
+      const config = resolveCommitConfig(fileConfig ?? {}, env);
+      const flags = input.flags ?? input;
+      const effectiveScope = flags.scope ?? config.scope?.default ?? "root";
+      const scopeCwd = resolveScopePath(cwd, effectiveScope, config.scope?.scopes);
+      const allowSecrets = flags["allow-secrets"] ?? false;
+      const autoConfirm = flags.yes ?? false;
+      const statusLoader = useLoader("Checking git status...");
+      statusLoader.start();
+      const status = await getGitStatus(scopeCwd);
+      if (!hasChanges(status)) {
+        statusLoader.stop();
+        ctx.ui?.warn?.("No changes to commit");
+        return {
+          exitCode: 1
+        };
+      }
+      statusLoader.succeed("Found changes to commit");
+      const analyzeLoader = useLoader("Analyzing changes...");
+      analyzeLoader.start();
+      const llmComplete = llm && config.llm.enabled ? async (prompt, options) => {
+        const result = await llm.complete(prompt, {
+          ...options,
+          temperature: options?.temperature ?? config.llm.temperature,
+          maxTokens: options?.maxTokens ?? config.llm.maxTokens
+        });
+        return {
+          content: result.content,
+          tokensUsed: result.usage ? result.usage.promptTokens + result.usage.completionTokens : void 0
+        };
+      } : void 0;
+      const plan = await generateCommitPlan({
+        cwd: scopeCwd,
+        llmComplete,
+        config,
+        allowSecrets,
+        autoConfirm,
+        onProgress: (message) => analyzeLoader.update({ text: message })
+      });
+      const saveLoader = useLoader("Saving plan...");
+      saveLoader.start();
+      await savePlan(cwd, plan, effectiveScope);
+      const planPath = getCurrentPlanPath(cwd, effectiveScope);
+      saveLoader.succeed("Plan saved");
+      analyzeLoader.succeed(`Generated commit plan with ${plan.commits.length} commit(s)`);
+      const output = {
+        plan,
+        planPath
+      };
+      if (input.json) {
+        ctx.ui?.json?.(output);
+      } else {
+        const commitsItems = plan.commits.map((commit) => {
+          const scope = commit.scope ? `(${commit.scope})` : "";
+          return `${commit.type}${scope}: ${commit.message} [${commit.files.length} file(s)]`;
+        });
+        const artifacts = [];
+        try {
+          const planStats = await stat(planPath);
+          artifacts.push({
+            name: "Commit Plan",
+            path: planPath,
+            size: planStats.size,
+            modified: planStats.mtime,
+            description: "Generated commit plan in JSON format"
+          });
+        } catch {
+        }
+        const sections = [];
+        if (commitsItems.length > 0) {
+          sections.push({
+            header: "Commits",
+            items: commitsItems
+          });
+        }
+        if (artifacts.length > 0) {
+          const artifactsLines = displayArtifacts(artifacts, {
+            showSize: true,
+            showTime: true,
+            showDescription: true,
+            maxItems: 10,
+            title: ""
+          });
+          sections.push({
+            header: "Artifacts",
+            items: artifactsLines
+          });
+        }
+        const summaryItems = [
+          `Files: ${plan.metadata.totalFiles}`,
+          `Commits: ${plan.metadata.totalCommits}`
+        ];
+        if (plan.metadata.llmUsed) {
+          const llmPhase = plan.metadata.escalated ? "Phase 2 (with diff)" : "Phase 1";
+          summaryItems.push(`LLM: ${llmPhase}`);
+          if (plan.metadata.tokensUsed) {
+            summaryItems.push(`Tokens: ${plan.metadata.tokensUsed}`);
+          }
+        } else {
+          summaryItems.push("Generator: Heuristics");
+        }
+        sections.unshift({
+          header: "Summary",
+          items: summaryItems
+        });
+        const timing = Date.now() - startTime;
+        ctx.ui?.success?.("Plan generated and saved", {
+          title: "Generate Commit Plan",
+          sections,
+          timing
+        });
+      }
+      return {
+        exitCode: 0,
+        result: output,
+        meta: {
+          timing: Date.now() - startTime
+        }
+      };
+    }
+  }
+});
+
+export { generate_default as default };
+//# sourceMappingURL=generate.js.map
+//# sourceMappingURL=generate.js.map