@kosuke-ai/cli 0.0.7 → 0.0.9

package/README.md

@@ -16,25 +16,96 @@ Or use with npx (no installation required):
 npx @kosuke-ai/cli <command>
 ```
 
+### Use as Library in TypeScript Projects
+
+Install as a project dependency:
+
+```bash
+npm install @kosuke-ai/cli
+```
+
+Then import and use programmatically:
+
+```typescript
+import {
+  analyseCommand,
+  lintCommand,
+  syncRulesCommand,
+  requirementsCommand,
+  discoverFiles,
+  createBatches,
+  runLint,
+  runTypecheck,
+} from '@kosuke-ai/cli';
+
+// Run commands programmatically
+await analyseCommand({
+  scope: 'src/components',
+  pr: false,
+});
+
+await lintCommand({ pr: false });
+
+// Use utilities
+const files = await discoverFiles({
+  types: ['ts', 'tsx'],
+  scope: 'lib',
+});
+
+const batches = createBatches(files, {
+  maxSize: 10,
+  groupBy: 'directory',
+});
+
+const lintResult = await runLint();
+if (!lintResult.success) {
+  console.error('Linting failed:', lintResult.error);
+}
+```
+
+#### Local Development with npm link
+
+To develop against a local version of kosuke-cli:
+
+```bash
+# In kosuke-cli directory
+npm run dev:link    # Builds, links, and watches for changes
+
+# In your project directory
+npm link @kosuke-ai/cli
+```
+
+Now your project will use the local kosuke-cli, and changes will be reflected automatically.
+
 ## Prerequisites
 
-Before using Kosuke CLI, set up the required environment variables:
+Set up the required environment variable:
 
 ```bash
 # Required for Claude API access
 export ANTHROPIC_API_KEY="your-api-key-here"
 
-# Required for creating pull requests
+# Optional: Only required when using --pr flag
 export GITHUB_TOKEN="your-github-token-here"
 ```
 
 You can also create a `.env` file in your project root:
 
-```
+```env
 ANTHROPIC_API_KEY=your-api-key-here
 GITHUB_TOKEN=your-github-token-here
 ```
 
+## Workflow
+
+By default, all commands apply changes **locally** without git operations. This allows you to:
+
+- Review changes before committing
+- Test fixes in your local environment
+- Iterate quickly without creating PRs
+
+Use the `--pr` flag to automatically create a pull request with the changes.
+
 ## Commands
 
 ### `kosuke sync-rules`
@@ -44,28 +115,40 @@ Sync rules and documentation from kosuke-template repository.
 **Options:**
 
 - `--force` - Compare files regardless of recent commit history
+- `--pr` - Create a pull request with the changes
+- `--base-branch=<name>` - Base branch for PR (default: current branch)
 
 **Examples:**
 
 ```bash
+# Sync locally
 kosuke sync-rules
+
+# Force comparison and sync locally
 kosuke sync-rules --force
+
+# Create PR with synced changes
+kosuke sync-rules --pr
+
+# Create PR with custom base branch
+kosuke sync-rules --pr --base-branch=develop
 ```
 
 ### `kosuke analyse`
 
-Analyze and fix code quality issues against CLAUDE.md rules. Creates a single PR with all fixes from multiple isolated Claude runs.
+Analyze and fix code quality issues against CLAUDE.md rules. Applies fixes locally by default.
 
 **Options:**
 
-- `--dry-run` - Report violations only, don't create PR
+- `--pr` - Create a pull request with fixes
+- `--base-branch=<name>` - Base branch for PR (default: current branch)
 - `--scope=<dirs>` - Analyze specific directories (comma-separated)
 - `--types=<exts>` - Analyze specific file types (comma-separated)
 
 **Examples:**
 
 ```bash
-# Analyze entire project
+# Analyze and fix locally
 kosuke analyse
 
 # Analyze specific directories
@@ -74,35 +157,38 @@ kosuke analyse --scope=hooks,lib/trpc
 # Analyze specific file types
 kosuke analyse --types=ts,tsx
 
-# Dry run (report only)
-kosuke analyse --dry-run
+# Create PR with fixes
+kosuke analyse --pr
+
+# Create PR with custom base branch
+kosuke analyse --pr --base-branch=main
 ```
 
 ### `kosuke lint`
 
-Use Claude AI to automatically fix linting errors in your codebase. Runs the lint command from package.json, analyzes the errors, and applies fixes.
+Use Claude AI to automatically fix linting errors. Applies fixes locally by default.
 
 **Options:**
 
-- `--dry-run` - Report errors only, don't fix them
-- `--no-pr` - Fix locally without creating PR
+- `--pr` - Create a pull request with fixes
+- `--base-branch=<name>` - Base branch for PR (default: current branch)
 
 **Examples:**
 
 ```bash
-# Fix all linting errors and create PR
+# Fix linting errors locally
 kosuke lint
 
-# Preview what errors would be fixed
-kosuke lint --dry-run
+# Create PR with fixes
+kosuke lint --pr
 
-# Fix errors locally without creating PR
-kosuke lint --no-pr
+# Create PR with custom base branch
+kosuke lint --pr --base-branch=main
 ```
 
 **Requirements:**
 
-- Your `package.json` must have a `lint` script (e.g., `"lint": "eslint . --fix"`)
+- Your `package.json` must have a `lint` script (e.g., `"lint": "eslint ."`)
 - The lint script should support the `--fix` flag for auto-fixing
 
 ### `kosuke requirements`
@@ -146,7 +232,7 @@ Create a `.kosukeignore` file in your project root to exclude files and director
 
 Example:
 
-```
+```gitignore
 # Ignore build outputs
 dist/
 build/

package/dist/index.js

@@ -26,20 +26,25 @@ import { requirementsCommand } from './kosuke/commands/requirements.js';
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
-    if (!command) {
+    if (!command || command === '--help' || command === '-h' || command === 'help') {
         showHelp();
-        process.exit(1);
+        process.exit(0);
     }
     try {
         switch (command) {
             case 'sync-rules': {
-                const hasForceFlag = args.includes('--force');
-                await syncRulesCommand(hasForceFlag);
+                const options = {
+                    force: args.includes('--force'),
+                    pr: args.includes('--pr'),
+                    baseBranch: args.find((arg) => arg.startsWith('--base-branch='))?.split('=')[1],
+                };
+                await syncRulesCommand(options);
                 break;
             }
             case 'analyse': {
                 const options = {
-                    dryRun: args.includes('--dry-run'),
+                    pr: args.includes('--pr'),
+                    baseBranch: args.find((arg) => arg.startsWith('--base-branch='))?.split('=')[1],
                     scope: args.find((arg) => arg.startsWith('--scope='))?.split('=')[1],
                     types: args
                         .find((arg) => arg.startsWith('--types='))
@@ -51,8 +56,8 @@ async function main() {
             }
             case 'lint': {
                 const options = {
-                    dryRun: args.includes('--dry-run'),
-                    noPr: args.includes('--no-pr'),
+                    pr: args.includes('--pr'),
+                    baseBranch: args.find((arg) => arg.startsWith('--base-branch='))?.split('=')[1],
                 };
                 await lintCommand(options);
                 break;
@@ -80,43 +85,49 @@ function showHelp() {
 
 COMMANDS:
 
-  sync-rules [--force]
+  sync-rules [options]
     Sync rules and documentation from kosuke-template
     
     Options:
-      --force    Compare files regardless of recent commit history
+      --force               Compare files regardless of recent commit history
+      --pr                  Create a pull request with changes
+      --base-branch=<name>  Base branch for PR (default: current branch)
     
     Examples:
-      kosuke sync-rules
-      kosuke sync-rules --force
+      kosuke sync-rules                    # Local changes only
+      kosuke sync-rules --force            # Force comparison
+      kosuke sync-rules --pr               # Create PR
+      kosuke sync-rules --pr --base-branch=develop
 
-  analyse
+  analyse [options]
     Analyze and fix code quality issues against CLAUDE.md rules
-    Creates a single PR with all fixes from multiple isolated Claude runs
+    Applies fixes locally by default
     
     Options:
-      --dry-run       Report violations only, don't create PR
-      --scope=<dirs>  Analyze specific directories (comma-separated)
-      --types=<exts>  Analyze specific file types (comma-separated)
+      --pr                  Create a pull request with fixes
+      --base-branch=<name>  Base branch for PR (default: current branch)
+      --scope=<dirs>        Analyze specific directories (comma-separated)
+      --types=<exts>        Analyze specific file types (comma-separated)
     
     Examples:
-      kosuke analyse
+      kosuke analyse                       # Local fixes only
+      kosuke analyse --pr                  # Create PR with fixes
       kosuke analyse --scope=hooks,lib/trpc
       kosuke analyse --types=ts,tsx
-      kosuke analyse --dry-run
+      kosuke analyse --pr --base-branch=main
 
-  lint
+  lint [options]
     Use Claude AI to automatically fix linting errors
-    Creates a PR with all lint fixes
+    Applies fixes locally by default
     
     Options:
-      --dry-run   Report errors only, don't fix them
-      --no-pr     Fix locally without creating PR
+      --pr                  Create a pull request with fixes
+      --base-branch=<name>  Base branch for PR (default: current branch)
     
     Examples:
-      kosuke lint
-      kosuke lint --dry-run
-      kosuke lint --no-pr
+      kosuke lint                          # Local fixes only
+      kosuke lint --pr                     # Create PR with fixes
+      kosuke lint --pr --base-branch=main
 
   requirements
     Interactive requirements gathering with Claude AI
@@ -125,10 +136,15 @@ COMMANDS:
     Examples:
       kosuke requirements
 
+WORKFLOW:
+
+  By default, all commands apply changes locally without git operations.
+  Use the --pr flag to create a pull request with the changes.
+
 ENVIRONMENT VARIABLES:
 
   ANTHROPIC_API_KEY   Required for Claude API access
-  GITHUB_TOKEN        Required for creating pull requests
+  GITHUB_TOKEN        Required when using --pr flag
 
 CONFIGURATION:
 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAExE,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,QAAQ,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC;QACH,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,YAAY,CAAC,CAAC,CAAC;gBAClB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBAC9C,MAAM,gBAAgB,CAAC,YAAY,CAAC,CAAC;gBACrC,MAAM;YACR,CAAC;YAED,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,MAAM,OAAO,GAAG;oBACd,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;oBAClC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACpE,KAAK,EAAE,IAAI;yBACR,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;wBAC1C,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;wBACf,EAAE,KAAK,CAAC,GAAG,CAAC;iBACf,CAAC;gBACF,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;gBAC9B,MAAM;YACR,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,OAAO,GAAG;oBACd,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;oBAClC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;iBAC/B,CAAC;gBACF,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;gBAC3B,MAAM;YACR,CAAC;YAED,KAAK,cAAc,CAAC,CAAC,CAAC;gBACpB,MAAM,mBAAmB,EAAE,CAAC;gBAC5B,MAAM;YACR,CAAC;YAED;gBACE,OAAO,CAAC,KAAK,CAAC,sBAAsB,OAAO,IAAI,CAAC,CAAC;gBACjD,QAAQ,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;QACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,SAAS,QAAQ;IACf,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6Db,CAAC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/dist/kosuke/commands/analyse.d.ts

@@ -5,7 +5,7 @@
  * - Each batch of 10-12 files gets its own Claude run
  * - Claude only sees those specific files (no repository-wide context)
  * - Validate after each batch, commit locally
- * - Push all commits at once and create single PR
+ * - If --pr flag: Push all commits and create single PR
  */
 import type { AnalyseOptions } from '../types.js';
 /**

package/dist/kosuke/commands/analyse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyse.d.ts","sourceRoot":"","sources":["../../../kosuke/commands/analyse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAkR9D;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6JhF"}
+{"version":3,"file":"analyse.d.ts","sourceRoot":"","sources":["../../../kosuke/commands/analyse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AA4R9D;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFhF"}