cli-pagemeta2issue

CSVページメタデータからGitHub Issueを一括作成する強力なCLIツール。カスタマイズ可能なテンプレート機能により、プロジェクトに最適な形式でIssueを生成できます。

主な機能

• 📊 CSVファイル処理: ページメタデータをCSVから読み込み、構造化されたIssueを作成
• 📝 テンプレート対応: Markdownテンプレートで自由にIssue形式をカスタマイズ
• 🏷️ スマートラベリング: ステータスとタイプに基づく自動ラベル付け
• 📍 マイルストーン管理: サイドバー位置に基づくマイルストーンの自動作成・割り当て
• ⚡ バッチ処理: GitHub APIレート制限を考慮した効率的な処理
• 🔄 リトライ機能: 失敗したリクエストの自動再試行
• 🎯 ドライラン: 実際のAPI呼び出しなしで作成内容を確認
• 🎨 視覚的フィードバック: プログレスバー付きの分かりやすい出力

インストール

グローバルインストール（推奨）

npm install -g cli-pagemeta2issue

pnpmを使用する場合:

pnpm add -g cli-pagemeta2issue

ローカルインストール

npm install cli-pagemeta2issue

クイックスタート

基本的な使い方

# 1. CSVファイルからIssueを作成（トークンとリポジトリを指定）
pagemeta2issue page.csv --repo owner/repo --token ghp_xxxxx

# 2. テンプレートを使用してカスタマイズ
pagemeta2issue page.csv --repo owner/repo --token ghp_xxxxx --template ./template.md

# 3. ドライランで事前確認
pagemeta2issue page.csv --dry-run --repo owner/repo --token ghp_xxxxx

# 4. 作成したIssueを一括クローズ
pagemeta2issue --all-close --repo owner/repo --token ghp_xxxxx

# 5. 一括クローズのドライラン
pagemeta2issue --all-close --dry-run --repo owner/repo --token ghp_xxxxx

環境変数での設定

# 環境変数を設定
export GITHUB_TOKEN=ghp_xxxxx
export GITHUB_REPOSITORY=owner/repo
export GITHUB_TEMPLATE=./template.md  # オプション

# 簡潔なコマンドで実行
pagemeta2issue page.csv

設定ファイルを使用

# config.jsonに設定を定義して実行
pagemeta2issue page.csv --config ./config.json

CSVファイル形式

CSVファイルは以下のヘッダーを含む必要があります:

sidebar_position,slug,parent,title,status,post_type,seo_title,seo_keywords,seo_description,handson_overview
1,getting-started,,Getting Started,draft,pages,"Getting Started Guide","intro, guide",Introduction to the system,Basic overview
2,installation,getting-started,Installation,published,pages,"Installation Guide","install, setup",How to install,Step-by-step installation

必須フィールド

• sidebar_position: 順序付けのための数値
• slug: ページの一意識別子
• title: ページタイトル（Issueタイトルになります）
• status: "draft" または "published"
• post_type: コンテンツの種類（例："pages", "posts"）
• seo_title: SEO最適化されたタイトル
• seo_keywords: SEOキーワード
• seo_description: SEO説明文
• handson_overview: 概要またはサマリー

オプションフィールド

• parent: 階層構造のための親ページslug

設定

設定ファイル

JSONまたはYAML形式の設定ファイルを作成できます:

{
  "github": {
    "token": "ghp_xxxxx",
    "repository": "owner/repo"
  },
  "processing": {
    "batchSize": 5,
    "delayMs": 1000,
    "maxRetries": 3
  },
  "labels": {
    "statusMapping": {
      "draft": "status:draft",
      "published": "status:published"
    },
    "postTypeMapping": {
      "pages": "type:page",
      "posts": "type:post"
    }
  },
  "milestones": {
    "autoCreate": true,
    "nameTemplate": "Section {position}"
  },
  "template": {
    "defaultFile": "./template.md"
  }
}

環境変数

• GITHUB_TOKEN: GitHub Personal Access Token
• GITHUB_REPOSITORY: "owner/repo"形式のリポジトリ名
• GITHUB_TEMPLATE: テンプレートファイルのパス（オプション）
• BATCH_SIZE: バッチごとのIssue数
• DELAY_MS: リクエスト間の遅延（ミリ秒）

CLIオプション

Usage: pagemeta2issue [csv-file] [options]

Arguments:
  csv-file                        CSVファイルのパス（ページメタデータを含む）
                                  --all-close使用時は不要

Options:
  # 基本オプション
  -c, --config <file>             設定ファイルのパス（JSONまたはYAML）
  -d, --dry-run                   実際のAPI呼び出しを行わずに作成/削除予定の内容を表示
  -r, --repo <owner/repo>         GitHubリポジトリ（例：owner/repo）
  -t, --token <token>             GitHub Personal Access Token
  -v, --verbose                   デバッグ用の詳細出力を有効化
  -V, --version                   バージョン情報を表示
  -h, --help                      コマンドのヘルプを表示

  # Issue作成オプション
  --template <file>               テンプレートファイル（Markdownファイル）
  -b, --batch-size <num>          バッチごとに作成するIssue数（デフォルト：5）
  -w, --delay <ms>                APIリクエスト間の遅延（ミリ秒、デフォルト：1000）

  # Issue一括削除オプション
  --all-close                     ツールで作成されたIssueを一括クローズ
  --labels <labels>               フィルター用ラベル（カンマ区切り、--all-close使用時）
  --created-after <date>          指定日以降に作成されたIssueのみ対象（--all-close使用時）
  --title-pattern <pattern>       タイトル正規表現パターン（--all-close使用時）
  --content-pattern <pattern>     本文内容正規表現パターン（--all-close使用時）
  --reason <reason>               クローズ理由：completed/not_planned（--all-close使用時）
  --confirm                       確認プロンプトをスキップ（--all-close使用時）

テンプレート機能

テンプレートファイル作成

カスタムテンプレートを使用してIssueの形式をカスタマイズできます。テンプレートファイルはMarkdown形式で、変数プレースホルダーを使用してCSVデータを埋め込みます。

基本的なテンプレート例

# {{title}}

## ページ概要
このページは {{slug}} として識別され、{{status}} 状態です。

### 基本情報
- **スラッグ**: {{slug}}
- **親ページ**: {{parent}}
- **ステータス**: {{status}}
- **種別**: {{post_type}}
- **サイドバー位置**: {{sidebar_position}}

## SEO情報
- **SEOタイトル**: {{seo_title}}
- **キーワード**: {{seo_keywords}}
- **説明**: {{seo_description}}

## 作業概要
{{handson_overview}}

## タスクリスト
- [ ] ページコンテンツの作成
- [ ] SEO最適化の確認
- [ ] レビュー実施
- [ ] 公開準備

---
*この Issue は CLI tool により自動生成されました*

利用可能な変数

テンプレート内で使用できる変数：

• {{title}} - ページタイトル
• {{slug}} - ページのスラッグ（一意識別子）
• {{parent}} - 親ページのスラッグ
• {{status}} - ページの状態（draft/published）
• {{post_type}} - コンテンツの種類
• {{sidebar_position}} - サイドバーでの位置
• {{seo_title}} - SEO最適化されたタイトル
• {{seo_keywords}} - SEOキーワード
• {{seo_description}} - SEO説明文
• {{handson_overview}} - ハンズオン概要

テンプレート使用例

1. シンプルなタスクトラッカー

# TODO: {{title}}

**Page**: `{{slug}}`
**Status**: {{status}}

## Description
{{handson_overview}}

## SEO Checklist
- [ ] Title: {{seo_title}}
- [ ] Keywords: {{seo_keywords}}
- [ ] Description: {{seo_description}}

## Tasks
- [ ] Create content
- [ ] Review and edit
- [ ] Publish

2. 詳細な進捗管理用

# 📝 {{title}} - Content Creation

## 📋 Project Information
- **Page Slug**: `{{slug}}`
- **Parent Page**: {{parent}}
- **Content Type**: {{post_type}}
- **Priority**: Position {{sidebar_position}}

## 🎯 Current Status
**{{status}}**

## 📈 SEO Configuration
```yaml
title: "{{seo_title}}"
keywords: "{{seo_keywords}}"
description: "{{seo_description}}"

📝 Content Overview

{{handson_overview}}

✅ Checklist

Content Creation

• [ ] Write initial draft
• [ ] Add images and media
• [ ] Format content properly

SEO Optimization

• [ ] Optimize title and headings
• [ ] Add meta descriptions
• [ ] Include relevant keywords

Quality Assurance

• [ ] Proofread content
• [ ] Check formatting
• [ ] Verify links

Publishing

• [ ] Final review
• [ ] Set publish date
• [ ] Announce release

#### 3. ミニマルテンプレート

```markdown
# {{title}}

{{handson_overview}}

**Status**: {{status}} | **Type**: {{post_type}} | **Position**: {{sidebar_position}}

Issueフォーマット

デフォルトフォーマット（テンプレート未使用時）

テンプレートを指定しない場合、以下のデフォルトフォーマットでIssueが作成されます：

タイトル

CSVのtitleフィールドの値

本文

## 📄 ページ情報

- **Slug**: `slug-value`
- **Parent**: `parent-value` (存在する場合)
- **Status**: draft/published
- **Post Type**: pages
- **Sidebar Position**: 1

## 🔍 SEO設定

- **Title**: SEOタイトル
- **Keywords**: キーワード1, キーワード2
- **Description**: SEO説明文

## 📝 ハンズオン概要

概要の内容がここに入ります

---

### タスク
- [ ] コンテンツの作成
- [ ] レビュー
- [ ] 公開準備

ラベル

• ステータスラベル（例：status:draft）
• タイプラベル（例：type:page）
• 位置に基づく優先度ラベル
• 親ページが存在する場合はhas-parent

マイルストーン

サイドバー位置のグループに基づいて自動作成

テンプレート使用時のIssue

テンプレートファイルを指定した場合：

• タイトル: CSVのtitleフィールドの値（変更なし）
• 本文: テンプレートファイルの内容にCSVデータの値を埋め込んだもの
• ラベル: 設定に基づく自動ラベリング（デフォルトと同様）
• マイルストーン: サイドバー位置に基づく自動作成（デフォルトと同様）

テンプレート内の{{variable}}プレースホルダーがCSVの対応するフィールド値に置換されます。

一括Issue削除機能

概要

--all-closeオプションを使用することで、このツールで作成されたIssueを一括でクローズできます。この機能は、自動的にツールで作成されたIssueを識別し、安全に削除するための機能です。

基本的な使い方

# 基本的な一括クローズ
pagemeta2issue --all-close --repo owner/repo --token ghp_xxxxx

# ドライランで事前確認（推奨）
pagemeta2issue --all-close --dry-run --repo owner/repo --token ghp_xxxxx

# 確認プロンプトをスキップ
pagemeta2issue --all-close --confirm --repo owner/repo --token ghp_xxxxx

フィルタリングオプション

特定の条件でIssueをフィルタリングして削除できます：

# 特定のラベルでフィルタリング
pagemeta2issue --all-close --labels "status:draft,type:page" --repo owner/repo --token ghp_xxxxx

# 特定の日付以降に作成されたIssueのみ
pagemeta2issue --all-close --created-after "2024-01-01" --repo owner/repo --token ghp_xxxxx

# タイトルパターンでフィルタリング
pagemeta2issue --all-close --title-pattern "^Getting Started" --repo owner/repo --token ghp_xxxxx

# 本文の内容パターンでフィルタリング
pagemeta2issue --all-close --content-pattern "ページ情報" --repo owner/repo --token ghp_xxxxx

# クローズ理由を指定
pagemeta2issue --all-close --reason "not_planned" --repo owner/repo --token ghp_xxxxx

Issue識別方法

このツールは以下の方法でツールで作成されたIssueを自動識別します：

1. ラベルベース識別

• status:draft, status:published
• type:page, type:post
• has-parent
• priority:high, priority:medium, priority:low

2. コンテンツシグネチャ識別

デフォルトテンプレートの特徴的なパターンを検出：

• ## 📄 ページ情報
• ## 🔍 SEO設定
• ## 📝 ハンズオン概要
• - [ ] コンテンツの作成
• **Slug**:, **Status**:, **Post Type**:

3. マイルストーンパターン識別

• Section 1, Section 2などの自動作成されたマイルストーン

安全機能

ドライランモード

実際の削除を行う前に、対象となるIssueを確認できます：

pagemeta2issue --all-close --dry-run --repo owner/repo --token ghp_xxxxx

出力例：

🔍 Found 15 issues to close:

  1. #123: Getting Started
     URL: https://github.com/owner/repo/issues/123
     Match reasons: tool labels: status:draft, type:page
     Labels: status:draft, type:page, priority:high

  2. #124: Installation Guide
     URL: https://github.com/owner/repo/issues/124
     Match reasons: default content signature
     Labels: status:published, type:page

🔍 DRY RUN: Would close 15 issues

確認プロンプト

デフォルトでは、実際に削除する前に確認を求めます：

⚠️  Are you sure you want to close 15 issues? (y/N): 

--confirmオプションで確認をスキップできます。

エラーハンドリング

• 個別のIssue削除に失敗しても、他のIssueの処理を継続
• 削除に失敗したIssueの詳細レポートを表示
• レート制限を考慮した遅延処理

高度な使用例

# 複数条件でのフィルタリング
pagemeta2issue --all-close \
  --labels "status:draft" \
  --created-after "2024-01-01" \
  --title-pattern "^Section" \
  --reason "not_planned" \
  --repo owner/repo \
  --token ghp_xxxxx

# 設定ファイルを使用した削除
pagemeta2issue --all-close --config ./config.json --dry-run

# 環境変数を使用した削除
export GITHUB_TOKEN=ghp_xxxxx
export GITHUB_REPOSITORY=owner/repo
pagemeta2issue --all-close --dry-run

トラブルシューティング

対象Issueが見つからない場合

# より詳細な出力で確認
pagemeta2issue --all-close --verbose --dry-run --repo owner/repo --token ghp_xxxxx

期待されるIssueが見つからない場合は、以下を確認してください：

• Issueが実際にこのツールで作成されたものか
• ラベルやコンテンツが期待される形式になっているか
• フィルター条件が適切に設定されているか

削除に失敗する場合

• GitHub APIのレート制限に達していないか確認
• トークンに適切な権限（repo スコープ）があるか確認
• リポジトリへの書き込み権限があるか確認

開発

セットアップ

# リポジトリをクローン
git clone https://github.com/yourusername/cli-pagemeta2issue.git
cd cli-pagemeta2issue

# 依存関係をインストール
pnpm install

# プロジェクトをビルド
pnpm build

# 開発モードで実行
pnpm dev page.csv --repo owner/repo --token ghp_xxxxx

# テンプレート付きで実行
pnpm dev page.csv --repo owner/repo --token ghp_xxxxx --template ./template.md

テスト

# テストの実行
pnpm test

# カバレッジ付きでテスト実行
pnpm test --coverage

ビルド

# 本番用ビルド
pnpm build

# npmパッケージの作成
pnpm pack

動作環境

• Node.js >= 18.0.0
• repoスコープを持つGitHub Personal Access Token
• 対象リポジトリへの書き込み権限

トラブルシューティング

よくある問題と解決策

1. GitHub認証エラー

Error: GitHub token is required

解決策:

• GitHub Personal Access Tokenが正しく設定されているか確認
• トークンにrepoスコープが含まれているか確認
• 環境変数GITHUB_TOKENまたは--tokenオプションを使用

2. リポジトリアクセスエラー

Error: Invalid repository format

解決策:

• リポジトリ名がowner/repo形式になっているか確認
• 対象リポジトリへの書き込み権限があるか確認

3. CSVファイルエラー

Error: Missing required field 'title'

解決策:

• CSVファイルに必須ヘッダーが全て含まれているか確認
• ヘッダー名のスペルミスがないか確認
• ファイルエンコーディングがUTF-8になっているか確認

4. テンプレートエラー

Error: Template file must have .md extension

解決策:

• テンプレートファイルの拡張子が.mdになっているか確認
• ファイルパスが正しいか確認
• ファイルの読み取り権限があるか確認

5. レート制限エラー

Error: Rate limit exceeded

解決策:

• --delayオプションで遅延時間を増やす（デフォルト: 1000ms）
• --batch-sizeオプションでバッチサイズを小さくする（デフォルト: 5）
• 認証済みのトークンを使用（未認証より高いレート制限）

6. 大量データ処理時のタイムアウト

解決策:

• まず--dry-runで問題ないか確認
• バッチサイズを小さくして実行
• ネットワーク環境を確認

デバッグ用オプション

詳細なログを確認するには--verboseオプションを使用：

pagemeta2issue page.csv --verbose --dry-run

設定の確認

現在の設定を確認するには、まずドライランモードで実行：

pagemeta2issue page.csv --dry-run

エラーハンドリング

ツールには以下の堅牢なエラーハンドリング機能が含まれています：

• 🔴 認証エラー: 無効または不足しているトークン
• 🟡 レート制限: バックオフ付きの自動リトライ
• 🔵 ネットワーク問題: 設定可能なリトライ機構
• 🟢 バリデーションエラー: 無効なデータに対する明確なエラーメッセージ

貢献

貢献を歓迎します！お気軽にPull Requestを送ってください。

1. リポジトリをフォーク
2. 機能ブランチを作成 (git checkout -b feature/AmazingFeature)
3. 変更をコミット (git commit -m 'Add some AmazingFeature')
4. ブランチへプッシュ (git push origin feature/AmazingFeature)
5. Pull Requestを作成

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

サポート

問題や質問はGitHub Issuesページをご利用ください。