@versu/cli 0.4.0

package/README.md

@@ -0,0 +1,386 @@
+# @versu/cli - Command-Line Interface
+
+Command-line interface for VERSU (Version Engine for Repo Semantic Evolution). This CLI provides all the power of VERSU's semantic versioning engine through an easy-to-use command-line tool, perfect for local development and custom CI/CD systems.
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g @versu/cli
+```
+
+### Local Installation
+
+```bash
+npm install --save-dev @versu/cli
+```
+
+### Using npx (no installation)
+
+```bash
+px @versu/cli
+```
+
+## Usage
+
+### Basic Usage
+
+Navigate to your project root and run:
+
+```bash
+versu
+```
+
+This will:
+
+1. Detect your project type (Gradle, etc.)
+2. Analyze commits since the last version
+3. Calculate version bumps based on Conventional Commits
+4. Update version files
+5. Generate changelogs
+6. Create git commits and tags
+7. Push changes to remote
+
+### Dry Run
+
+Preview what would happen without making changes:
+
+```bash
+versu --dry-run
+```
+
+### Specify Project Root
+
+```bash
+versu /path/to/project
+```
+
+### Specify Adapter
+
+If auto-detection fails or you want to be explicit:
+
+```bash
+versu --adapter gradle
+```
+
+## Command Reference
+
+### `versu [REPOSITORYROOT]`
+
+Calculate and apply semantic version changes.
+
+**Arguments:**
+
+- `REPOSITORYROOT` - Path to the repository root (default: `.`)
+
+**Flags:**
+
+| Flag | Description | Default |
+| ------ | ------------- | --------- |
+| `--dry-run` | Run without writing or pushing changes | `false` |
+| `--adapter <value>` | Language adapter (e.g., gradle). Auto-detected if not provided | - |
+| `--push-tags` | Push tags to origin | `true` |
+| `--no-push-tags` | Don't push tags to origin | - |
+| `--prerelease-mode` | Generate pre-release versions instead of final versions | `false` |
+| `--prerelease-id <value>` | Pre-release identifier (e.g., alpha, beta, rc) | `alpha` |
+| `--bump-unchanged` | In prerelease mode, bump modules even when no changes are detected | `false` |
+| `--add-build-metadata` | Add build metadata with short SHA to all versions | `false` |
+| `--timestamp-versions` | Use timestamp-based prerelease identifiers (requires prerelease-mode) | `false` |
+| `--append-snapshot` | Add -SNAPSHOT suffix to all versions if supported by adapter | `false` |
+| `--push-changes` | Commit and push version changes and changelogs to remote | `true` |
+| `--no-push-changes` | Don't commit and push changes | - |
+| `--generate-changelog` | Generate or update changelog files for changed modules | `true` |
+| `--no-generate-changelog` | Don't generate changelogs | - |
+| `--output-file <value>` | Write calculated versions to a file in JSON format | - |
+
+> 📖 **Detailed Pre-release Documentation**: See [@versu/core PRERELEASE.md](../core/PRERELEASE.md) for comprehensive examples and use cases.
+
+## Examples
+
+### Release Version
+
+Apply semantic versions based on commits:
+
+```bash
+versu
+```
+
+### Pre-release Versions
+
+Generate beta pre-release versions:
+
+```bash
+versu --prerelease-mode --prerelease-id beta
+```
+
+### Timestamp Versions
+
+Generate timestamp-based pre-release versions for CI builds:
+
+```bash
+versu --prerelease-mode --prerelease-id alpha --timestamp-versions --add-build-metadata
+```
+
+This generates versions like: `1.2.3-alpha.20251208.1530+abc1234`
+
+### Gradle SNAPSHOT Versions
+
+Generate Gradle SNAPSHOT versions:
+
+```bash
+versu --append-snapshot
+```
+
+### Development Workflow
+
+Bump all modules (even unchanged) for development:
+
+```bash
+versu --prerelease-mode --bump-unchanged
+```
+
+### Local Testing
+
+Test without committing or pushing:
+
+```bash
+versu --dry-run --no-push-changes --no-push-tags
+```
+
+### Manual Git Operations
+
+Calculate versions without automatic git operations:
+
+```bash
+versu --no-push-changes --no-push-tags
+```
+
+Then manually review, commit, and push.
+
+## Configuration
+
+VERSU CLI uses the same configuration system as the core library. Configuration files are automatically detected in your repository root.
+
+### Supported Configuration Files
+
+1. `package.json` (in a `"versu"` property)
+2. `.versurc` (JSON or YAML)
+3. `.versurc.json`
+4. `.versurc.yaml` / `.versurc.yml`
+5. `.versurc.js` (JavaScript)
+6. `versu.config.js` (JavaScript)
+
+### Configuration Example
+
+`.versurc.json`:
+
+```json
+{
+  "defaultBump": "patch",
+  "commitTypes": {
+    "feat": "minor",
+    "fix": "patch",
+    "perf": "patch",
+    "refactor": "patch",
+    "docs": "ignore",
+    "test": "ignore",
+    "chore": "ignore"
+  },
+  "dependencyRules": {
+    "onMajorOfDependency": "minor",
+    "onMinorOfDependency": "patch",
+    "onPatchOfDependency": "none"
+  }
+}
+```
+
+For more configuration examples, see the [core package documentation](../core).
+
+## Gradle Project Support
+
+The CLI supports Gradle projects with:
+
+- **Multi-module projects** via `settings.gradle(.kts)`
+- **Version management** through root `gradle.properties` file
+- **Dependency detection** via custom Gradle init script
+- **Both DSLs**: Groovy and Kotlin
+
+### Example Project Structure
+
+```text
+myproject/
+├── settings.gradle.kts
+├── build.gradle.kts
+├── gradle.properties      # All module versions defined here
+├── core/
+│   └── build.gradle.kts
+└── api/
+    └── build.gradle.kts
+```
+
+### Example `gradle.properties`
+
+```properties
+# Root module version
+version=1.0.0
+
+# Submodule versions
+core.version=2.1.0
+api.version=1.5.0
+```
+
+## Commit Message Format
+
+VERSU uses [Conventional Commits](https://conventionalcommits.org/) to determine version bumps:
+
+```text
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Examples:**
+
+- `feat(api): add new endpoint` → **minor** bump
+- `fix(core): resolve memory leak` → **patch** bump  
+- `feat!: breaking API change` → **major** bump
+
+### Breaking Changes
+
+Breaking changes trigger **major** version bumps:
+
+1. Using `!` after the type: `feat!: remove deprecated API`
+2. Using `BREAKING CHANGE:` in the footer:
+
+   ```text
+   feat: update API
+   
+   BREAKING CHANGE: The old API is removed
+   ```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Install VERSU CLI
+  run: npm install -g @versu/cli
+
+- name: Version modules
+  run: versu --adapter gradle
+```
+
+### GitLab CI
+
+```yaml
+version:
+  script:
+    - npm install -g @versu/cli
+    - versu --adapter gradle
+```
+
+### Jenkins
+
+```groovy
+stage('Version') {
+  steps {
+    sh 'npm install -g @versu/cli'
+    sh 'versu --adapter gradle'
+  }
+}
+```
+
+### Local Development
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "version": "versu --dry-run",
+    "version:release": "versu"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run version        # Dry run
+npm run version:release # Actual release
+```
+
+## Troubleshooting
+
+### Command Not Found
+
+If `versu` is not found after global installation:
+
+1. Check npm global bin path: `npm bin -g`
+2. Ensure it's in your PATH
+3. Try using npx: `npx @versu/cli`
+
+### Permission Denied on Push
+
+If you get permission errors when pushing:
+
+1. Ensure you have proper git credentials configured
+2. Check if you have write access to the repository
+3. Use `--no-push-changes --no-push-tags` to skip git operations
+
+### No Version Bump Detected
+
+If versions aren't bumping:
+
+1. Check commit messages follow Conventional Commits format
+2. Verify you have commits since the last version
+3. Check configuration if certain commit types are ignored
+4. Use `--dry-run` to see what VERSU detects
+
+### Adapter Not Detected
+
+If auto-detection fails:
+
+1. Verify your project has the expected build files
+2. Explicitly specify the adapter: `--adapter gradle`
+3. Check if your project structure is supported
+
+## Development
+
+### Building from Source
+
+```bash
+# From monorepo root
+npm install
+npm run build
+
+# Or from CLI package
+cd packages/cli
+npm install
+npm run build
+```
+
+### Running Locally
+
+```bash
+# After building
+node dist/index.js --dry-run
+```
+
+### Publishing
+
+```bash
+npm publish --workspace packages/cli --access public
+```
+
+## Related Packages
+
+- **[@versu/core](../core)** - Core library for custom integrations
+- **[@versu/action](../action)** - GitHub Actions integration
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details.

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { Command } from "@oclif/core";
+export default class Version extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        repositoryRoot: import("@oclif/core/interfaces").Arg<string, {
+            exists?: boolean;
+        }>;
+    };
+    static flags: {
+        version: import("@oclif/core/interfaces").BooleanFlag<void>;
+        "dry-run": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        adapter: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "push-tags": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "prerelease-mode": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "prerelease-id": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "bump-unchanged": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "add-build-metadata": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "timestamp-versions": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "append-snapshot": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "push-changes": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "generate-changelog": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "output-file": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAS,MAAM,aAAa,CAAC;AAInD,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,OAAO;IAC1C,OAAgB,WAAW,SAAkD;IAE7E,OAAgB,QAAQ,WAKtB;IAEF,MAAM,CAAC,IAAI;;;;MAMT;IAEF,OAAgB,KAAK;;;;;;;;;;;;;;MAyDnB;IAEI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CA8B3B"}

package/dist/index.js

@@ -0,0 +1,100 @@
+import { Args, Command, Flags } from "@oclif/core";
+import { VersuRunner, initLogger } from "@versu/core";
+import { OclifLogger } from "./logger.js";
+export default class Version extends Command {
+    static description = "Calculate and apply semantic version changes";
+    static examples = [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --adapter gradle",
+        "<%= config.bin %> <%= command.id %> --dry-run",
+        "<%= config.bin %> <%= command.id %> --prerelease-mode --prerelease-id alpha",
+    ];
+    static args = {
+        repositoryRoot: Args.directory({
+            required: false,
+            description: "Path to the repository root",
+            default: ".",
+        }),
+    };
+    static flags = {
+        version: Flags.version({ char: 'v' }),
+        "dry-run": Flags.boolean({
+            description: "Run without writing or pushing changes",
+            default: false,
+        }),
+        adapter: Flags.string({
+            description: "Language adapter (e.g., gradle). Auto-detected if not provided",
+            required: false,
+        }),
+        "push-tags": Flags.boolean({
+            description: "Push tags to origin",
+            default: true,
+            allowNo: true,
+        }),
+        "prerelease-mode": Flags.boolean({
+            description: "Generate pre-release versions instead of final versions",
+            default: false,
+        }),
+        "prerelease-id": Flags.string({
+            description: "Pre-release identifier (e.g., alpha, beta, rc)",
+            default: "alpha",
+        }),
+        "bump-unchanged": Flags.boolean({
+            description: "In prerelease mode, bump modules even when no changes are detected",
+            default: false,
+        }),
+        "add-build-metadata": Flags.boolean({
+            description: "Add build metadata with short SHA to all versions",
+            default: false,
+        }),
+        "timestamp-versions": Flags.boolean({
+            description: "Use timestamp-based prerelease identifiers (requires prerelease-mode)",
+            default: false,
+        }),
+        "append-snapshot": Flags.boolean({
+            description: "Add -SNAPSHOT suffix to all versions if supported by adapter",
+            default: false,
+        }),
+        "push-changes": Flags.boolean({
+            description: "Commit and push version changes and changelogs to remote",
+            default: true,
+            allowNo: true,
+        }),
+        "generate-changelog": Flags.boolean({
+            description: "Generate or update changelog files for changed modules",
+            default: true,
+            allowNo: true,
+        }),
+        "output-file": Flags.string({
+            description: "Path to the output file for project information",
+            default: "project-information.json",
+        }),
+    };
+    async run() {
+        const { flags, args } = await this.parse(Version);
+        initLogger(new OclifLogger(this));
+        try {
+            const options = {
+                repoRoot: args.repositoryRoot,
+                adapter: flags.adapter,
+                dryRun: flags["dry-run"],
+                pushTags: flags["push-tags"],
+                prereleaseMode: flags["prerelease-mode"],
+                prereleaseId: flags["prerelease-id"],
+                bumpUnchanged: flags["bump-unchanged"],
+                addBuildMetadata: flags["add-build-metadata"],
+                timestampVersions: flags["timestamp-versions"],
+                appendSnapshot: flags["append-snapshot"],
+                pushChanges: flags["push-changes"],
+                generateChangelog: flags["generate-changelog"],
+                outputFile: flags["output-file"],
+            };
+            const runner = new VersuRunner(options);
+            await runner.run();
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.error(`❌ Command failed: ${errorMessage}`);
+        }
+    }
+}

package/dist/logger.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+import type { Logger } from '@versu/core';
+export declare class OclifLogger implements Logger {
+    private readonly cmd;
+    constructor(cmd: Command);
+    info(message: string): void;
+    warning(message: string | Error): void;
+    error(message: string | Error, context?: Record<string, unknown>): void;
+    debug(message: string): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C,qBAAa,WAAY,YAAW,MAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,OAAO;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAG3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAGtC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAGvE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAG/B"}

package/dist/logger.js

@@ -0,0 +1,20 @@
+import Debug from 'debug';
+const debug = Debug('versu');
+export class OclifLogger {
+    cmd;
+    constructor(cmd) {
+        this.cmd = cmd;
+    }
+    info(message) {
+        this.cmd.log(message);
+    }
+    warning(message) {
+        this.cmd.warn(message);
+    }
+    error(message, context) {
+        this.cmd.error(message, context);
+    }
+    debug(message) {
+        debug(message);
+    }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@versu/cli",
+  "version": "0.4.0",
+  "description": "Version Engine for Repo Semantic Evolution (CLI)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "versu": "./bin/run.js"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json --outDir dist",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts"
+  },
+  "keywords": [
+    "versu",
+    "cli",
+    "semantic-versioning",
+    "conventional-commits",
+    "version-engine",
+    "monorepo"
+  ],
+  "author": "tvcsantos",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tvcsantos/versu.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tvcsantos/versu/issues"
+  },
+  "homepage": "https://github.com/tvcsantos/versu#readme",
+  "files": [
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@oclif/core": "^4.8.0",
+    "@versu/core": "^0.4.0",
+    "oclif": "^4.14.0"
+  },
+  "devDependencies": {
+    "@oclif/dev-cli": "^1.26.10",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^20.19.23",
+    "@typescript-eslint/eslint-plugin": "^6.15.0",
+    "@typescript-eslint/parser": "^6.15.0",
+    "eslint": "^8.56.0",
+    "prettier": "^3.1.1",
+    "ts-node": "^10.9.2",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "oclif": {
+    "bin": "versu",
+    "dirname": "versu",
+    "topicSeparator": " ",
+    "plugins": [],
+    "commands": {
+      "strategy": "single",
+      "target": "./dist/index.js"
+    }
+  }
+}