releaseradar 1.0.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Guy Hershko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# releaseradar
+
+[![GitHub release](https://img.shields.io/github/v/release/ghershko3/releaseradar)](https://github.com/ghershko3/releaseradar/releases)
+[![npm version](https://img.shields.io/npm/v/releaseradar.svg)](https://www.npmjs.com/package/releaseradar)
+[![license](https://img.shields.io/github/license/ghershko3/releaseradar.svg)](https://github.com/ghershko3/releaseradar/blob/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://www.npmjs.com/package/releaseradar)
+
+> Built on `gh`. A faster way to answer "what shipped since the version in prod?"
+
+releaseradar wraps the GitHub CLI with opinionated shortcuts for teams that release often — especially monorepos with prefixed tags like `api-*` or `worker-*`. Set your org and repo once, then skip the flags and the date math.
+
+**Common workflows**
+
+- `rr releases api-2.1.0` — everything released since prod for one service
+- `rr releases api-2.1.0 api-2.1.5` — diff between two deployed versions
+- `rr list api --last 7d` — this week's releases for one service
+- `rr search "CVE"` — find releases mentioning a keyword
+
+Set `RR_ORG` and `RR_REPO` once; no flags on every command.
+
+## Demo
+
+```bash
+$ rr list --last 7d
+
+TAG          DATE             AUTHOR
+────────────────────────────────────────
+v2.1.5       2025-12-20 09:23  alice
+v2.1.4       2025-12-19 16:42  bob
+
+Total: 2 release(s)
+
+$ rr releases v2.1.0 v2.1.5
+
+TAG          DATE             AUTHOR    CHANGES
+──────────────────────────────────────────────────
+v2.1.5       2025-12-20 09:23  alice    Rate limiting fix
+v2.1.4       2025-12-19 16:42  bob      Auth token refresh
+v2.1.3       2025-12-19 14:15  charlie  DB connection pool
+
+Total: 3 release(s)
+```
+
+## Quick Start
+
+**Install**
+
+```bash
+npm i -g releaseradar
+# or
+pnpm i -g releaseradar
+# or
+yarn global add releaseradar
+```
+
+> **Requirements:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated. releaseradar uses `gh` under the hood — no separate GitHub token setup needed.
+>
+> ```bash
+> brew install gh && gh auth login
+> ```
+
+**Configure** (add to `~/.zshrc` or `~/.bashrc`)
+
+```bash
+export RR_ORG=myorg
+export RR_REPO=myrepo
+```
+
+**Use**
+
+```bash
+rr list                    # View all releases
+rr releases v2.1.0         # Compare since version
+rr search "fix"            # Search releases
+rr info v2.1.5             # Release details
+```
+
+## Commands
+
+```bash
+rr releases <from> [to]    # Show releases since a tag, or between two tags
+rr list [prefix]           # List all releases (optional: filter by prefix)
+rr search <term>           # Search release notes
+rr info <tag>              # Get detailed release info
+```
+
+**Flags**
+
+- `--org <name>` - Override GitHub organization
+- `--repo <name>` - Override repository name
+- `--last <N>m|h|d` - Filter `list` to releases in the last N minutes/hours/days (e.g. `24h`, `7d`)
+
+## Features
+
+**Version Comparison**
+
+```bash
+$ rr releases v2.1.0
+
+TAG          DATE             AUTHOR    CHANGES
+──────────────────────────────────────────────────
+v2.1.5       2025-12-20 09:23  alice    Rate limiting fix
+v2.1.4       2025-12-19 16:42  bob      Auth token refresh
+v2.1.3       2025-12-19 14:15  charlie  DB connection pool
+
+Total: 3 release(s)
+```
+
+**Version Range** - Compare between two specific versions (not up to latest)
+
+```bash
+$ rr releases v2.1.0 v2.1.5
+
+TAG          DATE             AUTHOR    CHANGES
+──────────────────────────────────────────────────
+v2.1.5       2025-12-20 09:23  alice    Rate limiting fix
+v2.1.4       2025-12-19 16:42  bob      Auth token refresh
+v2.1.3       2025-12-19 14:15  charlie  DB connection pool
+
+Total: 3 release(s)
+```
+
+**Monorepo Support** - Filter by service prefix
+
+```bash
+rr list api                # only api-* releases
+rr list --last 24h         # releases from the last 24 hours
+rr list api --last 7d      # api-* releases from the last 7 days
+rr releases api-1.0.0      # compare API versions
+```
+
+**Real Author Detection** - Shows actual developers, not CI bots
+
+**Multi-Repo** - Switch repos with flags
+
+```bash
+rr --org myorg --repo backend list
+```
+
+## Configuration
+
+**Environment Variables** (recommended)
+
+```bash
+export RR_ORG=myorg
+export RR_REPO=myrepo
+export RR_LIMIT=500        # optional, default: 300
+```
+
+**Command Flags** (override env vars)
+
+```bash
+rr --org company --repo backend releases v1.0
+```
+
+## Troubleshooting
+
+**Command not found**
+
+```bash
+npm i -g releaseradar
+# or
+pnpm i -g releaseradar
+# or
+yarn global add releaseradar
+```
+
+**GitHub CLI missing**
+
+```bash
+brew install gh && gh auth login
+```
+
+**No releases showing**
+
+- Verify: `rr --org myorg --repo myrepo list`
+- Increase limit: `export RR_LIMIT=500`
+
+## Migration from @ghershko/releaseradar
+
+The package was renamed from the scoped `@ghershko/releaseradar` to unscoped `releaseradar`. Install the new package:
+
+```bash
+npm i -g releaseradar
+```
+
+The `rr` command and all configuration (`RR_ORG`, `RR_REPO`, etc.) remain the same.
+
+## License
+
+MIT
+
+---
+
+[Report Bug](https://github.com/ghershko3/releaseradar/issues) · [Request Feature](https://github.com/ghershko3/releaseradar/issues)

package/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+import chalk from 'chalk';
+import { checkGitHubCli } from './src/api/github.js';
+import { 
+  commandReleases, 
+  commandInfo, 
+  commandSearch, 
+  commandList,
+  showHelp 
+} from './src/commands/index.js';
+import { validateConfig, RrError } from './src/utils/validation.js';
+import { COMMANDS_REQUIRING_GH, ENV_VAR_KEYS, DEFAULT_RELEASE_LIMIT } from './src/utils/constants.js';
+
+const resolveConfig = (configOverrides) => {
+  const merged = {
+    org: configOverrides.org || process.env[ENV_VAR_KEYS.ORG],
+    repo: configOverrides.repo || process.env[ENV_VAR_KEYS.REPO],
+    releaseLimit: process.env[ENV_VAR_KEYS.LIMIT] 
+      ? parseInt(process.env[ENV_VAR_KEYS.LIMIT], 10) 
+      : DEFAULT_RELEASE_LIMIT
+  };
+  
+  if (!merged.org || !merged.repo) {
+    console.error(chalk.red('\nMissing required configuration\n'));
+    console.log('Set environment variables (recommended):');
+    console.log(chalk.dim('  export RR_ORG=myorg'));
+    console.log(chalk.dim('  export RR_REPO=myrepo\n'));
+    console.log('Or use flags:');
+    console.log(chalk.dim('  rr --org myorg --repo myrepo list\n'));
+    process.exit(1);
+  }
+  
+  const validated = validateConfig(merged);
+  return { ...validated, last: configOverrides.last };
+};
+
+const parseArguments = (args) => {
+  const flags = args.filter(arg => arg.startsWith('--'));
+  const nonFlags = args.filter(arg => !arg.startsWith('--'));
+  
+  const getFlagValue = (flagName) => {
+    const flag = flags.find(f => f.startsWith(`--${flagName}=`) || f === `--${flagName}`);
+    if (!flag) return null;
+    
+    const equalIndex = flag.indexOf('=');
+    if (equalIndex === -1) {
+      const flagIndex = args.indexOf(flag);
+      const nextArg = args[flagIndex + 1];
+      return nextArg && !nextArg.startsWith('--') ? nextArg : null;
+    }
+    return flag.substring(equalIndex + 1);
+  };
+  
+  return {
+    command: nonFlags[0],
+    parameter: nonFlags[1],
+    parameter2: nonFlags[2],
+    configOverrides: {
+      org: getFlagValue('org'),
+      repo: getFlagValue('repo'),
+      last: getFlagValue('last')
+    }
+  };
+};
+
+const COMMAND_HANDLERS = {
+  releases: commandReleases,
+  info: commandInfo,
+  search: commandSearch,
+  list: commandList,
+  help: showHelp,
+  '--help': showHelp,
+  '-h': showHelp
+};
+
+const COMMANDS_NOT_REQUIRING_CONFIG = ['help', '--help', '-h'];
+
+const executeCommand = (command, parameter, parameter2, config) => {
+  const handler = COMMAND_HANDLERS[command];
+  
+  if (!handler) {
+    throw new RrError(`Unknown command: ${command}`);
+  }
+  
+  if (COMMANDS_REQUIRING_GH.includes(command)) {
+    checkGitHubCli();
+  }
+  
+  handler(parameter, config, parameter2);
+};
+
+const main = () => {
+  try {
+    const args = process.argv.slice(2);
+    
+    if (args.length === 0) {
+      showHelp();
+      process.exit(0);
+    }
+    
+    const { command, parameter, parameter2, configOverrides } = parseArguments(args);
+    
+    if (COMMANDS_NOT_REQUIRING_CONFIG.includes(command)) {
+      executeCommand(command, parameter, parameter2, null);
+    } else {
+      const config = resolveConfig(configOverrides);
+      executeCommand(command, parameter, parameter2, config);
+    }
+    
+  } catch (error) {
+    if (error instanceof RrError) {
+      console.error(chalk.red(`\n${error.message}\n`));
+      process.exit(1);
+    }
+    
+    console.error(chalk.red('\nUnexpected error:'), error.message);
+    console.error(chalk.dim(error.stack));
+    process.exit(1);
+  }
+};
+
+main();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "releaseradar",
+  "version": "1.0.17",
+  "description": "CLI to list, compare, search, and diff GitHub releases from your terminal",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "rr": "index.js"
+  },
+  "preferGlobal": true,
+  "scripts": {
+    "start": "node index.js",
+    "version:patch": "npm version patch -m 'chore: bump version to %s'",
+    "version:minor": "npm version minor -m 'chore: bump version to %s'",
+    "version:major": "npm version major -m 'chore: bump version to %s'"
+  },
+  "keywords": [
+    "github-releases",
+    "release-notes",
+    "changelog",
+    "gh-cli",
+    "cli",
+    "devtools",
+    "semver",
+    "monorepo"
+  ],
+  "author": "Guy Hershko <ghershko3@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ghershko3/releaseradar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ghershko3/releaseradar/issues"
+  },
+  "homepage": "https://github.com/ghershko3/releaseradar#readme",
+  "files": [
+    "index.js",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2"
+  }
+}

package/src/README.md

@@ -0,0 +1,279 @@
+# Source Code Architecture
+
+Clean, modular organization following separation of concerns principles.
+
+## Directory Structure
+
+```
+src/
+├── utils/           # Utility functions (reusable across layers)
+│   ├── constants.js     # Application-wide constants
+│   ├── string-utils.js  # String manipulation utilities
+│   ├── date-utils.js    # Date formatting and operations
+│   ├── validation.js    # Input validation and error classes
+│   └── shell-utils.js   # Shell command execution wrapper
+│
+├── api/             # External API communication
+│   └── github.js        # GitHub CLI wrapper
+│
+├── services/        # Business logic layer
+│   └── releases.js      # Release data processing
+│
+├── presentation/    # Display formatting layer
+│   ├── formatter.js     # Console output formatting
+│   └── table.js         # Table rendering utilities
+│
+└── commands/        # CLI command orchestration
+    └── index.js         # Command handlers
+```
+
+## Layer Responsibilities
+
+### `utils/` - Utility Functions
+
+**Purpose**: Reusable, pure functions used across all layers
+
+**Modules**:
+
+- **`constants.js`** - Application constants (limits, patterns, widths)
+- **`string-utils.js`** - String operations (prefix extraction, text cleaning)
+- **`date-utils.js`** - Date formatting and comparisons
+- **`validation.js`** - Input validation, config validation, custom error classes
+- **`shell-utils.js`** - Safe shell command execution
+
+**Characteristics**:
+
+- Pure functions (no side effects)
+- Highly testable
+- Zero external dependencies within utils
+
+### `api/` - External Communication
+
+**Purpose**: Isolates all external API calls
+
+**Responsibilities**:
+
+- Wraps GitHub CLI (`gh`) commands
+- Handles authentication checks
+- Manages pagination for large datasets
+- Error handling for API failures
+
+**Key Functions**:
+
+- `checkGitHubCli()` - Verifies CLI installation and auth
+- `fetchReleasesFromGitHub()` - Fetches paginated releases
+
+### `services/` - Business Logic
+
+**Purpose**: Core data processing and transformation
+
+**Responsibilities**:
+
+- Transform raw GitHub data to internal format
+- Extract real authors from CI/CD bot releases
+- Sort and filter release data
+- Version prefix extraction
+
+**Key Functions**:
+
+- `fetchAndProcessReleases()` - Main orchestration
+- `extractRealAuthorFromReleaseNotes()` - Parse release notes for real author
+- `transformReleaseData()` - Convert GitHub format to internal format
+
+**Data Flow**:
+
+```
+Raw GitHub JSON → Transform → Validate → Sort → Internal Format
+```
+
+### `presentation/` - Display Formatting
+
+**Purpose**: Handles all console output formatting
+
+**Responsibilities**:
+
+- Format release data for display
+- Create table layouts
+- Handle detailed vs. compact views
+- Text truncation and padding
+
+**Key Functions**:
+
+- `formatRelease()` - Main formatting dispatcher
+- `formatReleaseDetailed()` - Detailed single release view
+- `formatReleaseCompact()` - Table row formatting
+- `createReleasesTableHeader()` - Table header creation
+
+**Separation**: Knows how to display, not what to fetch or process
+
+### `commands/` - CLI Orchestration
+
+**Purpose**: Coordinates between services and presentation
+
+**Responsibilities**:
+
+- Handle command routing
+- Validate command parameters
+- Coordinate data fetching (services) and display (presentation)
+- Implement command-specific logic
+
+**Key Functions**:
+
+- `commandReleases()` - Show releases since version
+- `commandInfo()` - Show detailed release info
+- `commandSearch()` - Search across releases
+- `commandList()` - List releases with filtering
+- `showHelp()` - Display help text
+
+**Pattern**: Each command follows:
+
+1. Validate input
+2. Fetch/process data (via services)
+3. Format output (via presentation)
+
+## Design Principles
+
+### 1. Separation of Concerns
+
+Each layer has a single, well-defined responsibility:
+
+- **Utils** = reusable tools
+- **API** = external communication
+- **Services** = business logic
+- **Presentation** = formatting
+- **Commands** = orchestration
+
+### 2. Dependency Direction
+
+```
+Commands → Services → API
+Commands → Presentation
+All layers → Utils
+```
+
+No circular dependencies. Lower layers never depend on higher layers.
+
+### 3. Pure Functions Where Possible
+
+Most functions in `utils/` and parts of `services/` are pure:
+
+- Same input = same output
+- No side effects
+- Easy to test
+
+### 4. Error Handling
+
+Custom error classes in `utils/validation.js`:
+
+- `RrError` - Base error class
+- `ValidationError` - Input/config validation errors
+- `GitHubApiError` - API communication errors
+
+Errors bubble up to `index.js` for centralized handling.
+
+### 5. Modern JavaScript Patterns
+
+- Destructuring for cleaner code
+- Optional chaining (`?.`) for safe property access
+- Nullish coalescing (`??`) for default values
+- Arrow functions for concise syntax
+- ES6 modules for clear imports/exports
+
+## Data Models
+
+### Release Object (Internal Format)
+
+```javascript
+{
+  tag: string,           // e.g., "app-25.12.107"
+  name: string,          // Release name
+  repo: string,          // Repository name
+  published: string,     // ISO date string
+  author: string,        // Real author (not bot)
+  releaseNotes: string,  // Full release notes
+  url: string,           // GitHub release URL
+  commitSha: string      // Commit SHA
+}
+```
+
+### Config Object
+
+```javascript
+{
+  org: string,              // GitHub organization
+  repo: string,             // Repository name
+  releaseLimit: number      // Max releases to fetch (default: 300)
+}
+```
+
+## Testing Strategy
+
+Tests are organized by functionality:
+
+- **`formatting.test.js`** - String/date utilities
+- **`github.test.js`** - Author extraction logic
+- **`run-all.js`** - Test runner
+
+### Test Coverage
+
+- ✅ Prefix extraction with edge cases
+- ✅ Date formatting
+- ✅ Change text extraction and cleaning
+- ✅ Real author detection patterns
+- ✅ Null/empty input handling
+
+## Adding New Features
+
+### Adding a New Utility
+
+1. Add to appropriate file in `utils/` or create new util file
+2. Export function
+3. Add tests
+4. Document in this README
+
+### Adding a New Command
+
+1. Add handler to `commands/index.js`
+2. Register in `COMMAND_HANDLERS` in `index.js`
+3. Add to help text in `showHelp()`
+4. Update main README
+
+### Adding a New Data Source
+
+1. Create new file in `api/` (e.g., `gitlab.js`)
+2. Implement same interface as `github.js`
+3. Update services to handle new format
+4. Add configuration options
+
+## Code Style Guidelines
+
+- Use `const` by default, `let` when needed
+- Prefer arrow functions for callbacks
+- Use descriptive variable names (e.g., `releaseNotes` not `body`)
+- Extract magic numbers/strings to constants
+- Keep functions small (< 30 lines ideally)
+- One responsibility per function
+- Document complex logic with clear comments (when needed)
+
+## Performance Considerations
+
+- Releases are fetched once per command invocation
+- Sorting/filtering happen in memory (fast for < 1000 releases)
+- Table formatting is optimized for console output
+- Pagination prevents fetching unnecessary data
+
+## Future Enhancements
+
+Potential improvements:
+
+- Caching releases to disk for faster subsequent runs
+- Compare two versions side-by-side
+- Export to JSON/CSV formats
+- Interactive mode with prompts
+- Multiple repository support in single command
+- Release notes templates validation
+- Custom output formatters (JSON, Markdown)
+
+---
+
+**Architecture Goal**: Simple, maintainable, and extensible code that's easy to understand and modify.

package/src/api/github.js

@@ -0,0 +1,76 @@
+import chalk from 'chalk';
+import { executeCommand, checkCommandExists } from '../utils/shell-utils.js';
+import { GitHubApiError } from '../utils/validation.js';
+import { RELEASES_PER_PAGE, MAX_BUFFER_SIZE } from '../utils/constants.js';
+
+export const checkGitHubCliInstalled = () => {
+  if (!checkCommandExists('gh')) {
+    console.error(chalk.red('\nGitHub CLI (gh) is not installed or not in PATH'));
+    console.log('\nInstall GitHub CLI:');
+    console.log(chalk.dim('  macOS:   brew install gh'));
+    console.log(chalk.dim('  Linux:   https://github.com/cli/cli/blob/trunk/docs/install_linux.md'));
+    console.log(chalk.dim('  Windows: https://github.com/cli/cli/releases\n'));
+    
+    throw new GitHubApiError('GitHub CLI not found');
+  }
+};
+
+export const checkGitHubAuthentication = () => {
+  try {
+    const result = executeCommand('gh auth status 2>&1');
+    
+    if (!result?.includes('Logged in to github.com')) {
+      throw new Error('Not authenticated');
+    }
+  } catch {
+    console.error(chalk.red('\nGitHub CLI is not authenticated'));
+    console.log('\nAuthenticate with GitHub:');
+    console.log(chalk.dim('  Run: gh auth login\n'));
+    
+    throw new GitHubApiError('GitHub CLI not authenticated');
+  }
+};
+
+export const checkGitHubCli = () => {
+  checkGitHubCliInstalled();
+  checkGitHubAuthentication();
+};
+
+export const fetchReleasesFromGitHub = (org, repo, limit = 300) => {
+  process.stdout.write(chalk.dim(`Fetching releases from ${chalk.cyan(org + '/' + repo)}...`));
+  
+  const totalPages = Math.ceil(limit / RELEASES_PER_PAGE);
+  const allReleases = [];
+  
+  try {
+    for (let page = 1; page <= totalPages; page++) {
+      const apiEndpoint = `/repos/${org}/${repo}/releases`;
+      const params = `per_page=${RELEASES_PER_PAGE}&page=${page}`;
+      const command = `gh api "${apiEndpoint}?${params}"`;
+      
+      const result = executeCommand(command, { 
+        maxBuffer: MAX_BUFFER_SIZE 
+      });
+      
+      const pageReleases = JSON.parse(result);
+      
+      if (!Array.isArray(pageReleases) || pageReleases.length === 0) {
+        break;
+      }
+      
+      allReleases.push(...pageReleases);
+      
+      if (pageReleases.length < RELEASES_PER_PAGE || allReleases.length >= limit) {
+        break;
+      }
+    }
+    
+    const limitedReleases = allReleases.slice(0, limit);
+    process.stdout.write('\r' + ' '.repeat(80) + '\r');
+    
+    return limitedReleases;
+  } catch (error) {
+    process.stdout.write('\r' + ' '.repeat(80) + '\r');
+    throw error;
+  }
+};

package/src/commands/index.js

@@ -0,0 +1,265 @@
+import chalk from 'chalk';
+import { fetchAndProcessReleases, extractVersionPrefix } from '../services/releases.js';
+import { formatRelease } from '../presentation/formatter.js';
+import { printTable, createReleasesTableHeader } from '../presentation/table.js';
+import { requireParameter, ValidationError, validateConfig } from '../utils/validation.js';
+import { isNewerThan, parseDuration, isWithinLast } from '../utils/date-utils.js';
+
+const findReleaseByVersion = (releases, version) => {
+  return releases.find(release => release.tag === version);
+};
+
+const filterReleasesByPrefix = (releases, prefix) => {
+  return releases.filter(release => extractVersionPrefix(release.tag) === prefix);
+};
+
+const filterReleasesNewerThan = (releases, targetRelease) => {
+  return releases.filter(release => 
+    isNewerThan(release.published, targetRelease.published)
+  );
+};
+
+export const filterReleasesInRange = (releases, fromRelease, toRelease) =>
+  releases.filter(release =>
+    isNewerThan(release.published, fromRelease.published) &&
+    !isNewerThan(release.published, toRelease.published)
+  );
+
+const filterReleasesByLast = (releases, last) => {
+  if (!last) return releases;
+  const durationMs = parseDuration(last);
+  if (!durationMs) {
+    throw new ValidationError(
+      `Invalid --last value: ${last}. Use formats like 30m, 24h, 7d`
+    );
+  }
+  return releases.filter(release => isWithinLast(release.published, durationMs));
+};
+
+const matchesSearchQuery = (release, query) => {
+  const searchableText = [
+    release.tag,
+    release.name,
+    release.releaseNotes
+  ].join(' ').toLowerCase();
+  
+  return searchableText.includes(query.toLowerCase());
+};
+
+export const commandReleases = (sinceVersion, config, toVersion) => {
+  requireParameter(sinceVersion, 'releases');
+  
+  const releases = fetchAndProcessReleases(config);
+  const prefix = extractVersionPrefix(sinceVersion);
+  
+  if (!prefix) {
+    throw new ValidationError(`Could not extract prefix from version: ${sinceVersion}`);
+  }
+  
+  const releasesWithPrefix = filterReleasesByPrefix(releases, prefix);
+  const targetRelease = findReleaseByVersion(releasesWithPrefix, sinceVersion);
+  
+  if (!targetRelease) {
+    console.log(chalk.yellow(`\nVersion ${sinceVersion} not found.`) + ` Showing all releases with prefix "${prefix}":\n`);
+    const tableConfig = createReleasesTableHeader();
+    printTable(tableConfig);
+    releasesWithPrefix.forEach(release => 
+      formatRelease(release, { showChanges: true })
+    );
+    console.log(chalk.dim(`\nTotal: ${releasesWithPrefix.length} release(s)`));
+    return;
+  }
+
+  if (toVersion) {
+    const toPrefix = extractVersionPrefix(toVersion);
+    if (toPrefix !== prefix) {
+      throw new ValidationError(
+        `Version prefixes must match: ${sinceVersion} (${prefix}) vs ${toVersion} (${toPrefix})`
+      );
+    }
+
+    const toRelease = findReleaseByVersion(releasesWithPrefix, toVersion);
+    if (!toRelease) {
+      console.log(chalk.yellow(`\nVersion ${toVersion} not found.`) + ` Showing all releases with prefix "${prefix}":\n`);
+      const tableConfig = createReleasesTableHeader();
+      printTable(tableConfig);
+      releasesWithPrefix.forEach(release =>
+        formatRelease(release, { showChanges: true })
+      );
+      console.log(chalk.dim(`\nTotal: ${releasesWithPrefix.length} release(s)`));
+      return;
+    }
+
+    if (!isNewerThan(toRelease.published, targetRelease.published)) {
+      throw new ValidationError('To version must be newer than from version');
+    }
+
+    const rangeReleases = filterReleasesByLast(
+      filterReleasesInRange(releasesWithPrefix, targetRelease, toRelease),
+      config.last
+    );
+
+    console.log(`\nReleases from ${chalk.cyan(sinceVersion)} to ${chalk.cyan(toVersion)} ${chalk.dim(`(prefix: ${prefix}):`)}\n`);
+    const tableConfig = createReleasesTableHeader();
+    printTable(tableConfig);
+
+    if (rangeReleases.length === 0) {
+      console.log(chalk.dim('No releases found in range.'));
+    } else {
+      rangeReleases.forEach(release =>
+        formatRelease(release, { showChanges: true })
+      );
+      console.log(chalk.dim(`\nTotal: ${rangeReleases.length} release(s)`));
+    }
+    return;
+  }
+  
+  const newerReleases = filterReleasesByLast(
+    filterReleasesNewerThan(releasesWithPrefix, targetRelease),
+    config.last
+  );
+  
+  console.log(`\nReleases since ${chalk.cyan(sinceVersion)} ${chalk.dim(`(prefix: ${prefix}):`)}\n`);
+  const tableConfig = createReleasesTableHeader();
+  printTable(tableConfig);
+  
+  if (newerReleases.length === 0) {
+    console.log(chalk.dim('No newer releases found.'));
+  } else {
+    newerReleases.forEach(release => 
+      formatRelease(release, { showChanges: true })
+    );
+    console.log(chalk.dim(`\nTotal: ${newerReleases.length} release(s)`));
+  }
+};
+
+export const commandInfo = (version, config) => {
+  requireParameter(version, 'info');
+  
+  const releases = fetchAndProcessReleases(config);
+  const release = findReleaseByVersion(releases, version);
+  
+  if (!release) {
+    throw new ValidationError(`Release not found: ${version}`);
+  }
+  
+  formatRelease(release, { detailed: true });
+};
+
+export const commandSearch = (query, config) => {
+  requireParameter(query, 'search');
+  
+  const releases = fetchAndProcessReleases(config);
+  const matchingReleases = releases.filter(release => 
+    matchesSearchQuery(release, query)
+  );
+  
+  console.log(`\nSearch results for "${query}":\n`);
+  const tableConfig = createReleasesTableHeader();
+  printTable(tableConfig);
+  
+  if (matchingReleases.length === 0) {
+    console.log(chalk.dim('No matches found.'));
+  } else {
+    matchingReleases.forEach(release => 
+      formatRelease(release, { showChanges: true })
+    );
+    console.log(chalk.dim(`\nTotal: ${matchingReleases.length} match(es)`));
+  }
+};
+
+export const commandList = (prefix, config) => {
+  const releases = fetchAndProcessReleases(config);
+  
+  let filteredReleases = prefix
+    ? filterReleasesByPrefix(releases, prefix)
+    : releases;
+
+  if (config.last) {
+    const durationMs = parseDuration(config.last);
+    if (!durationMs) {
+      throw new ValidationError(
+        `Invalid --last value: ${config.last}. Use formats like 30m, 24h, 7d`
+      );
+    }
+    filteredReleases = filteredReleases.filter(release =>
+      isWithinLast(release.published, durationMs)
+    );
+  }
+
+  const lastSuffix = config.last ? ` (last ${config.last})` : '';
+  const title = prefix
+    ? `\nReleases with prefix "${prefix}"${lastSuffix}:`
+    : `\nAll releases${lastSuffix}:`;
+  
+  console.log(`${title}\n`);
+  
+  const tableConfig = createReleasesTableHeader();
+  printTable(tableConfig);
+  
+  filteredReleases.forEach(release => 
+    formatRelease(release, { showChanges: true })
+  );
+  
+  console.log(chalk.dim(`\nTotal: ${filteredReleases.length} release(s)`));
+};
+
+export const showHelp = () => {
+  console.log(`
+ReleaseRadar (rr) 🚀
+
+QUICK START:
+  # Set once in ~/.zshrc or ~/.bashrc
+  export RR_ORG=myorg RR_REPO=myrepo
+  
+  # Start using immediately!
+  rr list
+
+COMMANDS:
+  rr releases <from> [to]  Compare: What's new since a version, or between two versions
+                           Example: rr releases app-25.12.100
+                           Example: rr releases app-25.12.100 app-25.12.105
+
+  rr search "<query>"   Search: Find releases by keyword
+                        Example: rr search "authentication fix"
+
+  rr list [prefix]      Browse: All releases (optionally filtered)
+                        Example: rr list api
+                        Example: rr list --last 24h
+
+  rr info <tag>         Details: Full info about a release
+                        Example: rr info app-25.12.107
+
+CONFIGURATION:
+  Environment Variables (recommended):
+    RR_ORG=myorg       Your GitHub organization
+    RR_REPO=myrepo     Your repository name
+    RR_LIMIT=500       Max releases to fetch (default: 300)
+
+  Override with flags:
+    --org <name>       One-time org override
+    --repo <name>      One-time repo override
+    --last <N>m|h|d    Filter list to releases in the last N minutes/hours/days
+
+EXAMPLES:
+  # Setup once
+  echo 'export RR_ORG=acme RR_REPO=backend' >> ~/.zshrc
+
+  # Find what changed since production
+  rr releases api-2.1.0
+
+  # Compare between two deployed versions
+  rr releases api-2.1.0 api-2.1.5
+
+  # Search for security patches
+  rr search "CVE"
+
+  # Check a specific release
+  rr info api-2.1.5
+
+  # Override for different repo
+  rr --org acme --repo frontend list
+
+Need help? Visit: https://github.com/ghershko3/releaseradar
+`);
+};

package/src/presentation/formatter.js

@@ -0,0 +1,73 @@
+import chalk from 'chalk';
+import { formatIsoDate } from '../utils/date-utils.js';
+import { extractFirstChangeFromNotes, truncateText, padText } from '../utils/string-utils.js';
+import { createSeparator } from './table.js';
+import { TABLE_WIDTHS } from '../utils/constants.js';
+
+export const formatReleaseDetailed = (release) => {
+  if (!release?.tag) return;
+  
+  const maxWidth = 80;
+  const border = '═'.repeat(maxWidth);
+  const light = '─'.repeat(maxWidth);
+  
+  console.log(chalk.dim(border));
+  console.log(chalk.cyan.bold(`  ${release.tag}`));
+  console.log(chalk.dim(light));
+  
+  const formatRow = (label, value, dimValue = false) => {
+    const padding = ' '.repeat(2);
+    const labelFormatted = chalk.dim(label.padEnd(12));
+    const valueFormatted = dimValue ? chalk.dim(value) : value;
+    console.log(`${padding}${labelFormatted}${valueFormatted}`);
+  };
+  
+  formatRow('Published:', formatIsoDate(release.published), true);
+  formatRow('Author:', release.author);
+  formatRow('Repository:', release.repo, true);
+  
+  if (release.commitSha) {
+    formatRow('Commit:', release.commitSha.substring(0, 12), true);
+  }
+  
+  formatRow('URL:', release.url, true);
+  
+  if (release.releaseNotes && release.releaseNotes.trim()) {
+    console.log(chalk.dim(light));
+    console.log(chalk.dim('  Release Notes:'));
+    console.log();
+    const notes = release.releaseNotes.split('\n').map(line => `  ${line}`).join('\n');
+    console.log(notes);
+  }
+  
+  console.log(chalk.dim(border));
+};
+
+export const formatReleaseCompact = (release, options = {}) => {
+  if (!release?.tag) return;
+  
+  const { showChanges = false } = options;
+  const tag = chalk.cyan(padText(release.tag, TABLE_WIDTHS.TAG));
+  const date = chalk.dim(padText(formatIsoDate(release.published).substring(0, 16), TABLE_WIDTHS.DATE));
+  const author = padText(release.author, TABLE_WIDTHS.AUTHOR);
+  
+  if (showChanges) {
+    const changes = extractFirstChangeFromNotes(release.releaseNotes);
+    const truncatedChanges = truncateText(changes, TABLE_WIDTHS.CHANGES);
+    const changesPadded = padText(truncatedChanges, TABLE_WIDTHS.CHANGES);
+    console.log(`${tag} ${date} ${author} ${changesPadded}`);
+  } else {
+    const repo = padText(release.repo, TABLE_WIDTHS.REPO);
+    console.log(`${tag} ${repo} ${date} ${author}`);
+  }
+};
+
+export const formatRelease = (release, options = {}) => {
+  const { detailed = false, showChanges = false } = options;
+  
+  if (detailed) {
+    formatReleaseDetailed(release);
+  } else {
+    formatReleaseCompact(release, { showChanges });
+  }
+};

package/src/presentation/table.js

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+import { TABLE_WIDTHS } from '../utils/constants.js';
+
+export const createSeparator = (length) => {
+  return chalk.dim('─'.repeat(length));
+};
+
+export const createTableHeader = (columns) => {
+  return columns.map(col => col.text.padEnd(col.width)).join(' ');
+};
+
+export const createTableRow = (values, widths) => {
+  return values.map((value, index) => 
+    (value || '').padEnd(widths[index])
+  ).join(' ');
+};
+
+export const printTable = ({ headers, separator }) => {
+  console.log(headers);
+  console.log(createSeparator(separator));
+};
+
+export const createReleasesTableHeader = () => {
+  return {
+    headers: createTableHeader([
+      { text: 'TAG', width: TABLE_WIDTHS.TAG },
+      { text: 'DATE', width: TABLE_WIDTHS.DATE },
+      { text: 'AUTHOR', width: TABLE_WIDTHS.AUTHOR },
+      { text: 'CHANGES', width: TABLE_WIDTHS.CHANGES }
+    ]),
+    separator: TABLE_WIDTHS.SEPARATOR_FULL
+  };
+};
+

package/src/services/releases.js

@@ -0,0 +1,60 @@
+import { fetchReleasesFromGitHub } from '../api/github.js';
+import { extractVersionPrefix } from '../utils/string-utils.js';
+import { validateReleases } from '../utils/validation.js';
+import { RELEASE_AUTHOR_PATTERN, PR_AUTHOR_PATTERN } from '../utils/constants.js';
+
+export const extractRealAuthorFromReleaseNotes = (releaseNotes, fallbackAuthor) => {
+  if (!releaseNotes) return fallbackAuthor;
+  
+  const createdByMatch = releaseNotes.match(RELEASE_AUTHOR_PATTERN);
+  if (createdByMatch) {
+    return createdByMatch[1];
+  }
+  
+  const prAuthorMatch = releaseNotes.match(PR_AUTHOR_PATTERN);
+  if (prAuthorMatch) {
+    return prAuthorMatch[1];
+  }
+  
+  return fallbackAuthor;
+};
+
+export const transformReleaseData = (release, repoName) => {
+  const botAuthor = release?.author?.login ?? 'unknown';
+  const releaseNotes = release.body ?? '';
+  const realAuthor = extractRealAuthorFromReleaseNotes(releaseNotes, botAuthor);
+  
+  return {
+    tag: release.tag_name,
+    name: release.name || release.tag_name,
+    repo: repoName,
+    published: release.published_at,
+    author: realAuthor,
+    releaseNotes,
+    url: release.html_url,
+    commitSha: release.target_commitish
+  };
+};
+
+export const sortReleasesByDate = (releases) => {
+  return releases.sort((a, b) => 
+    new Date(b.published).getTime() - new Date(a.published).getTime()
+  );
+};
+
+export const fetchAndProcessReleases = (config) => {
+  const { org, repo, releaseLimit } = config;
+  
+  const rawReleases = fetchReleasesFromGitHub(org, repo, releaseLimit);
+  validateReleases(rawReleases);
+  
+  const processedReleases = rawReleases
+    .filter(release => release?.tag_name)
+    .map(release => transformReleaseData(release, repo));
+  
+  const sortedReleases = sortReleasesByDate(processedReleases);
+  
+  return sortedReleases;
+};
+
+export { extractVersionPrefix };

package/src/utils/constants.js

@@ -0,0 +1,29 @@
+export const DEFAULT_RELEASE_LIMIT = 300;
+export const RELEASES_PER_PAGE = 100;
+export const MAX_BUFFER_SIZE = 10 * 1024 * 1024;
+
+export const ENV_VAR_KEYS = {
+  ORG: 'RR_ORG',
+  REPO: 'RR_REPO',
+  LIMIT: 'RR_LIMIT'
+};
+
+export const TABLE_WIDTHS = {
+  TAG: 30,
+  REPO: 20,
+  DATE: 17,
+  AUTHOR: 16,
+  CHANGES: 50,
+  SEPARATOR_FULL: 115,
+  SEPARATOR_STANDARD: 80
+};
+
+export const COMMANDS_REQUIRING_GH = ['releases', 'info', 'search', 'list'];
+
+export const VERSION_PREFIX_PATTERN = /^([a-zA-Z]+-?[a-zA-Z]*-|\d+\.)/;
+export const RELEASE_AUTHOR_PATTERN = /Release created by (\S+)/;
+export const PR_AUTHOR_PATTERN = /by @(\S+) in/;
+export const BULLET_POINT_PATTERN = /^[*-]\s+(.+)/;
+
+export const EXCLUDED_CHANGELOG_PHRASES = ['Full Changelog', 'Services tagged'];
+

package/src/utils/date-utils.js

@@ -0,0 +1,24 @@
+export const formatIsoDate = (isoDateString) => {
+  const date = new Date(isoDateString);
+  return date.toISOString().replace('T', ' ').substring(0, 19);
+};
+
+export const getTimestamp = (dateString) => {
+  return new Date(dateString).getTime();
+};
+
+export const isNewerThan = (date1, date2) => {
+  return getTimestamp(date1) > getTimestamp(date2);
+};
+
+export const parseDuration = (input) => {
+  const match = /^(\d+)([mhd])$/.exec((input || '').trim());
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  const multipliers = { m: 60000, h: 3600000, d: 86400000 };
+  return value * multipliers[match[2]];
+};
+
+export const isWithinLast = (dateString, durationMs, now = Date.now()) =>
+  now - getTimestamp(dateString) <= durationMs;
+

package/src/utils/shell-utils.js

@@ -0,0 +1,27 @@
+import { execSync } from 'child_process';
+import { GitHubApiError } from './validation.js';
+
+export const executeCommand = (command, options = {}) => {
+  try {
+    return execSync(command, {
+      encoding: 'utf-8',
+      stdio: options.silent ? 'ignore' : 'pipe',
+      ...options
+    });
+  } catch (error) {
+    if (options.throwOnError !== false) {
+      throw new GitHubApiError(`Command failed: ${command}\n${error.message}`);
+    }
+    return null;
+  }
+};
+
+export const checkCommandExists = (command) => {
+  try {
+    executeCommand(`${command} --version`, { silent: true });
+    return true;
+  } catch {
+    return false;
+  }
+};
+

package/src/utils/string-utils.js

@@ -0,0 +1,53 @@
+import { 
+  VERSION_PREFIX_PATTERN, 
+  BULLET_POINT_PATTERN, 
+  EXCLUDED_CHANGELOG_PHRASES 
+} from './constants.js';
+
+export const extractVersionPrefix = (version) => {
+  if (!version) return null;
+  const match = version.match(VERSION_PREFIX_PATTERN);
+  return match ? match[1] : null;
+};
+
+export const cleanAuthorMention = (text) => {
+  if (!text) return text;
+  return text
+    .replace(/\s+by @\S+/g, '')
+    .replace(/\s+in https?:\/\/\S+/g, '');
+};
+
+export const extractFirstChangeFromNotes = (releaseNotes) => {
+  if (!releaseNotes) return '';
+  
+  const lines = releaseNotes.split('\n');
+  const changes = [];
+  
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+    const match = trimmedLine.match(BULLET_POINT_PATTERN);
+    
+    if (match) {
+      const hasExcludedPhrase = EXCLUDED_CHANGELOG_PHRASES.some(
+        phrase => trimmedLine.includes(phrase)
+      );
+      
+      if (!hasExcludedPhrase) {
+        const cleanedText = cleanAuthorMention(match[1]);
+        changes.push(cleanedText);
+      }
+    }
+  }
+  
+  return changes[0] || '';
+};
+
+export const truncateText = (text, maxLength) => {
+  if (!text) return '';
+  return text.length > maxLength ? text.substring(0, maxLength) : text;
+};
+
+export const padText = (text, width) => {
+  return (text || '').padEnd(width);
+};
+

package/src/utils/validation.js

@@ -0,0 +1,66 @@
+import { DEFAULT_RELEASE_LIMIT } from './constants.js';
+
+import chalk from 'chalk';
+
+export class RrError extends Error {
+  constructor(message, code = 'RR_ERROR') {
+    super(message);
+    this.name = 'RrError';
+    this.code = code;
+  }
+}
+
+export class ValidationError extends RrError {
+  constructor(message) {
+    super(message, 'VALIDATION_ERROR');
+    this.name = 'ValidationError';
+  }
+}
+
+export class GitHubApiError extends RrError {
+  constructor(message) {
+    super(message, 'GITHUB_API_ERROR');
+    this.name = 'GitHubApiError';
+  }
+}
+
+export const validateConfig = (config) => {
+  if (!config) {
+    throw new ValidationError('Configuration is required');
+  }
+  
+  const required = ['org', 'repo'];
+  const missing = required.filter(key => !config[key]);
+  
+  if (missing.length > 0) {
+    throw new ValidationError(`Missing required config fields: ${missing.join(', ')}`);
+  }
+  
+  return {
+    org: config.org,
+    repo: config.repo,
+    releaseLimit: config.releaseLimit ?? DEFAULT_RELEASE_LIMIT
+  };
+};
+
+export const requireParameter = (param, commandName) => {
+  if (!param) {
+    throw new ValidationError(
+      `Missing required parameter for '${commandName}' command\n\n` +
+      `Usage: rr ${commandName} <parameter>`
+    );
+  }
+};
+
+export const validateReleases = (releases) => {
+  if (!releases || releases.length === 0) {
+    console.log(chalk.yellow('\nNo releases found'));
+    console.log(chalk.dim('Tips:'));
+    console.log(chalk.dim('  • Check your org/repo configuration'));
+    console.log(chalk.dim('  • Increase limit: export RR_LIMIT=500'));
+    console.log(chalk.dim('  • Verify the repository has releases\n'));
+    throw new GitHubApiError('No releases found');
+  }
+  return releases;
+};
+