github-labels-template 0.1.0-staging.6ad2532

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.
Files changed (3) hide show
  1. package/README.md +179 -0
  2. package/dist/index.js +336 -0
  3. package/package.json +40 -0
package/README.md ADDED
@@ -0,0 +1,179 @@
1
+ # GitHub Labels Template
2
+
3
+ ![GitHub Repo Banner](https://ghrb.waren.build/banner?header=GitHub+Labels+Template+%F0%9F%8F%B7%EF%B8%8F&subheader=A+curated+set+of+GitHub+labels+for+any+project+%E2%80%94+CLI-ready.&bg=013B84-016EEA&color=FFFFFF&headerfont=Google+Sans+Code&subheaderfont=Sour+Gummy&support=true)
4
+ <!-- Created with GitHub Repo Banner by Waren Gonzaga: https://ghrb.waren.build -->
5
+
6
+ A CLI tool to apply a curated set of GitHub labels to any repository using `gh` CLI.
7
+
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
+ [![npm version](https://img.shields.io/npm/v/github-labels-template.svg)](https://www.npmjs.com/package/github-labels-template)
10
+
11
+ ## Features
12
+
13
+ - ๐Ÿท๏ธ **20 Curated Labels**: Organized across 5 categories โ€” type, status, community, resolution, and area
14
+ - ๐Ÿš€ **One Command Setup**: Apply all labels to any repo with `ghlt apply`
15
+ - ๐Ÿ” **Auto-Detect Repo**: Automatically detects the current repository from git remote
16
+ - ๐Ÿ”„ **Smart Conflict Handling**: Skips existing labels by default, `--force` to update
17
+ - ๐Ÿงน **Wipe Command**: Remove all existing labels with a confirmation prompt
18
+ - โœ… **Pre-Flight Checks**: Validates `gh` CLI is installed and authenticated before doing anything
19
+ - ๐Ÿ“Š **Clear Output**: Color-coded status for each label with a summary report
20
+ - ๐ŸŒ **Dual Runtime**: Works with both `npx` and `bunx`
21
+
22
+ ## Quick Start
23
+
24
+ ```bash
25
+ # Using npx
26
+ npx github-labels-template apply
27
+
28
+ # Using bunx
29
+ bunx github-labels-template apply
30
+ ```
31
+
32
+ That's it. All 20 labels are applied to the current repo.
33
+
34
+ ## Installation
35
+
36
+ ```bash
37
+ # Global install (npm)
38
+ npm install -g github-labels-template
39
+
40
+ # Global install (bun)
41
+ bun install -g github-labels-template
42
+
43
+ # Then use anywhere
44
+ ghlt apply
45
+ ```
46
+
47
+ ## Prerequisites
48
+
49
+ - [GitHub CLI](https://cli.github.com) (`gh`) installed and authenticated
50
+
51
+ ## Usage
52
+
53
+ ### Apply Labels
54
+
55
+ ```bash
56
+ # Apply to the current repo (auto-detected from git remote)
57
+ ghlt apply
58
+
59
+ # Apply to a specific repo
60
+ ghlt apply --repo owner/repo
61
+
62
+ # Overwrite existing labels with template values
63
+ ghlt apply --force
64
+ ```
65
+
66
+ ### Wipe Labels
67
+
68
+ ```bash
69
+ # Remove all labels (with confirmation prompt)
70
+ ghlt wipe
71
+
72
+ # Remove all labels from a specific repo
73
+ ghlt wipe --repo owner/repo
74
+
75
+ # Skip confirmation prompt
76
+ ghlt wipe --yes
77
+ ```
78
+
79
+ ### Common Workflows
80
+
81
+ ```bash
82
+ # Clean slate: wipe defaults, then apply template
83
+ ghlt wipe --yes && ghlt apply
84
+
85
+ # Update a specific repo to match the template
86
+ ghlt apply --repo owner/repo --force
87
+ ```
88
+
89
+ ## Label Template
90
+
91
+ ### Type Labels
92
+
93
+ Classify what kind of work this is.
94
+
95
+ | Name | Color | Description |
96
+ |------|-------|-------------|
97
+ | `bug` | ![#d73a4a](https://placehold.co/12x12/d73a4a/d73a4a.png) `d73a4a` | Something isn't working |
98
+ | `enhancement` | ![#1a7f37](https://placehold.co/12x12/1a7f37/1a7f37.png) `1a7f37` | New feature or improvement to existing functionality |
99
+ | `documentation` | ![#0075ca](https://placehold.co/12x12/0075ca/0075ca.png) `0075ca` | Improvements or additions to docs, README, or guides |
100
+ | `refactor` | ![#8957e5](https://placehold.co/12x12/8957e5/8957e5.png) `8957e5` | Code improvement without changing functionality |
101
+ | `performance` | ![#e3795c](https://placehold.co/12x12/e3795c/e3795c.png) `e3795c` | Optimization, speed, or resource usage improvements |
102
+ | `security` | ![#d4a72c](https://placehold.co/12x12/d4a72c/d4a72c.png) `d4a72c` | Security vulnerability or hardening |
103
+
104
+ ### Status Labels
105
+
106
+ Track the current workflow state.
107
+
108
+ | Name | Color | Description |
109
+ |------|-------|-------------|
110
+ | `blocked` | ![#cf222e](https://placehold.co/12x12/cf222e/cf222e.png) `cf222e` | Waiting on another issue, decision, or external factor |
111
+ | `needs triage` | ![#e16f24](https://placehold.co/12x12/e16f24/e16f24.png) `e16f24` | New issue โ€” needs review and categorization |
112
+ | `awaiting response` | ![#1a7ec7](https://placehold.co/12x12/1a7ec7/1a7ec7.png) `1a7ec7` | Waiting for more information from the reporter |
113
+ | `ready` | ![#2da44e](https://placehold.co/12x12/2da44e/2da44e.png) `2da44e` | Triaged and ready to be picked up |
114
+
115
+ ### Community Labels
116
+
117
+ Signals for open source contributors.
118
+
119
+ | Name | Color | Description |
120
+ |------|-------|-------------|
121
+ | `good first issue` | ![#7057ff](https://placehold.co/12x12/7057ff/7057ff.png) `7057ff` | Good for newcomers โ€” well-scoped and documented |
122
+ | `help wanted` | ![#0e8a16](https://placehold.co/12x12/0e8a16/0e8a16.png) `0e8a16` | Open for community contribution |
123
+
124
+ ### Resolution Labels
125
+
126
+ Why an issue or PR was closed.
127
+
128
+ | Name | Color | Description |
129
+ |------|-------|-------------|
130
+ | `duplicate` | ![#cfd3d7](https://placehold.co/12x12/cfd3d7/cfd3d7.png) `cfd3d7` | This issue or pull request already exists |
131
+ | `invalid` | ![#cfd3d7](https://placehold.co/12x12/cfd3d7/cfd3d7.png) `cfd3d7` | This doesn't seem right |
132
+ | `wontfix` | ![#cfd3d7](https://placehold.co/12x12/cfd3d7/cfd3d7.png) `cfd3d7` | This will not be worked on |
133
+
134
+ ### Area Labels
135
+
136
+ Broad software layers โ€” universal across any project.
137
+
138
+ | Name | Color | Description |
139
+ |------|-------|-------------|
140
+ | `core` | ![#0052cc](https://placehold.co/12x12/0052cc/0052cc.png) `0052cc` | Core logic, business rules, and primary functionality |
141
+ | `interface` | ![#5319e7](https://placehold.co/12x12/5319e7/5319e7.png) `5319e7` | User-facing layer โ€” UI, CLI, API endpoints, or SDK surface |
142
+ | `data` | ![#006b75](https://placehold.co/12x12/006b75/006b75.png) `006b75` | Database, storage, caching, or data models |
143
+ | `infra` | ![#e16f24](https://placehold.co/12x12/e16f24/e16f24.png) `e16f24` | Build system, CI/CD, deployment, config, and DevOps |
144
+ | `testing` | ![#1a7f37](https://placehold.co/12x12/1a7f37/1a7f37.png) `1a7f37` | Unit tests, integration tests, E2E, and test tooling |
145
+
146
+ ## CLI Reference
147
+
148
+ ```
149
+ ghlt โ€” GitHub Labels Template CLI
150
+
151
+ USAGE
152
+ ghlt apply|wipe
153
+
154
+ COMMANDS
155
+ apply Apply labels from the template to a repository
156
+ wipe Remove all existing labels from a repository
157
+
158
+ OPTIONS (apply)
159
+ -r, --repo <owner/repo> Target repository (default: auto-detect)
160
+ -f, --force Overwrite existing labels
161
+
162
+ OPTIONS (wipe)
163
+ -r, --repo <owner/repo> Target repository (default: auto-detect)
164
+ -y, --yes Skip confirmation prompt
165
+ ```
166
+
167
+ ## Contributing
168
+
169
+ Contributions are welcome! This project follows the [Clean Commit](https://github.com/wgtechlabs/clean-commit) convention.
170
+
171
+ ## License
172
+
173
+ This project is licensed under the [MIT License](LICENSE).
174
+
175
+ ## Author
176
+
177
+ **Waren Gonzaga**
178
+
179
+ [![GitHub](https://img.shields.io/badge/GitHub-@warengonzaga-181717?logo=github)](https://github.com/warengonzaga)
package/dist/index.js ADDED
@@ -0,0 +1,336 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/index.ts
4
+ import { defineCommand as defineCommand3, runMain } from "citty";
5
+
6
+ // src/commands/apply.ts
7
+ import { defineCommand } from "citty";
8
+
9
+ // src/utils/gh.ts
10
+ import { execFile } from "node:child_process";
11
+ function run(args) {
12
+ return new Promise((resolve) => {
13
+ execFile("gh", args, (error, stdout, stderr) => {
14
+ resolve({
15
+ exitCode: error ? error.code ?? 1 : 0,
16
+ stdout: stdout ?? ""
17
+ });
18
+ });
19
+ });
20
+ }
21
+ async function checkGhInstalled() {
22
+ try {
23
+ const { exitCode } = await run(["--version"]);
24
+ return exitCode === 0;
25
+ } catch {
26
+ return false;
27
+ }
28
+ }
29
+ async function checkGhAuth() {
30
+ try {
31
+ const { exitCode } = await run(["auth", "status"]);
32
+ return exitCode === 0;
33
+ } catch {
34
+ return false;
35
+ }
36
+ }
37
+ async function detectRepo() {
38
+ try {
39
+ const { exitCode, stdout } = await run([
40
+ "repo",
41
+ "view",
42
+ "--json",
43
+ "nameWithOwner",
44
+ "-q",
45
+ ".nameWithOwner"
46
+ ]);
47
+ if (exitCode !== 0)
48
+ return null;
49
+ const trimmed = stdout.trim();
50
+ return trimmed || null;
51
+ } catch {
52
+ return null;
53
+ }
54
+ }
55
+ async function listLabels(repo) {
56
+ const { exitCode, stdout } = await run([
57
+ "label",
58
+ "list",
59
+ "--repo",
60
+ repo,
61
+ "--json",
62
+ "name",
63
+ "-q",
64
+ ".[].name",
65
+ "--limit",
66
+ "100"
67
+ ]);
68
+ if (exitCode !== 0)
69
+ return [];
70
+ const text = stdout.trim();
71
+ if (!text)
72
+ return [];
73
+ return text.split(`
74
+ `).map((n) => n.trim());
75
+ }
76
+ async function createLabel(repo, label) {
77
+ const { exitCode } = await run([
78
+ "label",
79
+ "create",
80
+ label.name,
81
+ "--repo",
82
+ repo,
83
+ "--color",
84
+ label.color,
85
+ "--description",
86
+ label.description
87
+ ]);
88
+ return exitCode === 0;
89
+ }
90
+ async function editLabel(repo, label) {
91
+ const { exitCode } = await run([
92
+ "label",
93
+ "edit",
94
+ label.name,
95
+ "--repo",
96
+ repo,
97
+ "--color",
98
+ label.color,
99
+ "--description",
100
+ label.description
101
+ ]);
102
+ return exitCode === 0;
103
+ }
104
+ async function deleteLabel(repo, name) {
105
+ const { exitCode } = await run([
106
+ "label",
107
+ "delete",
108
+ name,
109
+ "--repo",
110
+ repo,
111
+ "--yes"
112
+ ]);
113
+ return exitCode === 0;
114
+ }
115
+
116
+ // src/utils/logger.ts
117
+ import pc from "picocolors";
118
+ function success(msg) {
119
+ console.log(pc.green(` โœ“ ${msg}`));
120
+ }
121
+ function error(msg) {
122
+ console.log(pc.red(` โœ— ${msg}`));
123
+ }
124
+ function warn(msg) {
125
+ console.log(pc.yellow(` โš  ${msg}`));
126
+ }
127
+ function info(msg) {
128
+ console.log(pc.cyan(` โ„น ${msg}`));
129
+ }
130
+ function heading(msg) {
131
+ console.log(`
132
+ ${pc.bold(msg)}`);
133
+ }
134
+ function summary(counts) {
135
+ const parts = [];
136
+ if (counts.created)
137
+ parts.push(pc.green(`${counts.created} created`));
138
+ if (counts.updated)
139
+ parts.push(pc.blue(`${counts.updated} updated`));
140
+ if (counts.skipped)
141
+ parts.push(pc.yellow(`${counts.skipped} skipped`));
142
+ if (counts.deleted)
143
+ parts.push(pc.red(`${counts.deleted} deleted`));
144
+ if (counts.failed)
145
+ parts.push(pc.red(pc.bold(`${counts.failed} failed`)));
146
+ console.log(`
147
+ ${pc.bold("Summary:")} ${parts.join(", ")}`);
148
+ }
149
+ // src/labels.json
150
+ var labels_default = {
151
+ type: [
152
+ { name: "bug", color: "d73a4a", description: "[Type] Something isn't working [issues, PRs]" },
153
+ { name: "enhancement", color: "1a7f37", description: "[Type] New feature or improvement to existing functionality [issues, PRs]" },
154
+ { name: "documentation", color: "0075ca", description: "[Type] Improvements or additions to docs, README, or guides [issues, PRs]" },
155
+ { name: "refactor", color: "8957e5", description: "[Type] Code improvement without changing functionality [PRs]" },
156
+ { name: "performance", color: "e3795c", description: "[Type] Optimization, speed, or resource usage improvements [issues, PRs]" },
157
+ { name: "security", color: "d4a72c", description: "[Type] Security vulnerability or hardening [issues, PRs]" }
158
+ ],
159
+ status: [
160
+ { name: "blocked", color: "cf222e", description: "[Status] Waiting on another issue, decision, or external factor [issues]" },
161
+ { name: "needs triage", color: "e16f24", description: "[Status] New issue โ€” needs review and categorization [issues]" },
162
+ { name: "awaiting response", color: "1a7ec7", description: "[Status] Waiting for more information from the reporter [issues]" },
163
+ { name: "ready", color: "2da44e", description: "[Status] Triaged and ready to be picked up [issues]" }
164
+ ],
165
+ community: [
166
+ { name: "good first issue", color: "7057ff", description: "[Community] Good for newcomers โ€” well-scoped and documented [issues]" },
167
+ { name: "help wanted", color: "0e8a16", description: "[Community] Open for community contribution [issues]" }
168
+ ],
169
+ resolution: [
170
+ { name: "duplicate", color: "cfd3d7", description: "[Resolution] This issue or pull request already exists [issues, PRs]" },
171
+ { name: "invalid", color: "cfd3d7", description: "[Resolution] This doesn't seem right [issues, PRs]" },
172
+ { name: "wontfix", color: "cfd3d7", description: "[Resolution] This will not be worked on [issues]" }
173
+ ],
174
+ area: [
175
+ { name: "core", color: "0052cc", description: "[Area] Core logic, business rules, and primary functionality [issues, PRs]" },
176
+ { name: "interface", color: "5319e7", description: "[Area] User-facing layer โ€” UI, CLI, API endpoints, or SDK surface [issues, PRs]" },
177
+ { name: "data", color: "006b75", description: "[Area] Database, storage, caching, or data models [issues, PRs]" },
178
+ { name: "infra", color: "e16f24", description: "[Area] Build system, CI/CD, deployment, config, and DevOps [issues, PRs]" },
179
+ { name: "testing", color: "1a7f37", description: "[Area] Unit tests, integration tests, E2E, and test tooling [issues, PRs]" }
180
+ ]
181
+ };
182
+
183
+ // src/commands/apply.ts
184
+ var apply_default = defineCommand({
185
+ meta: {
186
+ name: "apply",
187
+ description: "Apply labels from the template to a repository"
188
+ },
189
+ args: {
190
+ repo: {
191
+ type: "string",
192
+ alias: "r",
193
+ description: "Target repository (owner/repo). Defaults to current repo."
194
+ },
195
+ force: {
196
+ type: "boolean",
197
+ alias: "f",
198
+ default: false,
199
+ description: "Overwrite existing labels with the same name"
200
+ }
201
+ },
202
+ async run({ args }) {
203
+ if (!await checkGhInstalled()) {
204
+ error("gh CLI is not installed. Install it from https://cli.github.com");
205
+ process.exit(1);
206
+ }
207
+ if (!await checkGhAuth()) {
208
+ error("Not authenticated. Run `gh auth login` first.");
209
+ process.exit(1);
210
+ }
211
+ const repo = args.repo || await detectRepo();
212
+ if (!repo) {
213
+ error("Could not detect repository. Use --repo <owner/repo> or run inside a git repo.");
214
+ process.exit(1);
215
+ }
216
+ info(`Target: ${repo}`);
217
+ const existing = await listLabels(repo);
218
+ const existingSet = new Set(existing.map((n) => n.toLowerCase()));
219
+ const allLabels = Object.entries(labels_default).flatMap(([, categoryLabels]) => categoryLabels);
220
+ const counts = { created: 0, updated: 0, skipped: 0, failed: 0 };
221
+ for (const [category, categoryLabels] of Object.entries(labels_default)) {
222
+ heading(`${category.charAt(0).toUpperCase() + category.slice(1)} Labels`);
223
+ for (const label of categoryLabels) {
224
+ const exists = existingSet.has(label.name.toLowerCase());
225
+ if (exists && args.force) {
226
+ const ok = await editLabel(repo, label);
227
+ if (ok) {
228
+ success(`${label.name} (updated)`);
229
+ counts.updated++;
230
+ } else {
231
+ error(`${label.name} (update failed)`);
232
+ counts.failed++;
233
+ }
234
+ } else if (exists) {
235
+ warn(`${label.name} (already exists, use --force to update)`);
236
+ counts.skipped++;
237
+ } else {
238
+ const ok = await createLabel(repo, label);
239
+ if (ok) {
240
+ success(`${label.name} (created)`);
241
+ counts.created++;
242
+ } else {
243
+ error(`${label.name} (create failed)`);
244
+ counts.failed++;
245
+ }
246
+ }
247
+ }
248
+ }
249
+ summary(counts);
250
+ }
251
+ });
252
+
253
+ // src/commands/wipe.ts
254
+ import { defineCommand as defineCommand2 } from "citty";
255
+ import pc2 from "picocolors";
256
+ var wipe_default = defineCommand2({
257
+ meta: {
258
+ name: "wipe",
259
+ description: "Remove all existing labels from a repository"
260
+ },
261
+ args: {
262
+ repo: {
263
+ type: "string",
264
+ alias: "r",
265
+ description: "Target repository (owner/repo). Defaults to current repo."
266
+ },
267
+ yes: {
268
+ type: "boolean",
269
+ alias: "y",
270
+ default: false,
271
+ description: "Skip confirmation prompt"
272
+ }
273
+ },
274
+ async run({ args }) {
275
+ if (!await checkGhInstalled()) {
276
+ error("gh CLI is not installed. Install it from https://cli.github.com");
277
+ process.exit(1);
278
+ }
279
+ if (!await checkGhAuth()) {
280
+ error("Not authenticated. Run `gh auth login` first.");
281
+ process.exit(1);
282
+ }
283
+ const repo = args.repo || await detectRepo();
284
+ if (!repo) {
285
+ error("Could not detect repository. Use --repo <owner/repo> or run inside a git repo.");
286
+ process.exit(1);
287
+ }
288
+ info(`Target: ${repo}`);
289
+ const existing = await listLabels(repo);
290
+ if (existing.length === 0) {
291
+ info("No labels found. Nothing to wipe.");
292
+ return;
293
+ }
294
+ if (!args.yes) {
295
+ console.log(`
296
+ ${pc2.bold(pc2.red(`This will delete all ${existing.length} labels from ${repo}.`))}`);
297
+ process.stdout.write(`${pc2.dim("Continue? [y/N] ")}`);
298
+ const response = await new Promise((resolve) => {
299
+ process.stdin.setEncoding("utf-8");
300
+ process.stdin.once("data", (data) => resolve(data.toString().trim()));
301
+ process.stdin.resume();
302
+ });
303
+ if (response.toLowerCase() !== "y") {
304
+ info("Aborted.");
305
+ return;
306
+ }
307
+ }
308
+ heading("Deleting Labels");
309
+ const counts = { deleted: 0, failed: 0 };
310
+ for (const name of existing) {
311
+ const ok = await deleteLabel(repo, name);
312
+ if (ok) {
313
+ success(`${name} (deleted)`);
314
+ counts.deleted++;
315
+ } else {
316
+ error(`${name} (delete failed)`);
317
+ counts.failed++;
318
+ }
319
+ }
320
+ summary(counts);
321
+ }
322
+ });
323
+
324
+ // src/index.ts
325
+ var main = defineCommand3({
326
+ meta: {
327
+ name: "ghlt",
328
+ version: "0.1.0",
329
+ description: "GitHub Labels Template โ€” apply a curated set of labels to any repo using gh CLI."
330
+ },
331
+ subCommands: {
332
+ apply: apply_default,
333
+ wipe: wipe_default
334
+ }
335
+ });
336
+ runMain(main);
package/package.json ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "github-labels-template",
3
+ "version": "0.1.0-staging.6ad2532",
4
+ "description": "A CLI tool to apply a curated GitHub labels template to any repository using gh CLI.",
5
+ "type": "module",
6
+ "bin": {
7
+ "ghlt": "dist/index.js"
8
+ },
9
+ "files": [
10
+ "dist"
11
+ ],
12
+ "scripts": {
13
+ "build": "bun build src/index.ts --outfile dist/index.js --target node --packages external",
14
+ "dev": "bun src/index.ts"
15
+ },
16
+ "engines": {
17
+ "node": ">=18",
18
+ "bun": ">=1.0"
19
+ },
20
+ "keywords": [
21
+ "github",
22
+ "labels",
23
+ "template",
24
+ "cli",
25
+ "gh"
26
+ ],
27
+ "author": "Waren Gonzaga",
28
+ "license": "MIT",
29
+ "repository": {
30
+ "type": "git",
31
+ "url": "git+https://github.com/warengonzaga/github-labels-template.git"
32
+ },
33
+ "dependencies": {
34
+ "citty": "^0.1.6",
35
+ "picocolors": "^1.1.1"
36
+ },
37
+ "devDependencies": {
38
+ "@types/bun": "latest"
39
+ }
40
+ }