---
root: true
targets: ["*"]
description: "Project overview and general development guidelines"
globs: ["**/*"]
---

# bulk-private - GitHub Repository Bulk Privacy Tool

## Project Overview

`bulk-private` is a CLI tool for bulk converting GitHub public repositories to private. It specifically detects repositories with 0 stars and forks that have been inactive for more than a year, and efficiently converts them to private.

## Technology Stack

- **Runtime**: Node.js 24
- **Package Manager**: pnpm
- **Language**: TypeScript
- **CLI Framework**: Ink (React for CLIs)
- **Build Tool**: tsup
- **Testing**: Vitest
- **Code Quality**:
  - Formatter: Biome
  - Linters: Oxlint + ESLint
  - Type Checking: TypeScript
  - Security: secretlint
  - Spell Checker: cspell

## Key Features

1. **Automatic Repository Detection**: Automatically identifies inactive repositories from public ones
2. **Filtering**: Filters repositories with 0 stars/forks and no updates for over a year
3. **Interactive UI**: Rich CLI interface using Ink
4. **Dry Run Mode**: Preview changes before actual execution
5. **Progress Display**: Real-time processing progress indication

## Architecture

### Component Structure

- **`src/index.tsx`**: Entry point, CLI configuration with Commander.js
- **`src/components/App.tsx`**: Main application logic
- **`src/components/RepoList.tsx`**: Repository list display component
- **`src/components/Confirm.tsx`**: Confirmation dialog component
- **`src/lib/github.ts`**: GitHub API operations class
- **`src/lib/filters.ts`**: Repository filtering logic
- **`src/types/index.ts`**: Type definitions

### Data Flow

1. Parse CLI arguments and options
2. Retrieve authenticated user information using GitHub API
3. Fetch all public repositories
4. Filter inactive repositories
5. Interactive confirmation process
6. Batch execution of privatization

## Development Guidelines

### Coding Conventions

- Use strict TypeScript type checking
- Follow React component design patterns
- Use async/await for asynchronous operations
- Implement proper error handling

### Quality Checks

- `pnpm check`: Execute formatting, linting, and type checking
- `pnpm test`: Run test suite
- Automatic quality checks via Git pre-commit hooks

### Security Considerations

- Proper management of GitHub Personal Access Tokens
- Detection of sensitive information using secretlint
- API scope configuration based on principle of least privilege

## Usage

```bash
# Installation
pnpm install

# Development mode
pnpm dev

# Build
pnpm build

# Example execution
node dist/index.js --token YOUR_GITHUB_TOKEN --dry-run
```

## Important Notes

- Be aware of GitHub API rate limits
- Privatization is an irreversible operation
- Recommend pre-confirmation using dry-run mode
- Proper GitHub Personal Access Token setup required (`repo` scope)