sync-cli-skill

Sync CLI スキル

git ベースの変更検出を使用して、skills/base44-cli/ スキルを Base44 CLI リポジトリの最新 CLI ソースコードと同期します。

使い方

このスキルが有効になると、次の情報を確認します。

1. CLI ソースフォルダーのパス（必須） - Base44 CLI ソースコードのローカルパス（git リポジトリである必要があります）

仕組み

このスキルは、git を使用して変更を効率的に検出します。

1. CLI_VERSION からローカルに保存されたバージョンを読み取ります（例：v0.0.17）
2. CLI ソースリポジトリと比較して、変更されたコマンドファイルを特定します
3. 実際に変更されたコマンドのみを処理します

手順

ステップ 1：入力情報の収集

利用可能な場合は AskQuestion ツールを使用して、CLI ソースフォルダーのパスをユーザーに尋ねます。利用できない場合は、会話の中で尋ねます。

必須：

• CLI ソースフォルダーのパス（例：~/projects/base44-cli または /Users/me/base44-cli）

ユーザーが最初のプロンプトでこれを指定している場合は、その値を使用します。

ステップ 2：ソースフォルダーの検証と構造の確認

1. 指定されたパスが存在し、git リポジトリであること（.git/ ディレクトリが存在すること）を確認します
2. CLI 関連の内容を含む package.json があることを確認します
3. コマンドディレクトリを確認します。コマンドファイルを含むディレクトリを探します。
   • 一般的なパターン：src/cli/commands/、src/commands/、commands/、lib/commands/
   • .command( または program.command のパターンを含むファイルを探します
4. CLI ソースルートを特定します。コマンドと共有コードの両方を含む親ディレクトリです

以降の手順で使用するため、確認したパスを保存します。

• <commands-path>：コマンドディレクトリのパス（例：src/cli/commands）
• <cli-root>：CLI ソースルートのパス（例：src/cli）

検証に失敗した場合、または構造が明確でない場合は、ユーザーに確認を求めます。

ステップ 3：ローカルバージョンの読み取りと変更の検出

1. スキルリポジトリのルートにある CLI_VERSION から保存済みバージョンを読み取ります（例：v0.0.17）

2. CLI ソースフォルダーで git を使用して、変更されたコマンドファイルを取得します。

   # From the CLI source folder, list command files changed since the stored version
   git diff --name-only <stored-version> HEAD -- <commands-path>
   

   保存済みバージョンのタグが存在しない場合は、次の方法にフォールバックします。

   # List all command files if tag is missing
   git ls-files <commands-path>
   

3. インフラストラクチャの変更を取得します（コマンドを除く CLI ソースルート）。

   # From the CLI source folder, list infra files changed since the stored version
   git diff --name-only <stored-version> HEAD -- <cli-root> | grep -v "<commands-path>"
   

4. 作業を進める前に、確認結果をユーザーに提示します。

   Found X changed command files since vX.X.X:
   - <commands-path>/deploy.ts
   - <commands-path>/entities/push.ts
   - <commands-path>/auth/login.ts
   
   Found Y infrastructure changes (may affect all commands):
   - <cli-root>/utils/api-client.ts
   - <cli-root>/config/defaults.ts
   

5. 変更が検出されない場合（コマンドもインフラストラクチャも変更なし）：「バージョン X 以降、変更はありません」と報告して終了します

ステップ 4：インフラストラクチャの変更を確認

個々のコマンドを処理する前に、すべてのコマンドに影響する可能性のあるインフラストラクチャの変更を確認します。

確認する項目

変更されたコマンド以外の各ファイルを確認し、影響の種類に分類します。

影響の種類	確認する項目	ドキュメントでの対応
API／クライアントの変更	ベース URL、エンドポイント、ヘッダー、リクエスト／レスポンスの処理	複数のコマンドの動作に影響する可能性があります
設定／デフォルト値	デフォルト値、環境変数、設定ファイルのパス	SKILL.md の設定セクションを更新します
認証	トークンの処理、ログインフロー、セッション管理	認証関連の記述を更新します
グローバルオプション	--verbose、--json、--help などの CLI 全体に適用されるフラグ	SKILL.md のグローバルオプションを更新します
出力形式	結果の表示方法、ログの動作	影響を受けるコマンドのリファレンスに記載します
型／インターフェース	共有型定義	通常は内部的なものですが、API の変更を示している可能性があります
エラー処理	終了コード、エラーメッセージ、検証	トラブルシューティングのセクションを更新します
依存関係	package.json の変更	動作に影響する更新がないか確認します

注：実際のファイル構造は CLI によって異なります。特定のパスを想定せず、git diff の出力を調べて構造を確認してください。

インフラストラクチャの変更への対応方法

1. 変更されたインフラストラクチャファイルをそれぞれ読み、変更内容を把握します
2. 横断的な影響を特定します：
   • 新しいグローバルオプション → SKILL.md の「Global Options」セクションを更新します
   • デフォルト値の変更 → 影響を受けるコマンドリファレンスに記載します
   • 認証フローの変更 → 認証関連のリファレンスを更新します
   • 新しい環境変数 → SKILL.md に記載します
   • API エンドポイントの変更 → 複数のコマンドに影響する可能性があります
3. 次の項目に影響する変更は、SKILL.md の更新対象としてフラグを立てます：
   • ユーザーによる CLI の設定方法
   • 前提条件またはセットアップ手順
   • ユーザーに表示される可能性のあるエラーメッセージ
   • 出力形式

インフラストラクチャ変更の例

Changed file: (some config/defaults file)

Before:
  export const DEFAULT_TIMEOUT = 30000;
  
After:
  export const DEFAULT_TIMEOUT = 60000;

Impact: All commands now have 60s timeout instead of 30s
Action: Update SKILL.md "Configuration" or "Troubleshooting" section

ステップ 5：変更された各コマンドを処理する

変更されたコマンドファイルごとに、次の手順を実行します。

ステップ 5a：コマンドを適切なスキルに割り当てる

コマンドは、関心領域ごとに複数のスキルに分けられています。リファレンスを読んだり更新したりする前に、そのコマンドを担当するスキルを特定してください。

既知のコマンドの割り当て：

コマンド	対象スキル	理由
logs	skills/base44-troubleshooter/	トラブルシューティング／デバッグに関するもの
その他すべて	skills/base44-cli/	プロジェクト管理に関するもの

新しいコマンドや不明なコマンドの場合は、そのコマンドの目的に基づいて担当を判断します：

関心領域	対象スキル	例
可観測性、デバッグ、診断、監視	skills/base44-troubleshooter/	logs、monitor、status、health
プロジェクトのセットアップ、リソース管理、デプロイ、認証	skills/base44-cli/	create、deploy、entities push、login

新しいコマンドの目的が曖昧な場合は、ソースコードを読み、**「開発者はアプリの構築や管理にこのコマンドを使うのか、それとも調査やデバッグに使うのか？」**と考えてください。それに応じて割り当てます。明確に判断できない場合は、ユーザーに確認してください。

リファレンスファイルの読み書きには、対象スキルの references/ フォルダーを使用し、そのスキルの SKILL.md にあるコマンドテーブルも更新してください。

ステップ 5b：既存のスキルリファレンスを読む

対象スキルの references/ フォルダーから、対応するリファレンスファイルを読みます：

skills/base44-cli/                      <- project management commands
├── SKILL.md
└── references/
    ├── auth-login.md      <- for <commands-path>/auth/login.ts
    ├── auth-logout.md
    ├── auth-whoami.md
    ├── create.md          <- for <commands-path>/create.ts
    ├── deploy.md
    ├── entities-create.md <- for <commands-path>/entities/create.ts
    ├── entities-push.md
    ├── functions-create.md
    ├── functions-deploy.md
    ├── rls-examples.md
    └── site-deploy.md

skills/base44-troubleshooter/           <- troubleshooting commands
├── SKILL.md
└── references/
    └── project-logs.md    <- for <commands-path>/logs.ts (or similar)

マッピングルール：<commands-path>/{parent}/{name}.ts → references/{parent}-{name}.md

新しいコマンドに対応するリファレンスファイルがない場合は、該当するスキルで作成する項目として記録します。

ステップ 5c：ソースとドキュメントを比較する

CLI のソースコードと既存のスキルドキュメントを比較します：

ソースから情報を抽出する

コマンドファイルを解析し、次の情報を抽出します：

• コマンド名とエイリアス
• 説明／ヘルプテキスト
• 使用可能なオプションとフラグ（名前、エイリアス、説明、デフォルト値、必須かどうか、型）
• 使用例（記載されている場合）
• サブコマンド

変更を検出する

差分を特定します：

コマンドレベル：

1. 新しいコマンド（ソースは存在するが、リファレンスファイルがない）
2. コマンドの説明の変更

オプション／引数レベル（重要）： 3. 新しいオプションの追加 4. オプションの削除 5. オプションの説明の変更 6. オプションのデフォルト値の変更 7. オプションの型の変更（例：文字列からブール値） 8. 必須かどうかの変更 9. オプションのエイリアスの変更（例：-f から -F） 10. オプションから位置引数への変更（例：create -n my-app → create my-app） 11. 位置引数からオプションへの変更（例：create my-app → create -n my-app）

オプションと位置引数の変更を検出する

Commander.js では、次のパターンを確認します：

• 名前付きオプション：.option('-n, --name <value>', 'description') または .requiredOption(...)
• 位置引数：.argument('<name>', 'description') またはコマンド定義内の .command('create <name>')

オプションが削除され、意味の似た位置引数が追加された場合（またはその逆）は、ユーザーによるコマンドの実行方法に影響する破壊的変更としてフラグを立てます。

比較結果を記録する

Command: deploy (<commands-path>/deploy.ts)

Source options:
  --force (-f): Force deployment [boolean, default: false]
  --env <name>: Target environment [string, required]

Documented options (references/deploy.md):
  --force (-f): Force deploy without confirmation [boolean, default: false]  
  --env <name>: Environment name [string, optional]

Changes detected:
  - --force: description changed
  - --env: required status changed (required vs optional)

Command: create (<commands-path>/create.ts)

Source (current):
  Positional: <name> - The app name [required]
  Options: --template (-t): Template to use [string, optional]

Documented (references/create.md):
  Options:
    -n, --name <name>: The app name [string, required]
    --template (-t): Template to use [string, optional]

Changes detected:
  - BREAKING: --name (-n) option converted to positional argument <name>
    Old syntax: npx base44 create -n my-app
    New syntax: npx base44 create my-app

ステップ 5d：リファレンスファイルを更新する

references/{command-name}.md を、次の形式で更新または作成します：

# base44 {command}

{Description from source}

## Syntax

```bash
npx base44 {command} [options]

オプション

オプション	説明	必須
-o, --option <value>	{description}	{yes/no}

例

{example usage from source}

注意事項

{Any important behavioral notes}

### Step 6: Update Main Skill Files (if needed)

After processing all changed commands, update the SKILL.md of each affected skill:

**For `skills/base44-cli/SKILL.md`** (project management commands):
1. Update the **Available Commands** tables if commands were added/removed
2. Update **Quick Start** if workflow changed
3. Update **Common Workflows** sections if relevant

**For `skills/base44-troubleshooter/SKILL.md`** (troubleshooting commands):
1. Update the **Available Commands** table if troubleshooting commands were added/removed
2. Update the **Troubleshooting Flow** if command behavior changed

**General rules:**
- Keep the existing structure and formatting of each skill
- Do NOT change the frontmatter description unless explicitly asked

### Step 6b: Flag base44-sandbox for review

The `skills/base44-sandbox/` skill (the cloud-sandbox flavor) is **hand-authored** and self-contained — it carries its own concise guidelines and links out to `base44-cli`'s references rather than copying them, so this sync does not edit it automatically. If this sync changed the backend-function authoring conventions in `skills/base44-cli/references/functions-create.md` (directory layout, `function.jsonc` shape, entry-point conventions, naming rules), **flag `skills/base44-sandbox/SKILL.md` for manual review** in the summary so its inline guidance can be updated to match.

### Step 7: Update CLI_VERSION and Skill Frontmatter

After successfully updating all changed commands:

1. Get the current version/commit from the CLI source:
   ```bash
   # Get latest tag, or HEAD commit if no tags
   git describe --tags --always

2. skills リポジトリのルートにある CLI_VERSION を新しいバージョンに更新します（例：v0.0.47）。

3. skills/base44-cli/SKILL.md のフロントマターにある metadata.sourcePackage を更新します。name を同期対象の npm パッケージである base44 に、version を v 接頭辞なしの新しいバージョンに設定します（例：0.0.47）。例：

   metadata:
     sourcePackage:
       name: base44
       version: 0.0.47
   

   これにより、インストール済みのスキルが古くなったときに Base44 CLI が検出できるようになります。

ステップ 8：概要を提示する

すべての更新後、ユーザーに概要を提示します。

## Sync Summary

### Version Updated
- Previous: v0.0.17
- Current: v0.0.20

### Changed Command Files Processed
- <commands-path>/deploy.ts
- <commands-path>/entities/push.ts

### Infrastructure Changes Reviewed
- (list infra files from git diff output)
- Example: config.ts (timeout increased to 60s)
- Example: api-client.ts (no user-facing changes)

### Files Updated
- references/deploy.md (updated options)
- references/entities-push.md (updated description)
- SKILL.md (updated command table, added timeout note)
- CLI_VERSION (v0.0.17 → v0.0.20)
- skills/base44-cli/SKILL.md frontmatter metadata.sourcePackage.version (0.0.17 → 0.0.20)

### Breaking Changes (highlight prominently)
- `create`: `-n, --name` option converted to positional argument
  - Old: `npx base44 create -n my-app`
  - New: `npx base44 create my-app`

### Option Changes
- `deploy --env`: now required (was optional)
- `entities push --dry-run`: default changed from true to false

### New Commands
- (none)

### Removed Commands  
- (none)

### Manual Review Recommended
- [List any changes that need verification]

重要な注意事項

• Git ベースの検出：このスキルは変更の検出に Git タグ／コミットを使用します。CLI のソースフォルダーが有効な Git リポジトリであることを確認してください。
• 既存の内容を保持する：古くなっていない限り、詳細な説明、例、警告を削除しないでください。
• 書式を統一する：既存の SKILL.md と参照ファイルのスタイルに合わせてください。
• 段階的な情報開示を維持する：詳細なドキュメントは参照ファイルに、概要は SKILL.md に記載してください。
• 不確かな点を明示する：ソースコードが不明瞭な場合は、手動での確認が必要であることを明記してください。
• RLS/FLS ドキュメントを慎重に扱う：entities-create.md と rls-examples.md には手書きのセキュリティドキュメントが含まれています。慎重に更新してください。

トラブルシューティング

問題	解決策
CLI リポジトリにタグが見つからない	git tag -l を使って利用可能なタグを一覧表示するか、コミットハッシュとの比較に切り替えてください
Infra の変更が検出されない	共有コードが標準以外のディレクトリにあるか確認し、必要に応じて git diff のパスを調整してください
Infra の変更がユーザーに影響するか不明	コマンドファイルで使用されているエクスポートを確認してください。内部専用の場合は記録するだけにして、ドキュメントには反映しないでください
コマンドファイルが見つからない	.command( または program.command のパターンを検索してください
オプションが検出されない	commander.js ファイル内の .option( パターンを検索してください
位置引数が検出されない	.argument( または .command('cmd <argName>') 内の <argName> パターンを検索してください
オプションから位置引数への変更が見落とされた	古いオプション一覧と新しい引数一覧を比較してください。オプションが消え、類似する引数が追加されている場合は、変換された可能性が高いです
説明がない	description: プロパティまたは .description( 呼び出しを確認してください
サブコマンドの構成	entities push のようなコマンドは、entities/push.ts にある場合があります
引数の変更が検出されない	各オプションのプロパティ（名前、エイリアス、説明、デフォルト値、必須かどうか、型）を比較してください
変更があるはずなのに検出されない	CLI_VERSION に保存されたバージョンが、有効な Git タグまたはコミットと一致していることを確認してください