contribute-now 0.1.2 → 0.2.0-dev.0de9dbd
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +162 -133
- package/dist/index.js +2599 -885
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,56 +1,56 @@
|
|
|
1
1
|
# contribute-now
|
|
2
2
|
|
|
3
|
-
|
|
4
4
|
<!-- Created with GitHub Repo Banner by Waren Gonzaga: https://ghrb.waren.build -->
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
**contribute-now** is a developer CLI that automates git workflows — branching, syncing, staging, committing, and opening PRs — so you can focus on shipping, not on memorizing git commands.
|
|
7
|
+
|
|
8
|
+
It natively supports multiple workflow models and commit conventions, with AI-powered assistance throughout.
|
|
7
9
|
|
|
8
10
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
|
9
11
|
[](https://www.npmjs.com/package/contribute-now)
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Workflow Modes
|
|
12
16
|
|
|
13
|
-
|
|
17
|
+
Pick the model that matches your project during `contrib setup`. contribute-now adapts its commands to your chosen workflow automatically — no manual branch names to remember.
|
|
14
18
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
19
|
+
| Mode | Branches | Strategy | Default |
|
|
20
|
+
|------|----------|----------|:-------:|
|
|
21
|
+
| 🌊 **Clean Flow** *(by WGTech Labs)* | `main` + `dev` + feature branches | Squash features → `dev`, merge `dev` → `main` | ✅ |
|
|
22
|
+
| 🐙 **GitHub Flow** | `main` + feature branches | Squash/merge features → `main` | |
|
|
23
|
+
| 🔀 **Git Flow** | `main` + `develop` + release/hotfix branches | Full ceremony branching | |
|
|
18
24
|
|
|
19
|
-
|
|
25
|
+
## Commit Conventions
|
|
20
26
|
|
|
21
|
-
|
|
27
|
+
contribute-now validates commit messages and guides your AI toward the right format — based on whichever convention you configure.
|
|
22
28
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
- ⚙️ **`contrib setup`** — Auto-detects your role (maintainer/contributor) and writes `.contributerc.json`
|
|
31
|
-
- 🤖 **AI-powered** — All AI features degrade gracefully if GitHub Copilot is unavailable
|
|
32
|
-
- 🎨 **ASCII Banner** — Beautiful ANSI Shadow figlet banner
|
|
29
|
+
| Convention | Format | Default |
|
|
30
|
+
|------------|--------|:-------:|
|
|
31
|
+
| 🧹 **Clean Commit** *(by WGTech Labs)* | `<emoji> <type>[!][(<scope>)]: <description>` | ✅ |
|
|
32
|
+
| 📝 **Conventional Commits** | `<type>[!][(<scope>)]: <description>` | |
|
|
33
|
+
| 🚫 **None** | No enforcement | |
|
|
34
|
+
|
|
35
|
+
---
|
|
33
36
|
|
|
34
37
|
## Quick Start
|
|
35
38
|
|
|
36
39
|
```bash
|
|
37
|
-
# Using npx
|
|
38
40
|
npx contribute-now setup
|
|
39
|
-
|
|
40
|
-
# Using bunx
|
|
41
|
-
bunx contribute-now setup
|
|
42
41
|
```
|
|
43
42
|
|
|
44
43
|
Or install globally:
|
|
45
44
|
|
|
46
45
|
```bash
|
|
47
46
|
npm install -g contribute-now
|
|
48
|
-
# then use:
|
|
49
47
|
contrib setup
|
|
50
|
-
# or:
|
|
51
|
-
contribute setup
|
|
52
48
|
```
|
|
53
49
|
|
|
50
|
+
> Both `contrib` and `contribute` invoke the same binary.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
54
|
## Installation
|
|
55
55
|
|
|
56
56
|
```bash
|
|
@@ -61,192 +61,173 @@ npm install -g contribute-now
|
|
|
61
61
|
bun install -g contribute-now
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
-
Both `contrib` and `contribute` invoke the same binary.
|
|
65
|
-
|
|
66
64
|
## Prerequisites
|
|
67
65
|
|
|
68
|
-
- [Git](https://git-scm.com/)
|
|
69
|
-
- [GitHub CLI](https://cli.github.com) (`gh`) — optional
|
|
70
|
-
- [GitHub Copilot](https://github.com/features/copilot)
|
|
66
|
+
- **[Git](https://git-scm.com/)** — required
|
|
67
|
+
- **[GitHub CLI](https://cli.github.com)** (`gh`) — optional; enables role auto-detection and PR creation
|
|
68
|
+
- **[GitHub Copilot](https://github.com/features/copilot)** — optional; enables AI features
|
|
69
|
+
|
|
70
|
+
---
|
|
71
71
|
|
|
72
|
-
##
|
|
72
|
+
## Commands
|
|
73
73
|
|
|
74
|
-
###
|
|
74
|
+
### `contrib setup`
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
Interactive setup wizard. Configures your repo's workflow mode, commit convention, your role, and branch/remote names. Writes `.contributerc.json`.
|
|
77
77
|
|
|
78
78
|
```bash
|
|
79
79
|
contrib setup
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
|
|
83
|
-
1.
|
|
84
|
-
2.
|
|
85
|
-
3.
|
|
86
|
-
4.
|
|
82
|
+
Steps:
|
|
83
|
+
1. Choose **workflow mode** — Clean Flow, GitHub Flow, or Git Flow
|
|
84
|
+
2. Choose **commit convention** — Clean Commit, Conventional Commits, or None
|
|
85
|
+
3. Detect remotes and auto-detect your **role** (maintainer or contributor)
|
|
86
|
+
4. Confirm branch and remote names
|
|
87
|
+
5. Write `.contributerc.json`
|
|
88
|
+
|
|
89
|
+
---
|
|
87
90
|
|
|
88
|
-
###
|
|
91
|
+
### `contrib sync`
|
|
89
92
|
|
|
90
|
-
|
|
93
|
+
Pull the latest changes from the correct remote branch based on your workflow and role.
|
|
91
94
|
|
|
92
95
|
```bash
|
|
93
|
-
contrib sync #
|
|
96
|
+
contrib sync # with confirmation
|
|
94
97
|
contrib sync --yes # skip confirmation
|
|
95
98
|
```
|
|
96
99
|
|
|
97
|
-
|
|
98
|
-
|
|
100
|
+
| Role | Clean Flow / Git Flow | GitHub Flow |
|
|
101
|
+
|------|-----------------------|-------------|
|
|
102
|
+
| Maintainer | pulls `origin/dev` | pulls `origin/main` |
|
|
103
|
+
| Contributor | pulls `upstream/dev` | pulls `upstream/main` |
|
|
99
104
|
|
|
100
|
-
|
|
105
|
+
---
|
|
101
106
|
|
|
102
|
-
###
|
|
107
|
+
### `contrib start`
|
|
103
108
|
|
|
104
|
-
Create a new feature branch from the
|
|
109
|
+
Create a new feature branch from the correct base branch, with optional AI-powered branch naming.
|
|
105
110
|
|
|
106
111
|
```bash
|
|
112
|
+
# Direct branch name
|
|
107
113
|
contrib start feature/user-auth
|
|
108
|
-
contrib start fix/login-timeout
|
|
109
114
|
|
|
110
|
-
# Natural language — AI suggests
|
|
111
|
-
contrib start "
|
|
115
|
+
# Natural language — AI suggests the branch name
|
|
116
|
+
contrib start "add user authentication"
|
|
112
117
|
|
|
113
|
-
# Skip AI
|
|
114
|
-
contrib start "
|
|
118
|
+
# Skip AI
|
|
119
|
+
contrib start "add user authentication" --no-ai
|
|
115
120
|
```
|
|
116
121
|
|
|
117
|
-
|
|
122
|
+
---
|
|
118
123
|
|
|
119
|
-
|
|
124
|
+
### `contrib commit`
|
|
120
125
|
|
|
121
|
-
|
|
122
|
-
contrib commit
|
|
126
|
+
Stage your changes and create a validated, AI-generated commit message matching your configured convention.
|
|
123
127
|
|
|
124
|
-
|
|
125
|
-
contrib commit
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
contrib commit --no-ai
|
|
128
|
+
```bash
|
|
129
|
+
contrib commit # AI-generated message
|
|
130
|
+
contrib commit --no-ai # manual entry, still validated
|
|
131
|
+
contrib commit --model gpt-4.1 # specific AI model
|
|
129
132
|
```
|
|
130
133
|
|
|
131
|
-
|
|
132
|
-
```
|
|
133
|
-
🔧 update (auth): fix login timeout handling
|
|
134
|
-
```
|
|
134
|
+
After the AI generates a message, you can **accept**, **edit**, **regenerate**, or **write manually**. Messages are always validated against your convention — with a soft warning if they don't match (you can still commit).
|
|
135
135
|
|
|
136
|
-
|
|
136
|
+
---
|
|
137
137
|
|
|
138
|
-
###
|
|
138
|
+
### `contrib update`
|
|
139
139
|
|
|
140
|
-
Rebase your current branch onto the latest
|
|
140
|
+
Rebase your current branch onto the latest base branch, with AI guidance if conflicts occur.
|
|
141
141
|
|
|
142
142
|
```bash
|
|
143
143
|
contrib update
|
|
144
|
-
|
|
145
|
-
# Skip AI conflict suggestions
|
|
146
|
-
contrib update --no-ai
|
|
144
|
+
contrib update --no-ai # skip AI conflict guidance
|
|
147
145
|
```
|
|
148
146
|
|
|
149
|
-
|
|
147
|
+
---
|
|
150
148
|
|
|
151
|
-
###
|
|
149
|
+
### `contrib submit`
|
|
152
150
|
|
|
153
|
-
Push your branch and open a pull request
|
|
151
|
+
Push your branch and open a pull request with an AI-generated title and description.
|
|
154
152
|
|
|
155
153
|
```bash
|
|
156
154
|
contrib submit
|
|
157
155
|
contrib submit --draft
|
|
158
|
-
contrib submit --no-ai
|
|
156
|
+
contrib submit --no-ai
|
|
159
157
|
contrib submit --model gpt-4.1
|
|
160
158
|
```
|
|
161
159
|
|
|
162
|
-
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
### `contrib clean`
|
|
163
163
|
|
|
164
|
-
Delete merged branches and prune remote refs
|
|
164
|
+
Delete merged branches and prune stale remote refs.
|
|
165
165
|
|
|
166
166
|
```bash
|
|
167
|
-
contrib clean
|
|
168
|
-
contrib clean --yes
|
|
167
|
+
contrib clean # shows candidates, asks to confirm
|
|
168
|
+
contrib clean --yes # skip confirmation
|
|
169
169
|
```
|
|
170
170
|
|
|
171
|
-
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
### `contrib status`
|
|
172
174
|
|
|
173
|
-
|
|
175
|
+
Show a sync status dashboard for your main, dev, and current branch.
|
|
174
176
|
|
|
175
177
|
```bash
|
|
176
178
|
contrib status
|
|
177
179
|
```
|
|
178
180
|
|
|
179
|
-
|
|
180
|
-
```
|
|
181
|
-
main ✓ in sync with origin/main
|
|
182
|
-
dev ↑ 3 commits ahead of origin/main (needs sync!)
|
|
183
|
-
feature/user-auth ↑ 2 ahead, 0 behind dev (current *)
|
|
184
|
-
```
|
|
181
|
+
---
|
|
185
182
|
|
|
186
|
-
|
|
183
|
+
### `contrib hook`
|
|
187
184
|
|
|
188
|
-
|
|
185
|
+
Install or uninstall a `commit-msg` git hook that validates every commit against your configured convention — no Husky or lint-staged needed.
|
|
189
186
|
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
"mainBranch": "main",
|
|
194
|
-
"devBranch": "dev",
|
|
195
|
-
"upstream": "upstream",
|
|
196
|
-
"origin": "origin",
|
|
197
|
-
"branchPrefixes": ["feature", "fix", "docs", "chore", "test", "refactor"]
|
|
198
|
-
}
|
|
187
|
+
```bash
|
|
188
|
+
contrib hook install # writes .git/hooks/commit-msg
|
|
189
|
+
contrib hook uninstall # removes it
|
|
199
190
|
```
|
|
200
191
|
|
|
201
|
-
|
|
192
|
+
- Automatically skips merge commits, fixup, squash, and amend commits
|
|
193
|
+
- Won't overwrite hooks it didn't create
|
|
202
194
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
```
|
|
206
|
-
contrib — Git workflow CLI for squash-merge two-branch models
|
|
207
|
-
|
|
208
|
-
USAGE
|
|
209
|
-
contrib [OPTIONS] setup|sync|start|commit|update|submit|clean|status
|
|
195
|
+
---
|
|
210
196
|
|
|
211
|
-
|
|
212
|
-
-v, --version Show version number
|
|
197
|
+
### `contrib validate`
|
|
213
198
|
|
|
214
|
-
|
|
215
|
-
setup Initialize config for this repo (.contributerc.json)
|
|
216
|
-
sync Reset dev branch to match origin/main or upstream/dev
|
|
217
|
-
start Create a new feature branch from the latest dev
|
|
218
|
-
commit Stage changes and create a Clean Commit message (AI-powered)
|
|
219
|
-
update Rebase current branch onto latest dev
|
|
220
|
-
submit Push current branch and create a pull request
|
|
221
|
-
clean Delete merged branches and prune remote refs
|
|
222
|
-
status Show sync status of main, dev, and current branch
|
|
199
|
+
Validate a commit message against your configured convention. Exits `0` if valid, `1` if not — useful in CI pipelines or custom hooks.
|
|
223
200
|
|
|
224
|
-
|
|
201
|
+
```bash
|
|
202
|
+
contrib validate "📦 new: user auth module" # exit 0
|
|
203
|
+
contrib validate "added stuff" # exit 1
|
|
225
204
|
```
|
|
226
205
|
|
|
206
|
+
---
|
|
207
|
+
|
|
227
208
|
## AI Features
|
|
228
209
|
|
|
229
|
-
All AI features
|
|
210
|
+
All AI features are powered by **GitHub Copilot** via `@github/copilot-sdk` and are entirely **optional** — every command has a manual fallback.
|
|
230
211
|
|
|
231
212
|
| Command | AI Feature | Fallback |
|
|
232
|
-
|
|
233
|
-
| `commit` | Generate
|
|
234
|
-
| `start` | Suggest branch name from natural language | Prefix picker + manual
|
|
235
|
-
| `update` | Conflict resolution guidance | Standard
|
|
236
|
-
| `submit` | Generate PR title
|
|
213
|
+
|---------|------------|---------|
|
|
214
|
+
| `commit` | Generate commit message from staged diff | Type manually |
|
|
215
|
+
| `start` | Suggest branch name from natural language | Prefix picker + manual |
|
|
216
|
+
| `update` | Conflict resolution guidance | Standard git instructions |
|
|
217
|
+
| `submit` | Generate PR title and body | `gh pr create --fill` or manual |
|
|
237
218
|
|
|
238
|
-
|
|
219
|
+
Pass `--no-ai` to any command to skip AI entirely. Use `--model <name>` to select a specific Copilot model (e.g., `gpt-4.1`, `claude-sonnet-4`).
|
|
239
220
|
|
|
240
|
-
|
|
221
|
+
---
|
|
241
222
|
|
|
242
|
-
|
|
223
|
+
## Commit Convention Reference
|
|
243
224
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
225
|
+
### Clean Commit *(default)*
|
|
226
|
+
|
|
227
|
+
Format: `<emoji> <type>[!][(<scope>)]: <description>`
|
|
247
228
|
|
|
248
|
-
| Emoji | Type |
|
|
249
|
-
|
|
229
|
+
| Emoji | Type | When to use |
|
|
230
|
+
|:-----:|------|-------------|
|
|
250
231
|
| 📦 | `new` | New features, files, or capabilities |
|
|
251
232
|
| 🔧 | `update` | Changes, refactoring, improvements |
|
|
252
233
|
| 🗑️ | `remove` | Removing code, files, or dependencies |
|
|
@@ -257,7 +238,54 @@ This project uses the **[Clean Commit](https://github.com/wgtechlabs/clean-commi
|
|
|
257
238
|
| 📖 | `docs` | Documentation changes |
|
|
258
239
|
| 🚀 | `release` | Version releases |
|
|
259
240
|
|
|
260
|
-
|
|
241
|
+
Examples:
|
|
242
|
+
```
|
|
243
|
+
📦 new: user authentication system
|
|
244
|
+
🔧 update (api): improve error handling
|
|
245
|
+
⚙️ setup (ci): configure github actions
|
|
246
|
+
🔧 update!: breaking change to config format
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
→ [Clean Commit spec](https://github.com/wgtechlabs/clean-commit)
|
|
250
|
+
|
|
251
|
+
### Conventional Commits
|
|
252
|
+
|
|
253
|
+
Format: `<type>[!][(<scope>)]: <description>`
|
|
254
|
+
|
|
255
|
+
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
|
|
256
|
+
|
|
257
|
+
Examples:
|
|
258
|
+
```
|
|
259
|
+
feat: add user authentication
|
|
260
|
+
fix(auth): resolve token expiry issue
|
|
261
|
+
docs: update contributing guide
|
|
262
|
+
feat!: redesign authentication API
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
→ [conventionalcommits.org](https://www.conventionalcommits.org/)
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## Config File
|
|
270
|
+
|
|
271
|
+
`contrib setup` writes `.contributerc.json` to your repo root:
|
|
272
|
+
|
|
273
|
+
```json
|
|
274
|
+
{
|
|
275
|
+
"workflow": "clean-flow",
|
|
276
|
+
"commitConvention": "clean-commit",
|
|
277
|
+
"role": "contributor",
|
|
278
|
+
"mainBranch": "main",
|
|
279
|
+
"devBranch": "dev",
|
|
280
|
+
"upstream": "upstream",
|
|
281
|
+
"origin": "origin",
|
|
282
|
+
"branchPrefixes": ["feature", "fix", "docs", "chore", "test", "refactor"]
|
|
283
|
+
}
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
> Add `.contributerc.json` to your `.gitignore` — it contains personal config and should not be committed.
|
|
287
|
+
|
|
288
|
+
---
|
|
261
289
|
|
|
262
290
|
## Development
|
|
263
291
|
|
|
@@ -282,3 +310,4 @@ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the workfl
|
|
|
282
310
|
---
|
|
283
311
|
|
|
284
312
|
💻💖☕ Made with ❤️ by [Waren Gonzaga](https://github.com/warengonzaga)
|
|
313
|
+
|