---
url: /docs/ci.md
---
# CI 連携例

::: tip
近日公開

:::

---

---
url: /docs/cli-reference.md
---
# CLI リファレンス

このページは `motion-plus-installer` CLI の主要オプションと使用例をまとめたリファレンスです。

## 基本

::: tip
ローカルにインストールしている場合は `./node_modules/.bin/motion-plus-installer` を直接利用できます。グローバルにインストールしている場合は `motion-plus-installer --help` で確認してください。
:::

この CLI はサブコマンド方式を採用しています。インストール操作は `install`（エイリアス `i`）サブコマンドを使って明示的に実行してください。

## サブコマンドと主なオプション

* **install** (`i`): 指定パッケージをダウンロードしてインストールします。引数は `pkg@version` 形式で指定します（例: `motion-plus@latest`）。

  * オプション（サブコマンドに付与）:
    * `-s, --storage <subdir>`: ダウンロードキャッシュの保存先（`node_modules` 内のサブディレクトリ）。デフォルト: `.motion-plus-installer`
    * `-t, --token <token>`: API へ渡す Bearer トークン（未指定の場合は環境変数 `MOTION_TOKEN` を参照。未設定だと実行時にエラーになります）。
    * `--keep` / `--no-keep`: ダウンロードした `.tgz` を保持する / 削除する（デフォルト: `--keep`）。
    * `--force`: 既存キャッシュを上書きして再ダウンロードする（デフォルト: false）。
    * `--retry <n>`: ダウンロードの再試行回数（デフォルト: `2`）。
    * `--out <path>`: ダウンロードした `.tgz` を指定パスへ直接出力する（`node_modules` の自動接頭なし）。
    * `--pm-cmd <cmd>`: 使用するパッケージマネージャコマンドを明示（例: `pnpm`, `npm`, `yarn`）。未指定時は自動検出します。
    * `--proxy <url>`: HTTP(S) プロキシを指定（実行時に `HTTP_PROXY` / `HTTPS_PROXY` 環境変数も設定されます）。
    * `-q, --quiet`: ログ出力を抑えて最小化する。
    * `--no-pretty`: 色付けやパス短縮などの「見た目」機能を無効化する。

  ::: warning 高度なオプション

  `-a, --allow-default`: 引数も環境変数も指定されていない場合に限り、デフォルトの `motion-plus@latest` へフォールバックします。通常は使用しないでください。CI などで自動化する場合にのみ明示的に指定してください。

  :::

* **clear-cache** (`cc`): ダウンロードキャッシュ（`.tgz`）を削除します。
  * オプション:
    * `-s, --storage <subdir>`: 対象ストレージを指定（既定: `.motion-plus-installer`）。
    * `--all`: ストレージディレクトリを丸ごと削除する（再帰削除）。
    * `-q, --quiet`: ログ出力を抑える。

その他の共通オプション（グローバル）:

* `-V, --version`: CLI のバージョンを表示します。
* `-h, --help`: ヘルプを表示します（commander 標準）。

## 実行前の確認

* `MOTION_TOKEN` を用意していることを確認してください。`install` 実行時に `--token` を指定するか、環境変数 `MOTION_TOKEN` を設定してください。
* 対象パッケージは `pkg@version` 形式で指定します。バージョンを省略したい場合は `latest` を指定してください（例: `motion-plus@latest`）。
* CI 環境では `MOTION_TOKEN` をシークレットに登録してください。

詳細な環境変数や設定方法については [環境変数と設定](./configuration) を参照してください。

## 実行例

* 最新（latest）をインストール:

```sh
motion-plus-installer install motion-plus@latest
# 省略形
motion-plus-installer i motion-plus@latest
```

* 特定バージョンをインストール:

```sh
motion-plus-installer install motion-plus@2.0.0-alpha.5
```

* キャッシュを削除（デフォルトストレージ内の .tgz を削除）:

```sh
motion-plus-installer clear-cache
```

* ストレージを丸ごと削除:

```sh
motion-plus-installer clear-cache --all
```

実際のコマンド例（`npx` / `pnpm dlx`、`.env` 例、CI スニペットなど）は、サイトの [利用方法](./usage) ページに集約しています。

---

---
url: /docs/what-is-motion-inst.md
---
# Motion Inst とは何ですか？ {#what-is-motion-inst}

Motion Inst は、Motion+ パッケージ群を安全かつ簡単に取得・インストールするための軽量なインストーラ／ランタイム補助ツールです。開発者や CI ワークフロー向けに設計され、手動での複雑な手順や依存関係の扱いを自動化します。

::: tip
まずは試してみたい？ [クイックスタート](./getting-started) へどうぞ。

:::

## 目的

* パッケージの取得とインストール手順を自動化して開発者の負担を減らす
* ダウンロード元とアーティファクトの検証を導入してセキュリティを高める
* 軽量で移植しやすい CLI を提供し、スクリプト／CI へ組み込みやすくする

## 主な特徴

* インストール自動化: 複数の Motion+ パッケージを一括で取得・展開し、必要なフックを呼び出します。
* セキュリティ重視: 署名やチェックサム検証のフローを想定しており、改ざん検知や信頼できる配布経路の利用を支援します。
* 軽量: 依存を最小限に抑えた実装により、CI やスクリプト内で高速に動作します。
* CLI フレンドリー: シンプルなコマンド体系で手動操作と自動化の両方に適します。

## 想定ユースケース

* 開発マシンでの素早いセットアップ（例: 開発用ツールやテンプレートの導入）
* CI/CD パイプラインでのパッケージ取得とインストール自動化
* オフラインやミラー配布環境での安全な配布ワークフロー

## 設定とカスタマイズ

* Motion Inst は設定ファイルや環境変数で挙動をカスタマイズできるよう設計されています。ダウンロード先、キャッシュの場所、検証方法（署名/チェックサム）などをプロジェクトごとに調整してください。

## セキュリティについて

* 常に公式の配布元や署名済みアーティファクトを優先して利用してください。
* CI での実行時はキャッシュと検証を組み合わせ、不正なアーティファクトが混入しないようにしてください。

## 貢献とフィードバック

* 不具合や改善要望は GitHub リポジトリの Issue や Pull Request で受け付けています。ドキュメントや例が不足している場合もお気軽に報告してください。

詳細は [利用方法](./usage)、[CLI リファレンス](./cli-reference)、[環境変数と設定](./configuration) を参照してください。

---

---
url: /contributors.md
---


---

---
url: /docs/getting-started.md
---
# クイックスタート {#getting-started}

このページでは、`motion-plus-installer` のインストールと基本的な使い方を示します。

## 実行例（参照）

このページの具体的なコマンド例（`npx` / `pnpm dlx`、`.env` を使った実行、CI スニペットなど）は重複を避けるためサイトの [利用方法](./usage) ページにまとめています。

## CI での利用

CI では `MOTION_TOKEN` をシークレットとして保存し、ビルド手順の中で `npx motion-plus-installer` を呼び出してください。例（GitHub Actions のステップ）:

```yaml [install.yml]
- name: Install Motion packages
  run: npx motion-plus-installer i motion-plus
  env:
    MOTION_TOKEN: ${{ secrets.MOTION_TOKEN }}
```

## パッケージマネージャーの明示

自動検出が上手くいかない場合は、`--pm-cmd <cmd>` オプションで実行コマンドを明示できます。簡単な例や置換例は [利用方法](./usage) にあります。

詳細は [CLI リファレンス](./cli-reference) と [パッケージマネージャ検出](./pm-detection) を参照してください。

---

---
url: /docs/contributing.md
---
# コントリビュート方法

::: tip
近日公開

:::

---

---
url: /docs/security.md
---
# セキュリティと運用上の注意

このページは `motion-plus-installer` を安全に運用するための実務的な注意点をまとめます。トークンやダウンロードキャッシュの扱い、CI での運用ポリシーに焦点を当てています。

## トークンの管理

* **環境変数で渡す**: `MOTION_TOKEN` を使用し、値は直接コミットしないでください。
* **CI ではシークレットを利用**: GitHub Actions / GitLab CI 等のシークレット機能に格納し、ジョブ内で環境変数として注入してください。
* **短命トークンを推奨**: 可能であれば短期間でローテーション可能なトークンを使い、漏洩リスクを下げます。

## ログと出力の扱い

* CLI はトークンの実値をログに出力しません（値はマスクされます）が、コマンドライン履歴や CI のログに露出しないよう注意してください。
* `--no-pretty` を使うと色つきやパス短縮が無効になり、ログのフォーマットがプレーンになります（デバッグ用途）。

## ダウンロードキャッシュと .gitignore

* デフォルトでダウンロードした `.tgz` は `node_modules/.motion-plus-installer/` に保存されます。リポジトリに含めないよう `.gitignore` を確認してください。
* 機密を含むファイルを意図せずコミットしないため、CI ステップやスクリプトで `.git` 関連の操作を行う際は注意してください。

## 最小権限とアクセス制御

* トークンに付与する権限は最小限にしてください。ダウンロードのみ許可するスコープを用意できる場合はそれを使います。
* レジストリのアクセス制御（IP 制限、クライアント証明書）を組み合わせると保護が強化されます。

## トークン漏洩時の対処

1. 影響を受けるトークンを直ちに無効化/失効させる。
2. 監査ログを確認して不正なダウンロードや API 呼び出しがないか確認する。
3. 新しいトークンを発行し、関係システムで更新する。

## CI パイプラインでの推奨設定（例）

::: tip
GitHub Actions の例（シークレットに `MOTION_TOKEN` を登録）

```yaml
- name: Run installer
  env:
    MOTION_TOKEN: ${{ secrets.MOTION_TOKEN }}
  run: npx motion-plus-installer i motion-plus
```

:::

## その他のヒント

* `--no-keep` を CI の実行で使うと、ジョブ終了後に `.tgz` を残さずクリーンにできます。
* ダウンロードしたファイルに機密情報が含まれる設計の場合は、保存先のアクセス制御とライフサイクル（自動削除）を検討してください。

***

### 関連ページ

* [環境変数と設定](./configuration)
* [利用方法](./usage)

---

---
url: /docs/troubleshooting.md
---
# トラブルシューティング

このページはよくある問題とその対処法をまとめています。問題が解決しない場合は、エラーメッセージを元にさらに調査してください。

## 認証エラー（401 / トークン関連）

::: warning
`MOTION_TOKEN` または `--token` が未設定の場合、CLI は実行を中断します。
:::

* 対処:
  * 環境変数 `MOTION_TOKEN` が正しく設定されているか確認します。
  * CI 環境ではシークレットに登録されているか確認してください（例: GitHub Secrets）。
  * トークンが期限切れでないか、アクセス権が正しいかを確認します。

## ネットワーク / プロキシ関連の失敗

* 症状: ダウンロードで `ECONNREFUSED` やタイムアウト、SSL エラーが出る。
* 対処:
  * 環境変数 `HTTP_PROXY` / `HTTPS_PROXY` を設定するか、`--proxy <url>` を指定してください。
  * 社内プロキシ環境ではプロキシの認証や証明書の設定を確認してください。

## ダウンロード失敗（再試行）

* CLI は `--retry`（デフォルト 2）で再試行します。ネットワークが不安定な場合は増やしてください。

```sh
npx motion-plus-installer --retry 5
```

## `require is not defined` や ESM/CJS のエラー

* 症状: Node 実行時に ESM/CJS の互換エラーが出る。
* 対処:
  * 配布版はビルド済みの CommonJS を想定しています。リポジトリのソースを直接実行する場合は `pnpm run build` を行ってから試してください。

## パッケージマネージャ検出の問題（自動検出が期待通りに動かない）

* 症状: `--pm-cmd` を指定していないのに意図しないマネージャが使われる。
* 対処:
  * CI では明示的に `--pm-cmd pnpm`（あるいは `npm`）を指定してください。詳細は [パッケージマネージャ検出](./pm-detection) を参照してください。
  * ローカルでは `package.json#packageManager` フィールドやロックファイル（`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`）の存在で検出されます。必要に応じてロックファイルを確認してください（関連: [パッケージマネージャ検出](./pm-detection)／[CLI リファレンス](./cli-reference)）。

## 権限エラー（ファイルシステム）

* 症状: 出力先に書き込めない、`EPERM`、`EACCES` エラー。
* 対処:
  * `--out` を使用して書き込み可能なパスを指定するか、`node_modules` 配下の書き込み権限を確認してください。
  * グローバルインストール・グローバル実行では管理者権限が必要になる場合があります。

## それでも解決しない場合

* エラーメッセージと実行コマンド（トークンは含めない）を添えて issue を作成してください。

---

---
url: /docs/pm-detection.md
---
# パッケージマネージャ検出

`motion-plus-installer` は、利用するパッケージマネージャー（例: `pnpm`, `npm`, `yarn`, `bun`）を自動検出して、ダウンロードした `.tgz` をプロジェクトへ追加します。

このページでは検出の順序と、意図したマネージャーを使うための対処法を説明します。

## 検出の優先順位

自動検出は以下の順序で行われます（上位が優先）。

1. 環境変数 `npm_config_user_agent` の解析
2. 環境変数 `npm_execpath` の解析
3. プロジェクトの `package.json` の `packageManager` フィールド
4. ロックファイルの存在確認（`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`）
5. 実行可能ファイルの存在チェック（`pnpm`, `yarn`, `bun` を順に確認）
6. 上記どれにも当てはまらない場合は `npm` を選択

このロジックにより、ローカル環境や CI 環境で一般的に使われているマネージャーを高い精度で推測できます。

## 各ステップの説明

* `npm_config_user_agent` / `npm_execpath`:
  * Node 実行時に設定される npm/Yarn/PNPM のユーザーエージェントや実行パスを参照します。npx や pnpm dlx 経由での実行時に有用です。
* `package.json` の `packageManager`:
  * 例: `"packageManager": "pnpm@8.0.0"` のように設定されている場合、そのマネージャーを優先します。
* ロックファイル:
  * リポジトリに残っているロックファイルから明示的に判定します（`pnpm-lock.yaml` → `pnpm`、`package-lock.json` → `npm`、`yarn.lock` → `yarn`、`bun.lockb` → `bun`）。
* 実行可能ファイルの有無チェック:
  * ローカル環境に `pnpm`/`yarn`/`bun` がインストールされているか `--version` 実行で確認します。

::: tip 推奨
自動検出が期待通りでない場合や CI 環境で確実に特定のマネージャーを使いたい場合は、CLI オプション `--pm-cmd <cmd>` を指定してください（例: `--pm-cmd pnpm`）。
:::

::: code-group

```sh [pnpm]
# pnpm を使う例
pnpm dlx motion-plus-installer i motion-plus --pm-cmd pnpm
```

```sh [npm]
# npm を使う例
npx motion-plus-installer i motion-plus --pm-cmd npm
```

```sh [yarn]
# yarn を使う例
yarn dlx motion-plus-installer i motion-plus --pm-cmd yarn
```

:::

::: details 実行後に呼ばれるコマンド
インストーラは検出したマネージャーに応じて以下のように `.tgz` をプロジェクトに追加します。

* `pnpm`, `yarn` の場合: `pnpm add ./path/to/file.tgz` / `yarn add ./path/to/file.tgz`
* `npm` の場合: `npm install ./path/to/file.tgz`

(内部では、指定した `--pm-cmd` の先頭トークンをコマンド名として解析し、サブコマンドは上記のように組み立てられます。）

:::

::: warning CI の注意
CI では環境が固定されているため、明示的に `--pm-cmd` を指定することを推奨します。特に `node` イメージやランナーが複数のパッケージマネージャを含む場合、検出結果が変わることがあります。

例（GitHub Actions）:

```yaml
- name: Install Motion package
  run: npx motion-plus-installer i motion-plus --pm-cmd pnpm
  env:
    MOTION_TOKEN: ${{ secrets.MOTION_TOKEN }}
```

:::

::: tip トラブルシュート
検出結果を知りたい場合は、`--pm-cmd <cmd>` を指定して明示的に実行ログを確認してください。

まれに、`npm_config_user_agent` が空で `package.json` に `packageManager` が設定されていないと、グローバルにインストールされた `pnpm` が優先される場合があります。CI では `--pm-cmd` 指定で回避できます。

:::

***

### 関連

* [CLI リファレンス](./cli-reference)
* [トラブルシューティング](./troubleshooting)

---

---
url: /_plan.md
---
# プラン

このファイルは日本語版ドキュメントのプランです。

## ジャンル分け

VitePress 公式のテンプレートでは、`./guide/*.md` と `./reference/*.md` に分けられています。
このようやフォルダージャンル分けを採用してください。ドキュメントの数が少ない場合は、フォルダージャンル分けをする必要性がないので、
`./docs/*.md` にして、サイドバー上でジャンルを分けるだけでいいです。

## ドキュメントを更新した場合

`docs\config.ts` の `defineAdditionalConfig.sidebar` を更新してください。

## 作成予定のページ

以下は優先度を付けた作成予定ページの一覧です。まずは「必須」3 点を優先し、その後に「重要」「推奨」を実装します。

* **重要**
  * `ci.md` — GitHub Actions 等の CI 組み込み例とシークレット管理の注意点。
  * `pm-detection.md` — パッケージマネージャ検出ロジックの詳細（検出順序の説明、`--pm-cmd` 使用例）。

* **推奨**
  * `faq.md` — 事例ベースの Q\&A。
  * `contributing.md` — 開発への貢献方法、PR テンプレートやローカルの開発フロー。

## 作成済みのページ

* `what-is-motion-inst.md` — プロジェクト概要（サイトに追加済み）

* `getting-started.md` — クイックスタート（サイトに追加済み）

* `cli-reference.md` — CLI オプション表を作成し、サイト向けに整形済み

* `usage.md` — 利用例ページを正規化して、重複を削除済み

* `development.md` — 開発者向け

* `troubleshooting.md` — よくある問題と対処

* `security.md` — トークン/署名/キャッシュ運用に関する注意点。

* `configuration.md` — 環境変数一覧と説明（`MOTION_*` 系）。

---

---
url: /docs/faq.md
---
# よくある質問

::: tip
近日公開

:::

---

---
url: /docs/usage.md
---
# 利用方法 {#usage}

ここではエンドユーザー向けの実例を示します。

## 開発依存としてインストール

::: code-group

```sh [pnpm]
cd /path/to/your-project
pnpm add -D motion-plus-installer
```

```sh [npm]
cd /path/to/your-project
npm install --save-dev motion-plus-installer
```

:::

## 一時的に実行（npx / dlx）

::: code-group

```sh [pnpm]
pnpm dlx motion-plus-installer i motion-plus@latest
```

```sh [npm]
npx motion-plus-installer motion-plus@latest
```

:::

## 環境変数（PowerShell の例）

```sh [PowerShell ~vscode-icons:file-type-powershell~]
$env:MOTION_TOKEN = 'your-token'
```

::: code-group

```sh [pnpm]
pnpm dlx motion-plus-installer i motion-plus@latest
```

```sh [npm]
npx motion-plus-installer i motion-plus@latest
```

:::

## ENV を使う（dotenv-cli）

::: code-group

```sh [pnpm]
pnpm dlx dotenv-cli -e .env -- pnpm dlx motion-plus-installer i motion-plus@latest
```

```sh [npm]
npx dotenv-cli -e .env -- npx motion-plus-installer i motion-plus@latest
```

:::

## CI 例（GitHub Actions）

```yaml
- name: Install CLI
  run: pnpm add --save-dev motion-plus-installer
- name: Run installer
  env:
    MOTION_TOKEN: ${{ secrets.MOTION_TOKEN }}
  run: npx motion-plus-installer i motion-plus@latest
```

::: warning 注意

* `MOTION_TOKEN` は機密情報です。CI ではシークレットとして保存してください（トークンノート参照）。
* `.tgz` の扱い（`--keep` / `--no-keep`）に注意してください。

:::

::: details トークンノート {#token-note}

ローカル検証では `.env` を使うことが便利ですが、本番や CI では必ずシークレットストアを利用してください。

:::

詳細は [CLI リファレンス](./cli-reference) と [環境変数と設定](./configuration) を参照してください。

---

---
url: /docs/configuration.md
---
# 環境変数と設定

このページでは `motion-plus-installer` が参照する主要な環境変数と簡単な説明、設定例をまとめます。

## 主要な環境変数

| 環境変数                     | 説明                                                                                                                        | 既定値                            |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `MOTION_TOKEN`               | API へアクセスするための Bearer トークン。CLI 実行時に未設定だとエラーになります。                                          | （必須）                          |
| `MOTION_PACKAGE`             | デフォルトのパッケージ名。`install` サブコマンドでパッケージ名を指定しない場合に利用されます（例: `motion-plus`）。         | `motion-plus`                     |
| `MOTION_VERSION`             | デフォルトのパッケージバージョン。`install` サブコマンドでバージョンを指定しない場合に利用されます（例: `2.0.0-alpha.4`）。 | `latest`                          |
| `MOTION_STORAGE_SUBDIR`      | ダウンロードキャッシュを保存する `node_modules` 内のサブディレクトリ名。                                                    | `.motion-plus-installer`          |
| `MOTION_REGISTRY_URL`        | ダウンロード先のベース URL。テスト用にローカルのモックサーバを使う場合に便利です。                                          | `https://api.motion.dev/registry` |
| `HTTP_PROXY` / `HTTPS_PROXY` | プロキシ経由でダウンロードする際に設定します。CLI は `--proxy` 指定でも同様に環境変数を利用します。                         | —                                 |

## 設定例

### PowerShell

CLI はサブコマンド方式です。インストール操作は明示的に `install`（エイリアス `i`）サブコマンドを使って実行してください。例: `pkg@version` 形式で指定します。

```sh [PowerShell ~vscode-icons:file-type-powershell~]
$env:MOTION_TOKEN = '****'
$env:MOTION_REGISTRY_URL = 'https://api.motion.dev/registry'
# latest をインストールする例
pnpm dlx motion-plus-installer install motion-plus@latest

# 特定バージョンを指定する例
pnpm dlx motion-plus-installer install motion-plus@2.0.0-alpha.5
```

## 注意点

* 環境変数に機密情報を設定する際は、ログに値が出力されないように注意してください。CI ではシークレット管理機能を使ってください。
* `MOTION_REGISTRY_URL` をテスト用に差し替えるときは、実運用用のトークンや URL を誤って公開しないよう注意してください。

::: warning 補足（デフォルト挙動）

`install` サブコマンドを引数なしで実行した場合、まず環境変数 `MOTION_PACKAGE` / `MOTION_VERSION` が優先されます。両方未設定の場合は通常エラーになります。ハードコードされた `motion-plus@latest` へ自動的にフォールバックするのは、明示的に `--allow-default`（短縮 `-a`）を指定した場合のみです。`--allow-default` は高度なオプションであり、ドキュメントでは基本的に使用を推奨しません。

:::

***

### 関連ページ

* [利用方法](./usage)
* [CLI リファレンス](./cli-reference)

---

---
url: /docs/development.md
---
# 開発者向けドキュメント

このページではパッケージのビルド、テスト、ローカル検証手順を示します。

## ビルド & パック

```sh [PowerShell ~vscode-icons:file-type-powershell~]
cd packages\motion-plus-installer
pnpm install
pnpm run build
pnpm pack
# -> motion-plus-installer-<version>.tgz が生成される
```

## ローカルでのテストプロジェクトで検証

```sh [PowerShell ~vscode-icons:file-type-powershell~]
cd /path/to/test-project
pnpm init -y
pnpm add "C:\path\to\motion-plus-installer-0.1.0.tgz"
.\node_modules\.bin\motion-plus-installer --help
```

## テスト

* ユニットテスト: `pnpm test`（`src` のユーティリティを検証）
* E2E テスト: `MOTION_REGISTRY_URL` を使ってローカルの HTTP サーバでダウンロードの検証を行う。

### 実装ノート（抜粋）

* パッケージマネージャの検出と実行は `src/pm.ts` に実装されています。ユニットテストでは `child_process.spawn` をモックしてください。
* `installer.ts` は CLI オプションのパースと実行フローを担います。

詳細は [パッケージマネージャ検出](./pm-detection) と [CLI リファレンス](./cli-reference) を参照してください。