projkit

Git commit workflow CLI for Node.js projects.

Features

• Commit message template with conventional format
• Auto-detect package scope from staged files (monorepo support)
• Auto-extract issue number from branch name
• Version management with package@version tags
• Release Please setup for automated changelog generation
• Multi-language support (English, Korean)
• Custom template path support

Installation

npm install -D projkit
# or
pnpm add -D projkit
# or
yarn add -D projkit

Installation automatically configures:

• Git commit template
• Git hooks (prepare-commit-msg)
• Default editor settings

Note: Interactive prompts are skipped during install to avoid blocking CI/CD. Run npx projkit --setup to customize settings.

Commands

npx projkit [command] [options]

| Command | Description | |---------|-------------| | (default) | Run setup (non-interactive) | | --setup | Run interactive setup | | version <type> | Bump version and create git tag | | doctor | Check project configuration status | | guide [topic] | Show workflow guides | | help | Show help message |

Options

| Option | Description | |--------|-------------| | -y, --non-interactive | Skip all prompts, use defaults |

Usage

Setup

# Interactive setup
npx projkit --setup

# Quick setup with defaults
npx projkit -y

Configurable options:

1. Git editor (VS Code, Cursor, Nano, Vim)
2. Language (English, Korean)
3. Commit template (default or custom path)
4. Release Please (auto changelog & release)

Version Management

Bump package version with automatic git tag in package@version format.

cd src/packages/my-package
npx projkit version <type>

| Type | Example | |------|---------| | patch | 0.0.1 → 0.0.2 | | minor | 0.0.1 → 0.1.0 | | major | 0.0.1 → 1.0.0 | | x.y.z | Set specific version |

$ npx projkit version patch

Bumping my-package: 0.0.1 → 0.0.2
  ✓ Updated package.json
  ✓ Created commit: chore(my-package): release 0.0.2
  ✓ Created tag: [email protected]

To push changes:
  git push && git push origin [email protected]

Doctor (Configuration Check)

Check if your project is properly configured.

npx projkit doctor

Checks:

| Check | Description | |-------|-------------| | Git Hook | Is projkit hook configured? | | Commit Template | Is commit template set? | | Release Please | Is release-please configured? (optional) | | Version Sync | Are manifest and package.json versions in sync? |

Example output:

🔍 Checking project...

✅ Git Hook is configured correctly.
✅ Commit template is configured.
✅ Release Please is configured.
✅ Versions are in sync. (.)

💡 Tips:
⚠️  Do not change version manually when publishing!
   Use the version managed by release-please as-is.
📖 More info: npx projkit guide publish

✨ All settings are correct!

Guide (Workflow Documentation)

Show workflow guides for common tasks.

npx projkit guide [topic]

Available topics:

| Topic | Description | |-------|-------------| | publish | How to publish without breaking version sync | | release-please | How release-please workflow works | | commit | Commit message format guide |

Example:

# Show available topics
npx projkit guide

# Show publish workflow guide
npx projkit guide publish

# Show release-please guide
npx projkit guide release-please

# Show commit format guide
npx projkit guide commit

Publish workflow guide preview:

📦 Publish Workflow Guide

❌ Wrong way:
  ┌─────────────────────────────────────────────┐
  │ 1. feat commit → merge to main              │
  │ 2. npm version patch  ← manual version      │
  │ 3. npm publish                              │
  │ → Out of sync with release-please!          │
  └─────────────────────────────────────────────┘

✅ Correct way:
  ┌─────────────────────────────────────────────┐
  │ 1. feat commit → merge to main              │
  │ 2. Merge release-please PR  ← auto version  │
  │ 3. npm publish (no version change)          │
  │ → Stays in sync!                            │
  └─────────────────────────────────────────────┘

💡 Key: Don't touch version during publish, it stays in sync.

Release Please Setup

Set up automated changelog generation and release management with release-please.

npx projkit --setup
# At step [7/7], select "Yes" for Release Please setup

What Gets Created

| File | Description | |------|-------------| | .github/workflows/release-please.yml | GitHub Action workflow | | release-please-config.json | Release configuration | | .release-please-manifest.json | Version manifest |

Workflow Scenario

┌─────────────────────────────────────────────────────────────────┐
│  1. DEVELOP                                                      │
│     Write code and commit with conventional format              │
│     $ git commit -m "feat(auth): add OAuth login"               │
│     $ git commit -m "fix(core): resolve memory leak"            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  2. MERGE TO MAIN                                                │
│     Create PR and merge to main branch                          │
│     Release Please Action triggers automatically                │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  3. RELEASE PR (Auto-generated)                                  │
│     Release Please creates/updates a Release PR:                │
│     - Version bump in package.json                              │
│     - CHANGELOG.md updated with all changes                     │
│     - PR title: "chore(main): release my-package 1.2.0"         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  4. REVIEW & EDIT (Optional)                                     │
│     - Review the generated CHANGELOG.md                         │
│     - Edit descriptions if needed                               │
│     - Add additional notes                                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  5. MERGE RELEASE PR                                             │
│     When ready, merge the Release PR:                           │
│     - GitHub Release created automatically                      │
│     - Git tag created (e.g., v1.2.0)                            │
│     - npm publish triggered (if configured)                     │
└─────────────────────────────────────────────────────────────────┘

Generated CHANGELOG Example

# Changelog

## [1.2.0](https://github.com/org/repo/compare/v1.1.0...v1.2.0) (2024-01-15)

### Features

* **auth:** add OAuth login support ([#42](https://github.com/org/repo/issues/42))
* **api:** implement rate limiting ([#45](https://github.com/org/repo/issues/45))

### Bug Fixes

* **core:** resolve memory leak in cache ([#43](https://github.com/org/repo/issues/43))
* **ui:** fix button alignment ([#44](https://github.com/org/repo/issues/44))

Version Bump Rules

| Commit Prefix | Version Bump | Example | |---------------|--------------|---------| | fix: | Patch | 1.0.0 → 1.0.1 | | feat: | Minor | 1.0.0 → 1.1.0 | | feat!: or BREAKING CHANGE: | Major | 1.0.0 → 2.0.0 |

Monorepo Support

For monorepo projects, projkit automatically:

• Detects pnpm-workspace.yaml, lerna.json, or workspaces in package.json
• Finds packages in packages/, src/packages/, apps/, libs/
• Generates separate changelog for each package

# Generated release-please-config.json for monorepo
{
  "packages": {
    "src/packages/auth": { "package-name": "@myorg/auth", ... },
    "src/packages/core": { "package-name": "@myorg/core", ... }
  }
}

Manual Changelog Edit

You can always edit CHANGELOG.md manually:

1. Before merging Release PR: Edit directly in the PR
2. After release: Edit CHANGELOG.md and commit normally
3. Custom sections: Add sections like "Migration Guide", "Known Issues"

Commit Workflow

Standard commit (with template)

git commit

Opens your editor with the commit template.

Quick commit

git commit -m "feat: your message"

You'll be prompted:

• y) Proceed as-is
• t) Open template editor
• c) Cancel

Auto Features (Monorepo)

Package Scope Detection

Automatically detects changed packages from src/packages/*/:

# Files in src/packages/auth/ staged
git commit -m "feat: add login"
# → feat(auth): add login

# Multiple packages
# → feat(auth, core): add login

Issue Number Extraction

Extracts issue number from branch name:

# Branch: feature/123-add-login
git commit -m "feat: add login"

# Result:
# feat: add login
#
# Closes #123

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

| Type | Description | |------|-------------| | feat | New feature | | fix | Bug fix | | docs | Documentation | | style | Formatting (no logic change) | | refactor | Code refactoring | | perf | Performance improvement | | test | Tests | | build | Build system | | deps | Dependencies | | ci | CI configuration | | chore | Other changes | | revert | Revert commit |

Example

feat(auth): add OAuth2 login support

- Add Google OAuth2 provider
- Add callback handler for OAuth flow
- Store refresh token securely

Closes #42

Configuration

After setup, .commitrc.js is generated:

export default {
  language: 'en',
  editor: 'code --wait',
  templatePath: './node_modules/projkit/templates/commit-template.en.txt',
  hooksPath: './node_modules/projkit/hooks',
}

Custom Template

npx projkit --setup
# Select "Use custom template path"
# Enter: ./my-commit-template.txt

Development

# Enable corepack (once per machine, enforces pnpm version)
corepack enable

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode (build)
pnpm dev

# Type check
pnpm typecheck

# Run tests
pnpm test

# Watch mode (test)
pnpm test:watch

Scripts

| Script | Description | |--------|-------------| | pnpm build | Build TypeScript | | pnpm dev | Build in watch mode | | pnpm typecheck | Type check | | pnpm test | Run tests | | pnpm test:watch | Run tests in watch mode | | prepublishOnly | Build + test before publish |

CI/CD

GitHub Actions runs tests on:

• Push to main (projkit changes)
• Pull requests to main (projkit changes)

Test matrix: Node.js 18, 20, 22

Release Workflow

This project uses release-please for automated versioning and changelog generation.

How it works

1. Develop: Create commits with Conventional Commits format

   git commit -m "feat(projkit): add new feature"
   git commit -m "fix(projkit): resolve bug"

2. Auto Release PR: When commits are merged to main, release-please automatically creates/updates a Release PR with:

   • Version bump in package.json
   • Generated CHANGELOG.md

3. Release: When ready, merge the Release PR

   • GitHub Release is created automatically
   • npm publish is triggered automatically

Version Bump Rules

| Commit Type | Version Bump | Example | |-------------|--------------|---------| | fix: | patch | 1.0.0 → 1.0.1 | | feat: | minor | 1.0.0 → 1.1.0 | | feat!: or BREAKING CHANGE: | major | 1.0.0 → 2.0.0 |

Manual Publish (Optional)

For manual publishing (e.g., dry run testing):

1. Go to Actions → Projkit Publish
2. Click Run workflow
3. Enable Dry run to test without publishing
4. Click Run workflow

Note: Uses npm Trusted Publisher (OIDC). No token required.

Requirements

• Node.js >= 18.0.0
• Git
• Bash (macOS, Linux, Windows with Git Bash/WSL)

License

MIT