@asagiri-design/labels-config 0.2.2

package/README.md

@@ -0,0 +1,387 @@
+# @boxpistols/labels-config
+
+Terminal-first GitHub label management - Simple, fast, no token needed.
+
+Manage GitHub labels from your terminal using gh CLI. No manual token setup required.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install gh CLI and authenticate (one-time setup)
+brew install gh  # macOS
+gh auth login
+
+# 2. Install labels-config
+npm install -g @boxpistols/labels-config
+
+# 3. Initialize from template
+labels-config init minimal --file labels.json
+
+# 4. Sync to your repository
+labels-config sync --owner your-name --repo your-repo --file labels.json
+```
+
+Done! Your labels are synced.
+
+---
+
+## Features
+
+- **Terminal-First**: No token management - uses gh CLI authentication
+- **Simple CLI**: 5 commands, straightforward usage
+- **Pre-built Templates**: 9 ready-to-use label sets
+- **Validation**: Check your config before syncing
+- **Dry Run**: Preview changes before applying
+
+---
+
+## Installation
+
+### Prerequisites
+
+Install and authenticate gh CLI:
+
+```bash
+# macOS
+brew install gh
+
+# Linux (Debian/Ubuntu)
+sudo apt install gh
+
+# Windows
+winget install --id GitHub.cli
+
+# Authenticate
+gh auth login
+```
+
+### Install labels-config
+
+```bash
+npm install -g @boxpistols/labels-config
+```
+
+---
+
+## Usage
+
+### Understanding init vs sync
+
+**Important:** The `init` command creates a local configuration file - it does NOT sync to GitHub.
+
+| Command | What it does |
+|---------|--------------|
+| `init` | Creates `labels.json` locally (no GitHub changes) |
+| `sync` | Applies `labels.json` to your GitHub repository |
+
+**Example workflow:**
+```bash
+# Step 1: Create local config file (no GitHub changes yet)
+labels-config init prod-ja --file labels.json
+
+# Step 2: Check what's in the file
+cat labels.json
+
+# Step 3: Apply to GitHub (this actually changes your labels)
+labels-config sync --owner your-name --repo your-repo --file labels.json
+```
+
+### 1. Create label configuration
+
+**From template:**
+```bash
+labels-config init minimal --file labels.json
+```
+
+**Available templates:**
+- `minimal` - Basic 3-label set (bug, feature, documentation)
+- `github` - GitHub standard labels
+- `prod-ja` - Production project (Japanese, 14 labels)
+- `prod-en` - Production project (English, 14 labels)
+- `agile` - Agile/Scrum workflow
+- `react`, `vue`, `frontend` - Framework-specific
+
+### 2. Validate configuration
+
+```bash
+labels-config validate labels.json
+```
+
+### 3. Preview changes (dry run)
+
+```bash
+labels-config sync \
+  --owner your-name \
+  --repo your-repo \
+  --file labels.json \
+  --dry-run \
+  --verbose
+```
+
+### 4. Sync to GitHub
+
+**Append mode** (default - keeps existing labels):
+```bash
+labels-config sync --owner your-name --repo your-repo --file labels.json
+```
+
+**Replace mode** (removes unlisted labels):
+```bash
+labels-config sync --owner your-name --repo your-repo --file labels.json --delete-extra
+```
+
+### 5. Export existing labels
+
+```bash
+labels-config export --owner your-name --repo your-repo --file exported.json
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `init <template>` | Create label config from template |
+| `validate <file>` | Validate label configuration |
+| `sync` | Sync labels to GitHub |
+| `export` | Export labels from GitHub |
+| `help` | Show help |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--owner <name>` | Repository owner |
+| `--repo <name>` | Repository name |
+| `--file <path>` | Config file path |
+| `--dry-run` | Preview changes only |
+| `--delete-extra` | Delete unlisted labels (replace mode) |
+| `--verbose` | Show detailed output |
+
+---
+
+## Label Configuration Format
+
+```json
+{
+  "version": "1.0.0",
+  "labels": [
+    {
+      "name": "bug",
+      "color": "d73a4a",
+      "description": "Something isn't working"
+    },
+    {
+      "name": "feature",
+      "color": "0e8a16",
+      "description": "New feature request"
+    }
+  ]
+}
+```
+
+**Requirements:**
+- `name`: 1-50 characters
+- `color`: 3 or 6 character hex code (without #)
+- `description`: 1-200 characters
+
+---
+
+## Sync Modes
+
+### Append Mode (Default)
+Adds new labels and updates existing ones. Keeps labels not in your config.
+
+```bash
+labels-config sync --owner user --repo repo --file labels.json
+```
+
+### Replace Mode
+Deletes all labels not in your config. Complete control.
+
+```bash
+labels-config sync --owner user --repo repo --file labels.json --delete-extra
+```
+
+⚠️ **Warning**: Replace mode removes labels from all issues and PRs. Always use `--dry-run` first!
+
+---
+
+## Multi-Repository Sync
+
+Sync the same labels to multiple repositories:
+
+```bash
+#!/bin/bash
+REPOS=("org/repo1" "org/repo2" "org/repo3")
+
+for REPO in "${REPOS[@]}"; do
+  OWNER=$(echo $REPO | cut -d'/' -f1)
+  REPO_NAME=$(echo $REPO | cut -d'/' -f2)
+
+  labels-config sync \
+    --owner $OWNER \
+    --repo $REPO_NAME \
+    --file labels.json \
+    --verbose
+done
+```
+
+---
+
+## Workflow Integration
+
+### GitHub Actions
+
+```yaml
+name: Sync Labels
+
+on:
+  push:
+    paths:
+      - 'labels.json'
+    branches:
+      - main
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install labels-config
+        run: npm install -g @boxpistols/labels-config
+
+      - name: Install gh CLI
+        run: |
+          sudo apt update
+          sudo apt install gh -y
+
+      - name: Authenticate gh CLI
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: echo "$GITHUB_TOKEN" | gh auth login --with-token
+
+      - name: Sync labels
+        run: |
+          labels-config sync \
+            --owner ${{ github.repository_owner }} \
+            --repo ${{ github.event.repository.name }} \
+            --file labels.json \
+            --verbose
+```
+
+---
+
+## Troubleshooting
+
+### Authentication failed
+
+```bash
+# Check gh CLI status
+gh auth status
+
+# Re-authenticate
+gh auth login
+
+# Refresh authentication
+gh auth refresh
+```
+
+### Validation errors
+
+```bash
+# Run validation to see specific errors
+labels-config validate labels.json
+
+# Common issues:
+# - Duplicate label names
+# - Invalid hex colors (must be 3 or 6 chars without #)
+# - Name too long (max 50 chars)
+# - Description too long (max 200 chars)
+```
+
+### Labels not syncing
+
+```bash
+# Check with verbose output
+labels-config sync --owner user --repo repo --file labels.json --verbose
+
+# Try dry run to see what would change
+labels-config sync --owner user --repo repo --file labels.json --dry-run --verbose
+```
+
+### Rate limit exceeded
+
+```bash
+# Check rate limit status
+gh api rate_limit
+
+# Wait for reset (typically 60 minutes)
+```
+
+---
+
+## Best Practices
+
+**✅ DO:**
+- Keep `labels.json` in version control
+- Run `--dry-run` before actual sync
+- Use semantic commit messages
+- Document label purposes in your project
+- Use consistent colors across projects
+
+**❌ DON'T:**
+- Delete labels without checking issue/PR usage
+- Change label names frequently
+- Skip validation before syncing
+
+---
+
+## Advanced Usage
+
+### As npm Package
+
+You can also use this as a library in your code:
+
+```typescript
+import { GitHubLabelSync } from '@boxpistols/labels-config/github'
+import { CONFIG_TEMPLATES } from '@boxpistols/labels-config'
+
+const sync = new GitHubLabelSync({
+  owner: 'your-org',
+  repo: 'your-repo'
+})
+
+const labels = CONFIG_TEMPLATES.minimal
+await sync.syncLabels(labels)
+```
+
+Install in your project:
+```bash
+npm install @boxpistols/labels-config
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Related
+
+- [日本語 README](./README.ja.md)
+
+---
+
+**Made for terminal users who love gh CLI** 🚀

package/dist/chunk-4ZUJQMV7.mjs

@@ -0,0 +1,285 @@
+import {
+  __publicField
+} from "./chunk-QZ7TP4HQ.mjs";
+
+// src/github/client.ts
+import { execSync } from "child_process";
+var GitHubClient = class {
+  constructor(options) {
+    __publicField(this, "owner");
+    __publicField(this, "repo");
+    __publicField(this, "repoPath");
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.repoPath = `${this.owner}/${this.repo}`;
+  }
+  /**
+   * Execute gh CLI command
+   */
+  exec(command) {
+    try {
+      return execSync(command, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+    } catch (error) {
+      throw new Error(`gh CLI command failed: ${error.message}`);
+    }
+  }
+  /**
+   * Fetch all labels from repository
+   */
+  async fetchLabels() {
+    try {
+      const output = this.exec(
+        `gh label list --repo ${this.repoPath} --json name,color,description --limit 1000`
+      );
+      if (!output) {
+        return [];
+      }
+      const labels = JSON.parse(output);
+      return labels.map((label) => ({
+        name: label.name,
+        color: label.color,
+        description: label.description || ""
+      }));
+    } catch (error) {
+      throw new Error(`Failed to fetch labels from ${this.repoPath}: ${error}`);
+    }
+  }
+  /**
+   * Create a new label
+   */
+  async createLabel(label) {
+    try {
+      const name = label.name.replace(/"/g, '\\"');
+      const description = label.description.replace(/"/g, '\\"');
+      const color = label.color.replace("#", "");
+      this.exec(
+        `gh label create "${name}" --color "${color}" --description "${description}" --repo ${this.repoPath}`
+      );
+      return {
+        name: label.name,
+        color: label.color,
+        description: label.description
+      };
+    } catch (error) {
+      throw new Error(`Failed to create label "${label.name}": ${error}`);
+    }
+  }
+  /**
+   * Update an existing label
+   */
+  async updateLabel(currentName, label) {
+    try {
+      const escapedCurrentName = currentName.replace(/"/g, '\\"');
+      const args = [];
+      if (label.name && label.name !== currentName) {
+        args.push(`--name "${label.name.replace(/"/g, '\\"')}"`);
+      }
+      if (label.color) {
+        args.push(`--color "${label.color.replace("#", "")}"`);
+      }
+      if (label.description !== void 0) {
+        args.push(`--description "${label.description.replace(/"/g, '\\"')}"`);
+      }
+      if (args.length === 0) {
+        return {
+          name: currentName,
+          color: label.color || "",
+          description: label.description || ""
+        };
+      }
+      this.exec(
+        `gh label edit "${escapedCurrentName}" ${args.join(" ")} --repo ${this.repoPath}`
+      );
+      return {
+        name: label.name || currentName,
+        color: label.color || "",
+        description: label.description || ""
+      };
+    } catch (error) {
+      throw new Error(`Failed to update label "${currentName}": ${error}`);
+    }
+  }
+  /**
+   * Delete a label
+   */
+  async deleteLabel(name) {
+    try {
+      const escapedName = name.replace(/"/g, '\\"');
+      this.exec(`gh label delete "${escapedName}" --repo ${this.repoPath} --yes`);
+    } catch (error) {
+      throw new Error(`Failed to delete label "${name}": ${error}`);
+    }
+  }
+  /**
+   * Check if label exists
+   */
+  async hasLabel(name) {
+    try {
+      const labels = await this.fetchLabels();
+      return labels.some((label) => label.name.toLowerCase() === name.toLowerCase());
+    } catch (error) {
+      return false;
+    }
+  }
+};
+
+// src/github/sync.ts
+var _GitHubLabelSync = class _GitHubLabelSync {
+  constructor(options) {
+    __publicField(this, "client");
+    __publicField(this, "options");
+    this.client = new GitHubClient(options);
+    this.options = options;
+  }
+  /**
+   * Log message if verbose mode is enabled
+   */
+  log(message) {
+    if (this.options.verbose) {
+      console.log(`[labels-config] ${message}`);
+    }
+  }
+  /**
+   * Sync labels to GitHub repository with batch operations for better performance
+   */
+  async syncLabels(localLabels) {
+    this.log("Fetching remote labels...");
+    const remoteLabels = await this.client.fetchLabels();
+    const result = {
+      created: [],
+      updated: [],
+      deleted: [],
+      unchanged: [],
+      errors: []
+    };
+    const remoteLabelMap = new Map(remoteLabels.map((label) => [label.name.toLowerCase(), label]));
+    const localLabelMap = new Map(localLabels.map((label) => [label.name.toLowerCase(), label]));
+    const toCreate = [];
+    const toUpdate = [];
+    const toDelete = [];
+    for (const label of localLabels) {
+      const remoteLabel = remoteLabelMap.get(label.name.toLowerCase());
+      if (!remoteLabel) {
+        toCreate.push(label);
+      } else if (this.hasChanges(label, remoteLabel)) {
+        toUpdate.push({ current: remoteLabel.name, updated: label });
+      } else {
+        result.unchanged.push(label);
+        this.log(`Unchanged label: ${label.name}`);
+      }
+    }
+    if (this.options.deleteExtra) {
+      for (const remoteLabel of remoteLabels) {
+        if (!localLabelMap.has(remoteLabel.name.toLowerCase())) {
+          toDelete.push(remoteLabel.name);
+        }
+      }
+    }
+    if (!this.options.dryRun) {
+      for (let i = 0; i < toCreate.length; i += _GitHubLabelSync.BATCH_SIZE) {
+        const batch = toCreate.slice(i, i + _GitHubLabelSync.BATCH_SIZE);
+        const promises = batch.map(async (label) => {
+          try {
+            await this.client.createLabel(label);
+            result.created.push(label);
+            this.log(`Created label: ${label.name}`);
+          } catch (error) {
+            result.errors.push({
+              name: label.name,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            this.log(`Error creating label "${label.name}": ${error}`);
+          }
+        });
+        await Promise.all(promises);
+      }
+      for (let i = 0; i < toUpdate.length; i += _GitHubLabelSync.BATCH_SIZE) {
+        const batch = toUpdate.slice(i, i + _GitHubLabelSync.BATCH_SIZE);
+        const promises = batch.map(async ({ current, updated }) => {
+          try {
+            await this.client.updateLabel(current, updated);
+            result.updated.push(updated);
+            this.log(`Updated label: ${updated.name}`);
+          } catch (error) {
+            result.errors.push({
+              name: updated.name,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            this.log(`Error updating label "${updated.name}": ${error}`);
+          }
+        });
+        await Promise.all(promises);
+      }
+      for (let i = 0; i < toDelete.length; i += _GitHubLabelSync.BATCH_SIZE) {
+        const batch = toDelete.slice(i, i + _GitHubLabelSync.BATCH_SIZE);
+        const promises = batch.map(async (name) => {
+          try {
+            await this.client.deleteLabel(name);
+            result.deleted.push(name);
+            this.log(`Deleted label: ${name}`);
+          } catch (error) {
+            result.errors.push({
+              name,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            this.log(`Error deleting label "${name}": ${error}`);
+          }
+        });
+        await Promise.all(promises);
+      }
+    } else {
+      result.created.push(...toCreate);
+      result.updated.push(...toUpdate.map((op) => op.updated));
+      result.deleted.push(...toDelete);
+      toCreate.forEach((label) => this.log(`[DRY RUN] Would create label: ${label.name}`));
+      toUpdate.forEach(({ updated }) => this.log(`[DRY RUN] Would update label: ${updated.name}`));
+      toDelete.forEach((name) => this.log(`[DRY RUN] Would delete label: ${name}`));
+    }
+    return result;
+  }
+  /**
+   * Check if label has changes
+   */
+  hasChanges(local, remote) {
+    return local.color.toLowerCase() !== remote.color.toLowerCase() || local.description !== (remote.description || "");
+  }
+  /**
+   * Fetch labels from GitHub
+   */
+  async fetchLabels() {
+    const labels = await this.client.fetchLabels();
+    return labels.map((label) => ({
+      name: label.name,
+      color: label.color,
+      description: label.description || ""
+    }));
+  }
+  /**
+   * Delete a single label
+   */
+  async deleteLabel(name) {
+    if (!this.options.dryRun) {
+      await this.client.deleteLabel(name);
+    }
+    this.log(`Deleted label: ${name}`);
+  }
+  /**
+   * Update a single label
+   */
+  async updateLabel(name, updates) {
+    if (!this.options.dryRun) {
+      await this.client.updateLabel(name, updates);
+    }
+    this.log(`Updated label: ${name}`);
+  }
+};
+__publicField(_GitHubLabelSync, "BATCH_SIZE", 5);
+var GitHubLabelSync = _GitHubLabelSync;
+
+export {
+  GitHubClient,
+  GitHubLabelSync
+};