@makispps/releasejet 1.0.0 → 1.0.2

package/.releasejet.example.yml

@@ -1,28 +1,28 @@
-# ReleaseJet Configuration
-# Copy to .releasejet.yml and customize for your project.
-# Or run: releasejet init
-
-# GitLab instance URL
-gitlab:
-  url: https://gitlab.example.com
-
-# Client definitions (omit for single-client repos)
-# clients:
-#   - prefix: mobile
-#     label: MOBILE
-#   - prefix: web
-#     label: WEB
-
-# Category label mappings
-# Key: the label name in GitLab
-# Value: the section heading in release notes
-categories:
-  feature: "New Features"
-  bug: "Bug Fixes"
-  improvement: "Improvements"
-  breaking-change: "Breaking Changes"
-
-# How to handle uncategorized issues
-# "lenient" — include under "Other" with a warning (default)
-# "strict" — fail release generation
-uncategorized: lenient
+# ReleaseJet Configuration
+# Copy to .releasejet.yml and customize for your project.
+# Or run: releasejet init
+
+# GitLab instance URL
+gitlab:
+  url: https://gitlab.example.com
+
+# Client definitions (omit for single-client repos)
+# clients:
+#   - prefix: mobile
+#     label: MOBILE
+#   - prefix: web
+#     label: WEB
+
+# Category label mappings
+# Key: the label name in GitLab
+# Value: the section heading in release notes
+categories:
+  feature: "New Features"
+  bug: "Bug Fixes"
+  improvement: "Improvements"
+  breaking-change: "Breaking Changes"
+
+# How to handle uncategorized issues
+# "lenient" — include under "Other" with a warning (default)
+# "strict" — fail release generation
+uncategorized: lenient

package/README.md

@@ -1,145 +1,197 @@
-<img width="480" height="120" alt="lockup-light-1x" src="https://github.com/user-attachments/assets/1fd84e91-86f3-4f62-bad7-8bf4b72b517f" />
-
-Automated release notes generator for GitLab and GitHub. Collects closed issues (or merged pull requests) between Git tags, categorizes them by label, and publishes formatted release notes.
-
-## Features
-
-- **GitLab and GitHub support** — works with both providers out of the box
-- **Issues or Pull Requests** — generate notes from closed issues (default) or merged PRs (GitHub)
-- **Multi-client repos** — filter by client label (e.g., `mobile-v1.0.0`, `web-v2.0.0`)
-- **Single-client repos** — just use `v<semver>` tags
-- **Configurable categories** — map labels to sections (features, bugs, improvements, etc.)
-- **CI/CD integration** — runs automatically on tag push via GitLab CI or GitHub Actions
-- **Strict/lenient modes** — enforce labeling or allow uncategorized issues under "Other"
-- **Milestone detection** — automatically links the most common milestone in release notes
-
-## Quick Start
-
-```bash
-npm install -g releasejet
-
-# Interactive setup (detects provider from git remote)
-releasejet init
-
-# Preview release notes
-releasejet generate --tag v1.0.0
-
-# Generate and publish
-releasejet generate --tag v1.0.0 --publish
-```
-
-## Configuration
-
-Create `.releasejet.yml` in your project root (or run `releasejet init`):
-
-```yaml
-provider:
-  type: github       # 'gitlab' or 'github'
-  url: https://github.com
-
-# GitHub-only: generate notes from issues or pull requests
-source: issues       # 'issues' (default) or 'pull_requests'
-
-# For multi-client repos (omit for single-client)
-clients:
-  - prefix: mobile
-    label: MOBILE
-  - prefix: web
-    label: WEB
-
-categories:
-  feature: "New Features"
-  bug: "Bug Fixes"
-  improvement: "Improvements"
-  breaking-change: "Breaking Changes"
-
-uncategorized: lenient  # or "strict" to enforce labeling
-```
-
-## CI/CD Integration
-
-### GitHub Actions
-
-Run `releasejet init` and select CI setup, or add `.github/workflows/release-notes.yml`:
-
-```yaml
-name: Release Notes
-on:
-  push:
-    tags:
-      - '**'
-jobs:
-  release-notes:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - run: npm install -g releasejet
-      - run: releasejet generate --tag "${{ github.ref_name }}" --publish
-        env:
-          RELEASEJET_TOKEN: ${{ secrets.RELEASEJET_TOKEN }}
-```
-
-Set `RELEASEJET_TOKEN` as a repository secret (Settings > Secrets > Actions).
-
-### GitLab CI
-
-Add to your `.gitlab-ci.yml` (or run `releasejet ci enable`):
-
-```yaml
-release-notes:
-  stage: deploy
-  image: node:20-alpine
-  rules:
-    - if: $CI_COMMIT_TAG
-  before_script:
-    - npm install -g releasejet
-  script:
-    - releasejet generate --tag "$CI_COMMIT_TAG" --publish
-```
-
-Set `GITLAB_API_TOKEN` (or `RELEASEJET_TOKEN`) as a CI/CD variable with `api` scope.
-
-## Authentication
-
-Token resolution order:
-
-1. `RELEASEJET_TOKEN` env var (works for both providers)
-2. Provider-specific env var: `GITLAB_API_TOKEN` or `GITHUB_TOKEN`
-3. Stored credentials from `~/.releasejet/credentials.yml`
-
-## Tag Format
-
-| Repo type | Format | Example |
-|-----------|--------|---------|
-| Multi-client | `<prefix>-v<semver>` | `mobile-v1.2.0` |
-| Single-client | `v<semver>` | `v1.2.0` |
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `releasejet init` | Interactive setup wizard |
-| `releasejet generate --tag <tag>` | Generate release notes |
-| `releasejet generate --tag <tag> --publish` | Generate and publish release |
-| `releasejet validate` | Check issues for proper labeling |
-| `releasejet ci enable` | Add CI configuration to `.gitlab-ci.yml` |
-| `releasejet ci disable` | Remove CI configuration |
-
-### Generate Flags
-
-| Flag | Description |
-|------|-------------|
-| `--publish` | Publish as a release on the provider |
-| `--dry-run` | Preview without publishing |
-| `--format <format>` | Output format: `markdown` (default) or `json` |
-| `--config <path>` | Custom config file path |
-| `--debug` | Show debug information |
-
-## License
-
-MIT
+<img width="480" height="120" alt="lockup-light-1x" src="https://github.com/user-attachments/assets/1fd84e91-86f3-4f62-bad7-8bf4b72b517f" />
+
+Automated release notes generator for GitLab and GitHub. Collects closed issues (or merged pull requests) between Git tags, categorizes them by label, and publishes formatted release notes.
+
+## Features
+
+- **GitLab and GitHub support** — works with both providers out of the box
+- **Issues or Pull Requests** — generate notes from closed issues (default) or merged PRs (GitHub)
+- **Multi-client repos** — filter by client label (e.g., `mobile-v1.0.0`, `web-v2.0.0`)
+- **Single-client repos** — just use `v<semver>` tags
+- **Configurable categories** — map labels to sections (features, bugs, improvements, etc.)
+- **CI/CD integration** — runs automatically on tag push via GitLab CI or GitHub Actions
+- **Strict/lenient modes** — enforce labeling or allow uncategorized issues under "Other"
+- **Milestone detection** — automatically links the most common milestone in release notes
+
+## Quick Start
+
+```bash
+npm install -g releasejet
+
+# Interactive setup (detects provider from git remote)
+releasejet init
+
+# Preview release notes
+releasejet generate --tag v1.0.0
+
+# Generate and publish
+releasejet generate --tag v1.0.0 --publish
+```
+
+## Configuration
+
+Create `.releasejet.yml` in your project root (or run `releasejet init`):
+
+```yaml
+provider:
+  type: github       # 'gitlab' or 'github'
+  url: https://github.com
+
+# GitHub-only: generate notes from issues or pull requests
+source: issues       # 'issues' (default) or 'pull_requests'
+
+# For multi-client repos (omit for single-client)
+clients:
+  - prefix: mobile
+    label: MOBILE
+  - prefix: web
+    label: WEB
+
+categories:
+  feature: "New Features"
+  bug: "Bug Fixes"
+  improvement: "Improvements"
+  breaking-change: "Breaking Changes"
+
+uncategorized: lenient  # or "strict" to enforce labeling
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+Run `releasejet init` and select CI setup, or add `.github/workflows/release-notes.yml`:
+
+```yaml
+name: Release Notes
+on:
+  push:
+    tags:
+      - '**'
+jobs:
+  release-notes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g releasejet
+      - run: releasejet generate --tag "${{ github.ref_name }}" --publish
+        env:
+          RELEASEJET_TOKEN: ${{ secrets.RELEASEJET_TOKEN }}
+```
+
+Set `RELEASEJET_TOKEN` as a repository secret (Settings > Secrets > Actions).
+
+### GitLab CI
+
+Add to your `.gitlab-ci.yml` (or run `releasejet ci enable`):
+
+```yaml
+release-notes:
+  stage: deploy
+  image: node:20-alpine
+  rules:
+    - if: $CI_COMMIT_TAG
+  before_script:
+    - npm install -g releasejet
+  script:
+    - releasejet generate --tag "$CI_COMMIT_TAG" --publish
+```
+
+Set `GITLAB_API_TOKEN` (or `RELEASEJET_TOKEN`) as a CI/CD variable with `api` scope.
+
+## Authentication
+
+Token resolution order:
+
+1. `RELEASEJET_TOKEN` env var (works for both providers)
+2. Provider-specific env var: `GITLAB_API_TOKEN` or `GITHUB_TOKEN`
+3. Stored credentials from `~/.releasejet/credentials.yml`
+
+## Tag Format
+
+| Repo type | Format | Example |
+|-----------|--------|---------|
+| Multi-client | `<prefix>-v<semver>` | `mobile-v1.2.0` |
+| Single-client | `v<semver>` | `v1.2.0` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `releasejet init` | Interactive setup wizard |
+| `releasejet generate --tag <tag>` | Generate release notes |
+| `releasejet generate --tag <tag> --publish` | Generate and publish release |
+| `releasejet validate` | Check issues for proper labeling |
+| `releasejet ci enable` | Add CI configuration to `.gitlab-ci.yml` |
+| `releasejet ci disable` | Remove CI configuration |
+
+### Generate Flags
+
+| Flag | Description |
+|------|-------------|
+| `--publish` | Publish as a release on the provider |
+| `--dry-run` | Preview without publishing |
+| `--format <format>` | Output format: `markdown` (default) or `json` |
+| `--config <path>` | Custom config file path |
+| `--debug` | Show debug information |
+
+## Troubleshooting
+
+### "API token not found"
+
+ReleaseJet checks three sources in order: `RELEASEJET_TOKEN` env var, provider-specific env var (`GITLAB_API_TOKEN` or `GITHUB_TOKEN`), and `~/.releasejet/credentials.yml`. Verify your token is set:
+
+```bash
+echo $RELEASEJET_TOKEN
+```
+
+To reconfigure, run `releasejet init`.
+
+### "Tag not found in remote repository"
+
+The tag exists locally but hasn't been pushed. Push it first:
+
+```bash
+git push origin <tag>
+```
+
+### "Invalid tag format"
+
+Tags must match `v<semver>` (e.g., `v1.2.0`) or `<prefix>-v<semver>` (e.g., `mobile-v1.2.0`). Suffixes like `v1.2.0-beta` are supported but the core version must be valid semver.
+
+### Issues missing from release notes
+
+ReleaseJet includes issues closed *between* the previous tag and the current tag (by `closedAt` timestamp, not `updatedAt`). Check that:
+
+- The issue is **closed** (not just merged)
+- The close date falls within the tag window
+- The issue has the correct **client label** (multi-client repos)
+
+Use `--debug` to see the date range and which issues were filtered.
+
+### "Request failed with status 401" or "403"
+
+The API token doesn't have the required permissions. GitLab tokens need `api` scope. GitHub tokens need `repo` scope. Regenerate the token with the correct scope and update it via `releasejet init` or the `RELEASEJET_TOKEN` env var.
+
+### `source: pull_requests` not working
+
+Pull request source is only supported for GitHub. GitLab projects must use `source: issues` (the default).
+
+### Config changes not taking effect
+
+Run with `--debug` to see the loaded config:
+
+```bash
+releasejet generate --tag <tag> --debug
+```
+
+Invalid values (e.g., `uncategorized: "strictt"`) now produce clear error messages instead of being silently ignored.
+
+## License
+
+MIT

package/ci/release-notes-github.yml

@@ -1,19 +1,19 @@
-name: Release Notes
-on:
-  push:
-    tags:
-      - '**'
-jobs:
-  release-notes:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - run: npm install -g releasejet
-      - run: releasejet generate --tag "${{ github.ref_name }}" --publish
-        env:
-          RELEASEJET_TOKEN: ${{ secrets.RELEASEJET_TOKEN }}
+name: Release Notes
+on:
+  push:
+    tags:
+      - '**'
+jobs:
+  release-notes:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g releasejet
+      - run: releasejet generate --tag "${{ github.ref_name }}" --publish
+        env:
+          RELEASEJET_TOKEN: ${{ secrets.RELEASEJET_TOKEN }}

package/ci/release-notes-gitlab.yml

@@ -1,22 +1,22 @@
-# ReleaseJet — Shared GitLab CI Template
-#
-# Include in your project's .gitlab-ci.yml:
-#
-#   include:
-#     - project: 'tools/releasejet'
-#       file: '/ci/release-notes.yml'
-#
-#   variables:
-#     RELEASEJET_TOKEN: $GITLAB_API_TOKEN
-
-release-notes:
-  stage: deploy
-  image: node:20-alpine
-  rules:
-    - if: $CI_COMMIT_TAG
-  variables:
-    RELEASEJET_TOKEN: ${RELEASEJET_TOKEN}
-  before_script:
-    - npm install -g releasejet
-  script:
-    - releasejet generate --tag "$CI_COMMIT_TAG" --publish
+# ReleaseJet — Shared GitLab CI Template
+#
+# Include in your project's .gitlab-ci.yml:
+#
+#   include:
+#     - project: 'tools/releasejet'
+#       file: '/ci/release-notes.yml'
+#
+#   variables:
+#     RELEASEJET_TOKEN: $GITLAB_API_TOKEN
+
+release-notes:
+  stage: deploy
+  image: node:20-alpine
+  rules:
+    - if: $CI_COMMIT_TAG
+  variables:
+    RELEASEJET_TOKEN: ${RELEASEJET_TOKEN}
+  before_script:
+    - npm install -g releasejet
+  script:
+    - releasejet generate --tag "$CI_COMMIT_TAG" --publish

package/dist/cli.js

@@ -37,17 +37,33 @@ async function loadConfig(configPath = ".releasejet.yml") {
   return mergeWithDefaults(raw);
 }
 function mergeWithDefaults(raw) {
-  const clients = raw.clients;
-  const categories = raw.categories;
-  const uncategorized = raw.uncategorized;
-  const source = raw.source;
   const providerRaw = raw.provider;
   const gitlabRaw = raw.gitlab;
+  const source = raw.source;
+  const uncategorized = raw.uncategorized;
+  const clientsRaw = raw.clients;
+  const categoriesRaw = raw.categories;
   let provider;
   if (providerRaw) {
+    const pType = providerRaw.type;
+    if (pType !== void 0 && pType !== "gitlab" && pType !== "github") {
+      throw new Error(
+        `Invalid config in .releasejet.yml
+
+  provider.type: "${pType}" is not valid. Expected "gitlab" or "github".`
+      );
+    }
+    const pUrl = providerRaw.url ?? "";
+    if (pUrl && !pUrl.startsWith("http://") && !pUrl.startsWith("https://")) {
+      throw new Error(
+        `Invalid config in .releasejet.yml
+
+  provider.url: "${pUrl}" is not valid. Must start with http:// or https://.`
+      );
+    }
     provider = {
-      type: providerRaw.type === "github" ? "github" : "gitlab",
-      url: providerRaw.url ?? ""
+      type: pType ?? "gitlab",
+      url: pUrl
     };
   } else if (gitlabRaw) {
     provider = {
@@ -57,12 +73,51 @@ function mergeWithDefaults(raw) {
   } else {
     provider = { type: "gitlab", url: "" };
   }
+  if (source !== void 0 && source !== "issues" && source !== "pull_requests") {
+    throw new Error(
+      `Invalid config in .releasejet.yml
+
+  source: "${source}" is not valid. Expected "issues" or "pull_requests".`
+    );
+  }
+  if (uncategorized !== void 0 && uncategorized !== "lenient" && uncategorized !== "strict") {
+    throw new Error(
+      `Invalid config in .releasejet.yml
+
+  uncategorized: "${uncategorized}" is not valid. Expected "lenient" or "strict".`
+    );
+  }
+  const clients = [];
+  if (Array.isArray(clientsRaw)) {
+    for (let i = 0; i < clientsRaw.length; i++) {
+      const entry = clientsRaw[i];
+      if (!entry?.prefix || !entry?.label) {
+        throw new Error(
+          `Invalid config in .releasejet.yml
+
+  clients[${i}]: "prefix" and "label" are required.`
+        );
+      }
+      clients.push({ prefix: entry.prefix, label: entry.label });
+    }
+  }
+  let categories;
+  if (categoriesRaw !== void 0) {
+    if (typeof categoriesRaw !== "object" || categoriesRaw === null || Array.isArray(categoriesRaw)) {
+      throw new Error(
+        "Invalid config in .releasejet.yml\n\n  categories: expected an object mapping labels to headings."
+      );
+    }
+    categories = categoriesRaw;
+  } else {
+    categories = { ...DEFAULT_CATEGORIES };
+  }
   return {
     provider,
-    source: source === "pull_requests" ? "pull_requests" : "issues",
-    clients: Array.isArray(clients) ? clients : [],
-    categories: categories ?? { ...DEFAULT_CATEGORIES },
-    uncategorized: uncategorized === "strict" ? "strict" : "lenient"
+    source: source ?? "issues",
+    clients,
+    categories,
+    uncategorized: uncategorized ?? "lenient"
   };
 }
 
@@ -465,15 +520,55 @@ async function promptForUncategorized(issues, config) {
   }
 }
 
+// src/cli/error-handler.ts
+function withErrorHandler(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const isDebug = process.argv.includes("--debug");
+      console.error(`
+Error: ${message}`);
+      if (isDebug && err instanceof Error && err.stack) {
+        console.error(`
+${err.stack}`);
+      } else if (!isDebug) {
+        console.error("\n  Re-run with --debug for more details.");
+      }
+      process.exitCode = 1;
+    }
+  };
+}
+
+// src/cli/logger.ts
+function createLogger(enabled) {
+  return {
+    debug: enabled ? (...args) => console.error("[DEBUG]", ...args) : (() => {
+    })
+  };
+}
+
 // src/cli/commands/generate.ts
+import ora from "ora";
 function registerGenerateCommand(program2) {
-  program2.command("generate").description("Generate release notes for a tag").requiredOption("--tag <tag>", "Git tag to generate release notes for").option("--publish", "Publish release", false).option("--dry-run", "Preview without publishing", false).option("--format <format>", "Output format (markdown|json)", "markdown").option("--config <path>", "Config file path", ".releasejet.yml").option("--debug", "Show debug information", false).action(async (options) => {
+  program2.command("generate").description("Generate release notes for a tag").requiredOption("--tag <tag>", "Git tag (e.g., v1.0.0 or mobile-v1.2.0)").option("--publish", "Publish release to provider", false).option("--dry-run", "Preview without publishing", false).option("--format <format>", "Output format (markdown|json)", "markdown").option("--config <path>", "Config file path", ".releasejet.yml").option("--debug", "Show debug information", false).addHelpText("after", `
+Examples:
+  $ releasejet generate --tag v1.0.0                Preview release notes
+  $ releasejet generate --tag mobile-v2.1.0         Multi-client tag
+  $ releasejet generate --tag v1.0.0 --publish      Publish to provider
+  $ releasejet generate --tag v1.0.0 --format json  JSON output
+
+Tag format:
+  Multi-client:  <prefix>-v<semver>  (e.g., mobile-v1.2.0)
+  Single-client: v<semver>           (e.g., v1.2.0)
+`).action(withErrorHandler(async (options) => {
     await runGenerate(options);
-  });
+  }));
 }
 async function runGenerate(options) {
-  const debug = options.debug ? (...args) => console.error("[DEBUG]", ...args) : () => {
-  };
+  const { debug } = createLogger(options.debug ?? false);
+  const spinner = options.debug ? null : ora({ stream: process.stderr });
   const config = await loadConfig(options.config);
   debug("Config loaded:", JSON.stringify(config, null, 2));
   const remoteUrl = process.env.CI_SERVER_URL || process.env.GITHUB_SERVER_URL ? "" : getRemoteUrl();
@@ -485,7 +580,15 @@ async function runGenerate(options) {
   const client = createClient(config, token);
   const currentParsed = parseTag(options.tag);
   debug("Parsed tag:", JSON.stringify(currentParsed));
-  const apiTags = await client.listTags(projectPath);
+  let apiTags;
+  try {
+    spinner?.start("Fetching tags...");
+    apiTags = await client.listTags(projectPath);
+    spinner?.succeed(`Fetched ${apiTags.length} tags`);
+  } catch (err) {
+    spinner?.fail("Failed to fetch tags");
+    throw err;
+  }
   debug("All remote tags:", apiTags.map((t) => `${t.name} (${t.createdAt})`).join(", "));
   const allTags = apiTags.map((t) => {
     try {
@@ -505,14 +608,24 @@ async function runGenerate(options) {
   const previousTag = findPreviousTag(allTags, currentTag);
   debug("Previous tag:", previousTag ? JSON.stringify(previousTag) : "none (first release)");
   debug("Date range:", previousTag?.createdAt ?? "beginning", "->", currentTag.createdAt);
-  const issues = await collectIssues(
-    client,
-    projectPath,
-    currentTag,
-    previousTag,
-    config,
-    debug
-  );
+  const sourceLabel = config.source === "pull_requests" ? "pull requests" : "issues";
+  let issues;
+  try {
+    spinner?.start(`Collecting ${sourceLabel}...`);
+    issues = await collectIssues(
+      client,
+      projectPath,
+      currentTag,
+      previousTag,
+      config,
+      debug
+    );
+    const issueCount = Object.values(issues.categorized).reduce((sum, arr) => sum + arr.length, 0) + issues.uncategorized.length;
+    spinner?.succeed(`Collected ${issueCount} ${sourceLabel}`);
+  } catch (err) {
+    spinner?.fail(`Failed to collect ${sourceLabel}`);
+    throw err;
+  }
   if (issues.uncategorized.length > 0) {
     if (process.stdin.isTTY) {
       await promptForUncategorized(issues, config);
@@ -548,37 +661,63 @@ async function runGenerate(options) {
     console.log(markdown);
     if (options.publish && !options.dryRun) {
       const releaseName = currentParsed.prefix ? `${currentParsed.prefix.toUpperCase()} v${currentParsed.version}` : `v${currentParsed.version}`;
-      await client.createRelease(projectPath, {
-        tagName: options.tag,
-        name: releaseName,
-        description: markdown,
-        milestones: milestone ? [milestone] : void 0
-      });
-      console.log(`
-\u2713 Release published for ${options.tag}`);
+      try {
+        spinner?.start("Publishing release...");
+        await client.createRelease(projectPath, {
+          tagName: options.tag,
+          name: releaseName,
+          description: markdown,
+          milestones: milestone ? [milestone] : void 0
+        });
+        spinner?.succeed(`Release published for ${options.tag}`);
+      } catch (err) {
+        spinner?.fail("Failed to publish release");
+        throw err;
+      }
     }
   }
 }
 
 // src/cli/commands/validate.ts
+import ora2 from "ora";
 function registerValidateCommand(program2) {
-  program2.command("validate").description("Check open issues for proper labeling").option("--config <path>", "Config file path", ".releasejet.yml").action(async (options) => {
+  program2.command("validate").description("Check open issues for proper labeling").option("--config <path>", "Config file path", ".releasejet.yml").option("--debug", "Show debug information", false).addHelpText("after", `
+Examples:
+  $ releasejet validate                   Check with default config
+  $ releasejet validate --config my.yml   Check with custom config
+`).action(withErrorHandler(async (options) => {
     await runValidate(options);
-  });
+  }));
 }
 async function runValidate(options) {
+  const { debug } = createLogger(options.debug ?? false);
+  const spinner = options.debug ? null : ora2({ stream: process.stderr });
   const config = await loadConfig(options.config);
+  debug("Config loaded:", JSON.stringify(config, null, 2));
   const remoteUrl = getRemoteUrl();
   const hostUrl = config.provider.url || resolveHostUrl(remoteUrl);
   const projectPath = resolveProjectPath(remoteUrl);
+  debug("Host URL:", hostUrl);
+  debug("Project path:", projectPath);
   const token = await resolveToken(config.provider.type);
   const client = createClient(config, token);
-  const issues = await client.listIssues(projectPath, {
-    state: "opened"
-  });
+  let issues;
+  try {
+    spinner?.start("Fetching open issues...");
+    issues = await client.listIssues(projectPath, {
+      state: "opened"
+    });
+    spinner?.succeed(`Fetched ${issues.length} open issues`);
+  } catch (err) {
+    spinner?.fail("Failed to fetch issues");
+    throw err;
+  }
+  debug("Fetched", issues.length, "open issues");
   const categoryLabels = Object.keys(config.categories);
   const clientLabels = config.clients.map((c) => c.label);
   const isMultiClient = clientLabels.length > 0;
+  debug("Category labels:", categoryLabels);
+  debug("Client labels:", clientLabels.length > 0 ? clientLabels : "none (single-client)");
   const problems = [];
   for (const issue of issues) {
     const missing = [];
@@ -589,6 +728,7 @@ async function runValidate(options) {
       missing.push("category label");
     }
     if (missing.length > 0) {
+      debug(`  #${issue.number} "${issue.title}" labels=[${issue.labels.join(", ")}] missing=[${missing.join(", ")}]`);
       problems.push({ number: issue.number, title: issue.title, missing });
     }
   }
@@ -677,9 +817,12 @@ jobs:
           RELEASEJET_TOKEN: \${{ secrets.RELEASEJET_TOKEN }}
 `;
 function registerInitCommand(program2) {
-  program2.command("init").description("Interactive setup for ReleaseJet").action(async () => {
+  program2.command("init").description("Interactive setup for ReleaseJet").addHelpText("after", `
+Examples:
+  $ releasejet init    Run the interactive setup wizard
+`).action(withErrorHandler(async () => {
     await runInit();
-  });
+  }));
 }
 async function runInit() {
   console.log("\u{1F680} ReleaseJet Setup\n");
@@ -901,22 +1044,32 @@ import { readFile as readFile4, writeFile as writeFile2, unlink } from "fs/promi
 import { input as input2 } from "@inquirer/prompts";
 var CI_FILE = ".gitlab-ci.yml";
 function registerCiCommand(program2) {
-  const ci = program2.command("ci").description("Manage GitLab CI/CD integration");
-  ci.command("enable").description("Add ReleaseJet CI configuration to .gitlab-ci.yml").option("--tags <tags>", "Runner tags (comma-separated)").action(async (options) => {
+  const ci = program2.command("ci").description("Manage GitLab CI/CD integration").addHelpText("after", `
+Examples:
+  $ releasejet ci enable                   Interactive setup
+  $ releasejet ci enable --tags ci,docker  Non-interactive with tags
+  $ releasejet ci disable                  Remove CI configuration
+`);
+  ci.command("enable").description("Add ReleaseJet CI configuration to .gitlab-ci.yml").option("--tags <tags>", "Runner tags (comma-separated)").option("--debug", "Show debug information", false).action(withErrorHandler(async (options) => {
     await runCiEnable(options);
-  });
-  ci.command("disable").description("Remove ReleaseJet CI configuration from .gitlab-ci.yml").action(async () => {
+  }));
+  ci.command("disable").description("Remove ReleaseJet CI configuration from .gitlab-ci.yml").action(withErrorHandler(async () => {
     await runCiDisable();
-  });
+  }));
 }
 async function runCiEnable(options) {
+  const { debug } = createLogger(options.debug ?? false);
   let existing = "";
   try {
     existing = await readFile4(CI_FILE, "utf-8");
+    debug("Existing .gitlab-ci.yml found, length:", existing.length);
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
+    debug(".gitlab-ci.yml not found, will create new file");
   }
-  if (hasCiBlock(existing)) {
+  const hasMarkers = hasCiBlock(existing);
+  debug("ReleaseJet markers found:", hasMarkers);
+  if (hasMarkers) {
     console.log("ReleaseJet CI is already enabled.");
     return;
   }
@@ -930,6 +1083,7 @@ async function runCiEnable(options) {
     tags = tagsInput.trim() ? tagsInput.split(",").map((t) => t.trim()).filter(Boolean) : DEFAULT_TAGS;
   }
   const block = generateCiBlock(tags);
+  debug("Generated CI block:\n" + block);
   const content = appendCiBlock(existing, block);
   await writeFile2(CI_FILE, content);
   console.log("\u2713 ReleaseJet CI configuration added to .gitlab-ci.yml");
@@ -959,7 +1113,7 @@ async function runCiDisable() {
 
 // src/cli/index.ts
 var program = new Command();
-program.name("releasejet").description("Automated GitLab release notes generator").version("1.0.0");
+program.name("releasejet").description("Automated release notes generator for GitLab and GitHub").version("1.0.2");
 registerGenerateCommand(program);
 registerValidateCommand(program);
 registerInitCommand(program);

package/package.json

@@ -1,59 +1,60 @@
-{
-  "name": "@makispps/releasejet",
-  "version": "1.0.0",
-  "description": "Automated release notes generator for GitLab and GitHub",
-  "license": "MIT",
-  "author": "Mavroudis Papas",
-  "homepage": "https://www.releasejet.dev/",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/makisp/releasejet.git"
-  },
-  "bugs": {
-    "url": "https://github.com/makisp/releasejet/issues"
-  },
-  "keywords": [
-    "release-notes",
-    "changelog",
-    "gitlab",
-    "github",
-    "cli",
-    "automation",
-    "ci-cd"
-  ],
-  "type": "module",
-  "bin": {
-    "releasejet": "./dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "ci",
-    ".releasejet.example.yml"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "dev": "tsx src/cli/index.ts",
-    "prepublishOnly": "npm run test && npm run build"
-  },
-  "dependencies": {
-    "@gitbeaker/rest": "^41.3.0",
-    "@inquirer/prompts": "^7.2.0",
-    "@octokit/rest": "^22.0.1",
-    "commander": "^13.1.0",
-    "semver": "^7.7.1",
-    "yaml": "^2.7.0"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5.2",
-    "@types/semver": "^7.5.8",
-    "tsup": "^8.4.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.1.0"
-  },
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "@makispps/releasejet",
+  "version": "1.0.2",
+  "description": "Automated release notes generator for GitLab and GitHub",
+  "license": "MIT",
+  "author": "Mavroudis Papas",
+  "homepage": "https://www.releasejet.dev/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/makisp/releasejet.git"
+  },
+  "bugs": {
+    "url": "https://github.com/makisp/releasejet/issues"
+  },
+  "keywords": [
+    "release-notes",
+    "changelog",
+    "gitlab",
+    "github",
+    "cli",
+    "automation",
+    "ci-cd"
+  ],
+  "type": "module",
+  "bin": {
+    "releasejet": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "ci",
+    ".releasejet.example.yml"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsx src/cli/index.ts",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "dependencies": {
+    "@gitbeaker/rest": "^41.3.0",
+    "@inquirer/prompts": "^7.2.0",
+    "@octokit/rest": "^22.0.1",
+    "commander": "^13.1.0",
+    "ora": "^9.3.0",
+    "semver": "^7.7.1",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@types/semver": "^7.5.8",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}