作業報告: GitBucket Issue 双方向同期ツールの作成

1. 作業実施の理由と指示

• 背景: ユーザーより、GitBucketのリモートリポジトリに存在するIssueデータをローカル環境（docs/issues/）にMarkdownとして同期（プルおよびプッシュ）できないかとの要望があった。
• 意図と指示: 単なる一方向のダウンロードだけでなく、ローカルでMarkdownを編集した内容をリモートへ反映（Push）、また新規発行（Create）が行える双方向（2-way）同期スクリプトを構築し、GitBucketをシームレスなローカルIssueトラッカーとして利用可能にすること。

2. 指摘事項とその対応

• 指摘: GitBucketからの全Issue取得と更新の仕組みが必要。
  • 対応: GitHub API互換の https://gitbucket.tmworks.club/api/v3/repos/dtmoyaji/TelosDB/issues エンドポイントに対し、Node.jsの標準 fetch を用いて通信を行う tools/scripts/sync_issues.mjs を作成した。
• 指摘: 双方向の整合性（コンフリクト管理）をどうするか。
  • 対応: 各Markdownの先頭にYAML形式のFrontmatterメタデータ（id, state, title, updated_at）を持たせた。スクリプト実行時にリモート側の updated_at とローカルファイルの更新日時を厳密に比較し、より新しい方を正として上書き（Pull / Push）を行うロジックを実装した。また、id: new として作成されたファイルはPOST通信を行い、新規Issueとして発番からリネームまでを自動処理する仕組みを取り入れた。

3. 作業詳細

AIエージェントは以下の作業を実行した：

• 実装計画（implementation_plan_issues.md）の作成と、タスクリストの定義。
• tools/scripts/sync_issues.mjs の実装。依存モジュール（YAMLパーサー等）を不要にするため、専用の正規表現を用いた軽量なFrontmatter解析ロジックを自作。
• スクリプトのテスト実行を実施し、リモートに存在する既存のIssue2件（Issue-1, Issue-2）を docs/issues/ 内に正確なMarkdownファイルとして生成（Pull）成功した。

4. AI視点での結果

graph LR
    A[docs/issues/*.md] <-->|sync_issues.mjs| B((GitBucket API))
    
    A -->|1. meta: id: new| B1[POST: Create Issue]
    B1 -.-> A1(Rename to Issue-X.md)
    A -->|2. Local is Newer| B2[PATCH: Update Issue]
    B -->|3. Remote is Newer| A2[Write/Overwrite Markdown]

双方向同期スクリプトの完成により、今後開発者はIDE（VS Code等）上で直接MarkdownとしてIssueの閲覧・追記・クローズが可能になった。これによりブラウザとエディタ間を往復する手間が省かれ、開発のフローが劇的に効率化される見込みである。 ※ 注意：リモートへのPush操作を行うには .env に GITBUCKET_TOKEN の設定が必要。