@asagiri-design/labels-config 0.2.2

package/docs/API.md

@@ -0,0 +1,309 @@
+# API Reference
+
+## Types
+
+### `LabelConfig`
+
+Main label configuration interface.
+
+```typescript
+interface LabelConfig {
+  name: string      // Label name (unique, 1-50 chars)
+  color: HexColor   // Hex color code (6 digits)
+  description: string  // Description (1-200 chars)
+}
+```
+
+### `LabelRegistry`
+
+Container for label collections with metadata.
+
+```typescript
+interface LabelRegistry {
+  version: string
+  timestamp?: string
+  labels: LabelConfig[] | LabelCategory[]
+  metadata?: Record<string, unknown>
+}
+```
+
+### `LabelCategory`
+
+Grouping mechanism for related labels.
+
+```typescript
+interface LabelCategory {
+  category: string
+  labels: LabelConfig[]
+}
+```
+
+## Classes
+
+### `LabelManager`
+
+Main class for managing label configurations in memory.
+
+#### Constructor
+
+```typescript
+new LabelManager(options?: LabelManagerOptions)
+```
+
+Options:
+- `labels?: LabelConfig[]` - Initial labels to load
+- `strict?: boolean` - Strict validation mode (default: false)
+
+#### Methods
+
+##### `loadLabels(labels: LabelConfig[]): void`
+
+Load labels from array. Clears previous labels.
+
+##### `loadRegistry(registry: LabelRegistry): void`
+
+Load labels from registry object. Handles both flat and categorized formats.
+
+##### `addLabel(label: LabelConfig): void`
+
+Add a new label. Throws if name already exists.
+
+##### `updateLabel(name: string, updates: Partial<LabelConfig>): void`
+
+Update an existing label. Throws if label not found.
+
+##### `removeLabel(name: string): void`
+
+Remove a label by name.
+
+##### `getLabel(name: string): LabelConfig | undefined`
+
+Get a label by name. Case-insensitive.
+
+##### `hasLabel(name: string): boolean`
+
+Check if label exists. Case-insensitive.
+
+##### `getAllLabels(): LabelConfig[]`
+
+Get all labels as array.
+
+##### `count(): number`
+
+Get total number of labels.
+
+##### `export(): LabelConfig[]`
+
+Export all labels as array.
+
+##### `exportRegistry(version?: string, metadata?: Record<string, unknown>): LabelRegistry`
+
+Export as registry object with metadata.
+
+##### `search(query: string): LabelConfig[]`
+
+Search labels by name or description. Case-insensitive.
+
+##### `findByColor(color: string): LabelConfig[]`
+
+Find labels by color code. Case-insensitive.
+
+##### `clear(): void`
+
+Clear all labels.
+
+##### `validate(): { valid: boolean; duplicates: string[] }`
+
+Validate current state. Returns duplicate label names.
+
+### `GitHubLabelSync`
+
+Synchronize labels with GitHub repositories.
+
+#### Constructor
+
+```typescript
+new GitHubLabelSync(options: GitHubSyncOptions)
+```
+
+Options:
+- `token: string` - GitHub personal access token (required)
+- `owner: string` - Repository owner (required)
+- `repo: string` - Repository name (required)
+- `dryRun?: boolean` - Dry run mode (default: false)
+- `deleteExtra?: boolean` - Delete extra labels (default: false)
+- `verbose?: boolean` - Verbose logging (default: false)
+
+#### Methods
+
+##### `async syncLabels(labels: LabelConfig[]): Promise<SyncResult>`
+
+Sync local labels to GitHub repository.
+
+Returns:
+```typescript
+interface SyncResult {
+  created: LabelConfig[]
+  updated: LabelConfig[]
+  deleted: string[]
+  unchanged: LabelConfig[]
+  errors: Array<{ name: string; error: string }>
+}
+```
+
+##### `async fetchLabels(): Promise<LabelConfig[]>`
+
+Fetch all labels from GitHub repository.
+
+##### `async deleteLabel(name: string): Promise<void>`
+
+Delete a single label from repository.
+
+##### `async updateLabel(name: string, updates: Partial<LabelConfig>): Promise<void>`
+
+Update a single label in repository.
+
+### `ConfigLoader`
+
+Load configurations from various sources.
+
+#### Constructor
+
+```typescript
+new ConfigLoader(options?: LoaderOptions)
+```
+
+Options:
+- `strict?: boolean` - Strict validation mode (default: true)
+
+#### Methods
+
+##### `loadFromJSON(data: unknown): LabelConfig[]`
+
+Load labels from JSON object or array.
+
+##### `loadFromString(jsonString: string): LabelConfig[]`
+
+Load labels from JSON string.
+
+##### `loadRegistry(registry: LabelRegistry): LabelConfig[]`
+
+Load labels from registry object.
+
+## Functions
+
+### Validation
+
+#### `validateLabel(label: unknown): LabelConfig`
+
+Validate and normalize a single label.
+
+Throws: `ZodError` if validation fails.
+
+#### `validateLabels(labels: unknown): LabelConfig[]`
+
+Validate and normalize multiple labels.
+
+Throws: `ZodError` if validation fails.
+
+#### `validateRegistry(registry: unknown): LabelRegistry`
+
+Validate complete registry object.
+
+Throws: `ZodError` if validation fails.
+
+#### `validateWithDetails(labels: unknown): ValidationResult`
+
+Comprehensive validation with detailed error reporting.
+
+```typescript
+interface ValidationResult {
+  valid: boolean
+  labels: LabelConfig[]
+  errors: {
+    duplicateNames?: string[]
+    duplicateColors?: string[]
+    validationErrors?: ZodError[]
+  }
+}
+```
+
+#### `checkDuplicateNames(labels: LabelConfig[]): string[]`
+
+Find duplicate label names.
+
+#### `checkDuplicateColors(labels: LabelConfig[]): string[]`
+
+Find duplicate colors.
+
+### Type Guards
+
+#### `isCategorized(labels: LabelConfig[] | LabelCategory[]): labels is LabelCategory[]`
+
+Check if labels are categorized.
+
+#### `flattenLabels(labels: LabelConfig[] | LabelCategory[]): LabelConfig[]`
+
+Flatten categorized labels to flat array.
+
+### Templates
+
+#### `getTemplate(name: TemplateName): LabelConfig[]`
+
+Get predefined template by name.
+
+Templates:
+- `minimal` - Minimal set for getting started
+- `github` - GitHub standard labels
+- `prod` - Production project labels (Japanese)
+- `prod-en` - Production project labels (English)
+- `prod-ja` - Production project labels (Japanese, alias)
+- `react` - React ecosystem labels
+- `vue` - Vue.js ecosystem labels
+- `frontend` - General frontend development labels
+- `agile` - Agile/Scrum labels
+
+#### `listTemplates(): TemplateName[]`
+
+List all available template names.
+
+## Error Handling
+
+All validation functions throw `ZodError` on invalid input:
+
+```typescript
+import { validateLabel } from '@boxpistols/labels-config'
+
+try {
+  validateLabel({ name: 'test', color: 'invalid' })
+} catch (error) {
+  if (error instanceof ZodError) {
+    error.errors.forEach(err => {
+      console.log(err.path, err.message)
+    })
+  }
+}
+```
+
+## Strict Mode
+
+When `strict: true` is passed to managers/loaders:
+- All errors throw immediately
+- No partial results are returned
+- Validation is mandatory
+
+When `strict: false`:
+- Some errors are warnings
+- Partial results may be returned
+- Validation is optional
+
+## Type Safety
+
+All APIs are fully typed with TypeScript. No `any` types are used.
+
+```typescript
+// Full type inference
+const manager = new LabelManager({ labels: [] })
+const label = manager.getLabel('test') // Type: LabelConfig | undefined
+const all = manager.getAllLabels()      // Type: LabelConfig[]
+```

package/docs/GETTING_STARTED.md

@@ -0,0 +1,305 @@
+# Getting Started with @boxpistols/labels-config
+
+## Installation
+
+### npm
+
+```bash
+npm install @boxpistols/labels-config
+```
+
+### yarn
+
+```bash
+yarn add @boxpistols/labels-config
+```
+
+### pnpm
+
+```bash
+pnpm add @boxpistols/labels-config
+```
+
+### CDN
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@boxpistols/labels-config/dist/index.umd.js"></script>
+<script>
+  const { validateLabels } = window.LabelsConfig
+</script>
+```
+
+## Basic Usage
+
+### Validate Labels
+
+```typescript
+import { validateLabels } from '@boxpistols/labels-config'
+
+const labels = [
+  {
+    name: 'bug',
+    color: 'ff0000',
+    description: 'Something is broken'
+  },
+  {
+    name: 'feature',
+    color: '00ff00',
+    description: 'New feature or request'
+  }
+]
+
+// Validate labels
+const validated = validateLabels(labels)
+console.log(validated) // Returns validated and normalized labels
+```
+
+### Using Label Manager
+
+```typescript
+import { LabelManager } from '@boxpistols/labels-config'
+
+const manager = new LabelManager({
+  labels: [
+    { name: 'bug', color: 'ff0000', description: 'Bug' },
+    { name: 'feature', color: '00ff00', description: 'Feature' }
+  ]
+})
+
+// Add a label
+manager.addLabel({ name: 'docs', color: '0000ff', description: 'Documentation' })
+
+// Get all labels
+const allLabels = manager.getAllLabels()
+
+// Search labels
+const results = manager.search('feature')
+
+// Export
+const exported = manager.export()
+const registry = manager.exportRegistry('1.0.0')
+```
+
+### GitHub Synchronization
+
+```typescript
+import { GitHubLabelSync } from '@boxpistols/labels-config/github'
+
+const sync = new GitHubLabelSync({
+  token: process.env.GITHUB_TOKEN,
+  owner: 'your-org',
+  repo: 'your-repo',
+  verbose: true
+})
+
+// Sync local labels to GitHub
+const result = await sync.syncLabels([
+  { name: 'bug', color: 'ff0000', description: 'Bug' },
+  { name: 'feature', color: '00ff00', description: 'Feature' }
+])
+
+console.log(`Created: ${result.created.length}`)
+console.log(`Updated: ${result.updated.length}`)
+console.log(`Deleted: ${result.deleted.length}`)
+```
+
+### Load Configuration from File
+
+```typescript
+import { ConfigLoader } from '@boxpistols/labels-config/config'
+import { promises as fs } from 'fs'
+
+const loader = new ConfigLoader()
+const fileContent = await fs.readFile('labels.json', 'utf-8')
+const labels = loader.loadFromString(fileContent)
+```
+
+### Using Templates
+
+```typescript
+import { CONFIG_TEMPLATES, listTemplates } from '@boxpistols/labels-config/config'
+
+// Get production template (Japanese)
+const prodLabels = CONFIG_TEMPLATES.prod
+
+// List all available templates
+const templates = listTemplates() // ['minimal', 'github', 'prod', 'prod-en', 'prod-ja', 'react', 'vue', 'frontend', 'agile']
+
+// Use GitHub standard template
+const githubLabels = CONFIG_TEMPLATES.github
+```
+
+## CLI Usage
+
+### Initialize Configuration
+
+```bash
+# Create from template
+labels-config init prod-ja --file labels.json
+
+# Available templates: minimal, github, prod, prod-en, prod-ja, react, vue, frontend, agile
+labels-config init github --file labels.json
+```
+
+### Validate Configuration
+
+```bash
+labels-config validate ./labels.json
+```
+
+### Sync to GitHub
+
+```bash
+labels-config sync \
+  --token $GITHUB_TOKEN \
+  --owner your-org \
+  --repo your-repo \
+  --file labels.json \
+  --verbose
+```
+
+### Dry Run
+
+```bash
+# See what would be changed without actually changing
+labels-config sync \
+  --token $GITHUB_TOKEN \
+  --owner your-org \
+  --repo your-repo \
+  --file labels.json \
+  --dry-run \
+  --verbose
+```
+
+### Export from Repository
+
+```bash
+# Export existing labels from GitHub
+labels-config export \
+  --token $GITHUB_TOKEN \
+  --owner your-org \
+  --repo your-repo \
+  --file exported-labels.json
+```
+
+## Configuration File Format
+
+### Flat List
+
+```json
+[
+  {
+    "name": "bug",
+    "color": "ff0000",
+    "description": "Something is broken"
+  },
+  {
+    "name": "feature",
+    "color": "00ff00",
+    "description": "New feature"
+  }
+]
+```
+
+### Registry Format
+
+```json
+{
+  "version": "1.0.0",
+  "timestamp": "2024-11-12T00:00:00Z",
+  "labels": [
+    {
+      "name": "bug",
+      "color": "ff0000",
+      "description": "Something is broken"
+    }
+  ],
+  "metadata": {
+    "project": "my-project"
+  }
+}
+```
+
+### Categorized Labels
+
+```json
+{
+  "version": "1.0.0",
+  "labels": [
+    {
+      "category": "Type",
+      "labels": [
+        {
+          "name": "bug",
+          "color": "ff0000",
+          "description": "Bug fix"
+        },
+        {
+          "name": "feature",
+          "color": "00ff00",
+          "description": "New feature"
+        }
+      ]
+    },
+    {
+      "category": "Priority",
+      "labels": [
+        {
+          "name": "priority:high",
+          "color": "ff0000",
+          "description": "High priority"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Advanced Usage
+
+### Error Handling
+
+```typescript
+import { validateWithDetails } from '@boxpistols/labels-config'
+
+const result = validateWithDetails(data)
+
+if (!result.valid) {
+  console.log('Duplicate names:', result.errors.duplicateNames)
+  console.log('Duplicate colors:', result.errors.duplicateColors)
+  console.log('Validation errors:', result.errors.validationErrors)
+}
+```
+
+### Custom Validation
+
+```typescript
+import { checkDuplicateNames, checkDuplicateColors } from '@boxpistols/labels-config'
+
+const duplicateNames = checkDuplicateNames(labels)
+const duplicateColors = checkDuplicateColors(labels)
+
+if (duplicateNames.length > 0) {
+  console.warn('Found duplicate label names:', duplicateNames)
+}
+```
+
+### Search and Filter
+
+```typescript
+// Search by name or description
+const results = manager.search('bug')
+
+// Find by color
+const redLabels = manager.findByColor('ff0000')
+
+// Case-insensitive retrieval
+const label = manager.getLabel('BUG') // Returns label named 'bug'
+```
+
+## Next Steps
+
+- Read the [API documentation](./API.md)
+- Check [examples](../examples)
+- View [CLI documentation](./CLI.md)
+- See [templates documentation](./TEMPLATES.md)

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@asagiri-design/labels-config",
+  "version": "0.2.2",
+  "description": "Terminal-first label management system for GitHub repositories using gh CLI - No token required",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "browser": "dist/index.umd.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.esm.js",
+      "require": "./dist/config/index.js"
+    },
+    "./github": {
+      "types": "./dist/github/index.d.ts",
+      "import": "./dist/github/index.esm.js",
+      "require": "./dist/github/index.js"
+    }
+  },
+  "bin": {
+    "labels-config": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "docs"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts src/config/index.ts src/github/index.ts src/cli.ts --format cjs,esm --dts --shims",
+    "build:umd": "tsup src/index.ts --format iife --dts --globalName LabelsConfig --outDir dist",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src --fix",
+    "cli": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build",
+    "version": "node -e \"const fs=require('fs');const v=require('./package.json').version;fs.writeFileSync('src/version.ts','export const version = \\''+v+'\\'\\n')\" && git add src/version.ts",
+    "release:patch": "npm version patch -m 'Release v%s [skip ci]' && npm publish --access public && git push --follow-tags",
+    "release:minor": "npm version minor -m 'Release v%s [skip ci]' && npm publish --access public && git push --follow-tags",
+    "release:major": "npm version major -m 'Release v%s [skip ci]' && npm publish --access public && git push --follow-tags",
+    "release:beta": "npm version prerelease --preid=beta -m 'Release v%s [skip ci]' && npm publish --access public --tag beta && git push --follow-tags"
+  },
+  "keywords": [
+    "labels",
+    "github",
+    "issue-tracking",
+    "config",
+    "management",
+    "schema",
+    "validation"
+  ],
+  "author": "BoxPistols",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BoxPistols/labels-config.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BoxPistols/labels-config/issues"
+  },
+  "homepage": "https://github.com/BoxPistols/labels-config#readme",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.54.0",
+    "tsup": "^8.0.2",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.0.4"
+  },
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}