diff --git a/docs/cli/configuration/plugins.mdx b/docs/cli/configuration/plugins.mdx index 7c352ab0a..b881c9013 100644 --- a/docs/cli/configuration/plugins.mdx +++ b/docs/cli/configuration/plugins.mdx @@ -170,9 +170,7 @@ A plugin can only exist at one scope. To change scope, uninstall first and reins Plugins are versioned by Git commit hash, not semantic version. When you update a plugin, Droid fetches the latest commit from the marketplace repository. - -Version pinning is not supported. Updates always fetch the latest version from the marketplace. - +To pin a marketplace to a specific version, set `ref` (a branch or tag) or `sha` (a full 40-character commit SHA) on the marketplace source. See [Pinning a marketplace to a ref or commit](#pinning-a-marketplace-to-a-ref-or-commit) below. ## Marketplaces @@ -240,6 +238,45 @@ The installation scope depends on where the setting is defined: - User settings → `user` scope - Project settings → `project` scope +### Pinning a marketplace to a ref or commit + +By default Droid tracks the marketplace's default branch and pulls the latest commit on update. You can pin a marketplace to a specific Git ref or commit by adding `ref` or `sha` to the source object. + +| Field | Type | Description | +|-------|------|-------------| +| `ref` | string | Branch or tag to track (e.g. `"main"`, `"v1.2.0"`, `"staging"`). | +| `sha` | string | Full 40-character commit SHA. When set, the marketplace stays on this exact commit and `droid plugin marketplace update` is a no-op. | + +`ref` and `sha` are supported on the `github`, `url`, and `git-subdir` source types. Use `sha` for hard pins; use `ref` to follow a branch or tag. + +```json +{ + "extraKnownMarketplaces": { + "your-org-internal-plugins": { + "source": { + "source": "github", + "repo": "your-org/internal-plugins", + "ref": "v1.2.0" + } + }, + "your-org-frozen-plugins": { + "source": { + "source": "github", + "repo": "your-org/internal-plugins", + "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b" + } + } + } +} +``` + +From the CLI, pass `--ref` or `--sha` when adding a marketplace: + +```bash +droid plugin marketplace add https://github.com/your-org/internal-plugins --ref v1.2.0 +droid plugin marketplace add https://github.com/your-org/internal-plugins --sha 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b +``` + ## Discovering plugins ### Official Factory plugins diff --git a/docs/enterprise/enterprise-plugin-registry.mdx b/docs/enterprise/enterprise-plugin-registry.mdx index e4ec07931..f61b94e26 100644 --- a/docs/enterprise/enterprise-plugin-registry.mdx +++ b/docs/enterprise/enterprise-plugin-registry.mdx @@ -207,13 +207,39 @@ Pre-installed plugins: Plugins are versioned by Git commit hash. When a plugin is updated, Droid fetches the latest commit from the marketplace. -To control versions, use Git branches: -- `main` - Production-ready for all users -- `staging` - For early adopters -- `dev` - For internal testing +To control versions, pin the marketplace source itself with `ref` (branch or tag) or `sha` (full commit SHA): + +```json +{ + "extraKnownMarketplaces": { + "acme-corp-plugins": { + "source": { + "source": "github", + "repo": "your-org/droid-plugins", + "ref": "v2.4.0" + } + }, + "acme-corp-plugins-frozen": { + "source": { + "source": "github", + "repo": "your-org/droid-plugins", + "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b" + } + } + } +} +``` + +Common patterns: +- `ref: "main"` — production-ready for all users (default behavior) +- `ref: "staging"` — early-adopter channel +- `ref: "v1.2.0"` — pin to a release tag +- `sha: "<40-char SHA>"` — hard pin to a specific commit; `droid plugin marketplace update` is a no-op + +See [Plugins · Pinning a marketplace to a ref or commit](/cli/configuration/plugins#pinning-a-marketplace-to-a-ref-or-commit) for the full source schema. -Version pinning via the `version` field is not currently supported. The field is for documentation only. +Version pinning via the per-plugin `version` field is not currently supported. To pin a plugin's version, pin the marketplace it lives in via `ref` or `sha`. ## Private repository access diff --git a/docs/enterprise/hierarchical-settings-and-org-control.mdx b/docs/enterprise/hierarchical-settings-and-org-control.mdx index edb0bd097..fc9b267cd 100644 --- a/docs/enterprise/hierarchical-settings-and-org-control.mdx +++ b/docs/enterprise/hierarchical-settings-and-org-control.mdx @@ -206,13 +206,25 @@ Below is the full schema for org-managed settings. These are configured by org a GitHub repository in `owner/repo` format. + + Optional Git branch or tag to track (e.g. `"main"`, `"v1.2.0"`). + + + Optional full 40-character commit SHA. When set, the marketplace is pinned to this exact commit. + Must be `"url"`. - URL of the marketplace manifest. + Git repository URL of the marketplace (e.g. `https://gitlab.com/company/plugins.git`). + + + Optional Git branch or tag to track. + + + Optional full 40-character commit SHA to pin to. diff --git a/docs/guides/building/building-plugins.mdx b/docs/guides/building/building-plugins.mdx index f8e6ab5e8..ec2dd998c 100644 --- a/docs/guides/building/building-plugins.mdx +++ b/docs/guides/building/building-plugins.mdx @@ -340,7 +340,7 @@ Use semantic versioning in your plugin manifest for documentation purposes: - **Patch** (1.0.0 → 1.0.1): Bug fixes -Droid tracks plugin versions by Git commit hash, not semantic version. When users update a plugin, they always get the latest commit from the marketplace. Version pinning is not currently supported. +Droid tracks plugin versions by Git commit hash, not semantic version. By default, updating a plugin fetches the latest commit from the marketplace. To pin a plugin to a specific version, pin the marketplace it lives in by setting `ref` (branch or tag) or `sha` (full commit SHA) on the marketplace source — see [Pinning a marketplace to a ref or commit](/cli/configuration/plugins#pinning-a-marketplace-to-a-ref-or-commit). ## Claude Code compatibility diff --git a/docs/jp/cli/configuration/plugins.mdx b/docs/jp/cli/configuration/plugins.mdx index 76ea95e83..60fe31cd8 100644 --- a/docs/jp/cli/configuration/plugins.mdx +++ b/docs/jp/cli/configuration/plugins.mdx @@ -158,9 +158,7 @@ my-plugin/ プラグインはセマンティックバージョンではなく、Gitコミットハッシュによってバージョニングされます。プラグインを更新すると、Droidはマーケットプレイスリポジトリから最新のコミットを取得します。 - -バージョン固定はサポートされていません。更新では常にマーケットプレイスから最新バージョンを取得します。 - +マーケットプレイスを特定のバージョンに固定するには、マーケットプレイスソースに `ref`（ブランチまたはタグ）または `sha`（40文字のフルコミットSHA）を設定します。下記の[マーケットプレイスをrefまたはコミットに固定する](#%E3%83%9E%E3%83%BC%E3%82%B1%E3%83%83%E3%83%88%E3%83%97%E3%83%AC%E3%82%A4%E3%82%B9%E3%82%92ref%E3%81%BE%E3%81%9F%E3%81%AF%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%99%E3%82%8B)を参照してください。 ## マーケットプレイス @@ -222,6 +220,45 @@ Droidが起動すると、自動的に以下を実行します： - ユーザー設定 → `user`スコープ - プロジェクト設定 → `project`スコープ +### マーケットプレイスをrefまたはコミットに固定する + +デフォルトでは、Droidはマーケットプレイスのデフォルトブランチを追跡し、更新時に最新のコミットを取得します。ソースオブジェクトに `ref` または `sha` を追加することで、マーケットプレイスを特定のGit refまたはコミットに固定できます。 + +| フィールド | 型 | 説明 | +|-------|------|-------------| +| `ref` | string | 追跡するブランチまたはタグ（例: `"main"`、`"v1.2.0"`、`"staging"`）。 | +| `sha` | string | 40文字のフルコミットSHA。設定すると、マーケットプレイスはこのコミットに固定され、`droid plugin marketplace update` は何も行いません。 | + +`ref` と `sha` は `github`、`url`、`git-subdir` ソースタイプでサポートされています。ハードピンには `sha`、ブランチやタグを追跡するには `ref` を使用します。 + +```json +{ + "extraKnownMarketplaces": { + "your-org-internal-plugins": { + "source": { + "source": "github", + "repo": "your-org/internal-plugins", + "ref": "v1.2.0" + } + }, + "your-org-frozen-plugins": { + "source": { + "source": "github", + "repo": "your-org/internal-plugins", + "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b" + } + } + } +} +``` + +CLIからマーケットプレイスを追加する際は、`--ref` または `--sha` を渡します： + +```bash +droid plugin marketplace add https://github.com/your-org/internal-plugins --ref v1.2.0 +droid plugin marketplace add https://github.com/your-org/internal-plugins --sha 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b +``` + ## プラグインの発見 ### 公式Factoryプラグイン diff --git a/docs/jp/enterprise/enterprise-plugin-registry.mdx b/docs/jp/enterprise/enterprise-plugin-registry.mdx index bb3ea8fba..c70361add 100644 --- a/docs/jp/enterprise/enterprise-plugin-registry.mdx +++ b/docs/jp/enterprise/enterprise-plugin-registry.mdx @@ -207,13 +207,39 @@ plugins/ プラグインはGitコミットハッシュでバージョン管理されます。プラグインが更新されると、Droidはマーケットプレイスから最新のコミットを取得します。 -バージョンを制御するには、Gitブランチを使用します： -- `main` - すべてのユーザー向けのプロダクション準備完了 -- `staging` - 早期採用者向け -- `dev` - 内部テスト向け +バージョンを制御するには、マーケットプレイスソース自体に `ref`（ブランチまたはタグ）または `sha`（フルコミットSHA）を設定して固定します： + +```json +{ + "extraKnownMarketplaces": { + "acme-corp-plugins": { + "source": { + "source": "github", + "repo": "your-org/droid-plugins", + "ref": "v2.4.0" + } + }, + "acme-corp-plugins-frozen": { + "source": { + "source": "github", + "repo": "your-org/droid-plugins", + "sha": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b" + } + } + } +} +``` + +一般的なパターン： +- `ref: "main"` — すべてのユーザー向けのプロダクション準備完了（デフォルトの動作） +- `ref: "staging"` — 早期採用者チャンネル +- `ref: "v1.2.0"` — リリースタグに固定 +- `sha: "<40文字のSHA>"` — 特定のコミットへのハードピン；`droid plugin marketplace update` は何も行いません + +完全なソーススキーマについては、[プラグイン · マーケットプレイスをrefまたはコミットに固定する](/jp/cli/configuration/plugins#%E3%83%9E%E3%83%BC%E3%82%B1%E3%83%83%E3%83%88%E3%83%97%E3%83%AC%E3%82%A4%E3%82%B9%E3%82%92ref%E3%81%BE%E3%81%9F%E3%81%AF%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%99%E3%82%8B)を参照してください。 -`version`フィールドによるバージョン固定は現在サポートされていません。このフィールドはドキュメント用です。 +プラグインごとの `version` フィールドによるバージョン固定は現在サポートされていません。プラグインのバージョンを固定するには、`ref` または `sha` を使用してプラグインが含まれるマーケットプレイスを固定してください。 ## プライベートリポジトリアクセス diff --git a/docs/jp/enterprise/hierarchical-settings-and-org-control.mdx b/docs/jp/enterprise/hierarchical-settings-and-org-control.mdx index de1a68911..2e67e2dc4 100644 --- a/docs/jp/enterprise/hierarchical-settings-and-org-control.mdx +++ b/docs/jp/enterprise/hierarchical-settings-and-org-control.mdx @@ -187,6 +187,12 @@ User → ~/.factory/ `owner/repo` 形式のGitHubリポジトリ。 + + 追跡するGitブランチまたはタグ（例: `"main"`、`"v1.2.0"`）。オプション。 + + + 40文字のフルコミットSHA。設定すると、マーケットプレイスはこのコミットに固定されます。オプション。 + @@ -195,6 +201,12 @@ User → ~/.factory/ マーケットプレイスマニフェストのURL。 + + 追跡するGitブランチまたはタグ。オプション。 + + + 固定する40文字のフルコミットSHA。オプション。 + diff --git a/docs/jp/guides/building/building-plugins.mdx b/docs/jp/guides/building/building-plugins.mdx index 2714ea33e..f5c0d2c06 100644 --- a/docs/jp/guides/building/building-plugins.mdx +++ b/docs/jp/guides/building/building-plugins.mdx @@ -340,7 +340,7 @@ my-marketplace/ - **パッチ**（1.0.0 → 1.0.1）：バグ修正 -DroidはプラグインバージョンをセマンティックバージョンではなくGitコミットハッシュで追跡します。ユーザーがプラグインを更新すると、常にマーケットプレイスの最新コミットを取得します。バージョン固定は現在サポートされていません。 +DroidはプラグインバージョンをセマンティックバージョンではなくGitコミットハッシュで追跡します。デフォルトでは、プラグインを更新するとマーケットプレイスから最新のコミットを取得します。プラグインを特定のバージョンに固定するには、マーケットプレイスソースに `ref`（ブランチまたはタグ）または `sha`（フルコミットSHA）を設定して、プラグインが含まれるマーケットプレイスを固定してください。詳細は[マーケットプレイスをrefまたはコミットに固定する](/jp/cli/configuration/plugins#%E3%83%9E%E3%83%BC%E3%82%B1%E3%83%83%E3%83%88%E3%83%97%E3%83%AC%E3%82%A4%E3%82%B9%E3%82%92ref%E3%81%BE%E3%81%9F%E3%81%AF%E3%82%B3%E3%83%9F%E3%83%83%E3%83%88%E3%81%AB%E5%9B%BA%E5%AE%9A%E3%81%99%E3%82%8B)を参照してください。 ## Claude Code互換性 diff --git a/docs/jp/reference/hooks-reference.mdx b/docs/jp/reference/hooks-reference.mdx index 76e4013ba..0fb9fd7ec 100644 --- a/docs/jp/reference/hooks-reference.mdx +++ b/docs/jp/reference/hooks-reference.mdx @@ -411,7 +411,7 @@ Droidセッションが終了するときに実行されます。クリーンア "continue": true, // Whether Droid should continue after hook execution (default: true) "stopReason": "string", // Message shown when continue is false - "suppressOutput": true, // Hide stdout from transcript mode (default: false) + "suppressOutput": true, // フックが終了コード0で終了した場合、フックブロックをチャットビューから非表示にします（デフォルト: false）。詳細トランスクリプト（Ctrl+O）には引き続き表示され、失敗したフック（非ゼロ終了コード）は常に表示されます。 "systemMessage": "string" // Optional warning message shown to the user } ``` @@ -666,7 +666,7 @@ if tool_name == "Read": output = { "decision": "approve", "reason": "Documentation file auto-approved", - "suppressOutput": True # Don't show in transcript mode + "suppressOutput": True # チャットビューからフックブロックを非表示にします（トランスクリプトには表示） } print(json.dumps(output)) sys.exit(0) diff --git a/docs/reference/hooks-reference.mdx b/docs/reference/hooks-reference.mdx index 060a0a2a0..46eb42ad9 100644 --- a/docs/reference/hooks-reference.mdx +++ b/docs/reference/hooks-reference.mdx @@ -436,7 +436,7 @@ All hook types can include these optional fields: "continue": true, // Whether Droid should continue after hook execution (default: true) "stopReason": "string", // Message shown when continue is false - "suppressOutput": true, // Hide stdout from transcript mode (default: false) + "suppressOutput": true, // Hide the hook block from the chat view when the hook exits 0 (default: false). The block is still shown in the detailed transcript (Ctrl+O), and failing hooks (non-zero exit) are always rendered. "systemMessage": "string" // Optional warning message shown to the user } ``` @@ -703,7 +703,7 @@ if tool_name == "Read": output = { "decision": "approve", "reason": "Documentation file auto-approved", - "suppressOutput": True # Don't show in transcript mode + "suppressOutput": True # Hide the hook block from chat view (still in transcript) } print(json.dumps(output)) sys.exit(0)