Templetry

Templetry Engine

Templetry のコアです。コンパイル可能なテンプレートから、すぐに使えるリポジトリを生成する、純粋な Go ライブラリと薄い CLI です。

_{ひな形を生成して編集した後、更新します。テンプレートの新しいコミットは、3方向マージ（ベースのレンダリング結果、プロジェクト、新しいレンダリング結果）されるため、テンプレートの変更が反映され、編集内容も維持されます。小さなフィクスチャテンプレートに対して、実際の CLI で記録したものです（開発を参照）。}

ステータス：🚀 v1 は安定版です（最新リリース） — マニフェスト、ディレクティブ、answers ファイル、レジストリの各スキーマ、および CLI のインターフェースは、互換性ポリシー（ADR-0013）に基づく安定した公開 API です。

v1.0 以降の追加機能：templetry update（3方向マージ）、Docker での templetry verify、遅延ピース（pieces/add）、YAML/TOML パッチ、機能の requires/conflicts と presets、複数 Forge でのテンプレートホスティング（github:、gitlab:、gitea: のソーススキーム）、および templetry-mcp サーバー。v1.10 以降、フォームには分類体系（kinds/languages/frameworks）があり、templetry list で絞り込めます。出力パスはパストラバーサルやプラットフォーム固有の問題から保護されており、ディレクティブスキャナーはファジーテスト済みです。

原則（wikiより）

• エンジンはフレームワークを認識しません — 知識はすべて各テンプレートの template.yml にあります（ADR-0002）。
• テンプレートはコンパイルされます — 3つの変換メカニズムがあります：同一性マップによる名前変更、コメントディレクティブ、構造化パッチ（ADR-0003）。
• 純粋なコアと副作用のある境界 — 決定論的です。同じ入力からは、バイト単位で同一の出力が得られます。

アーキテクチャ

パッケージ	役割
manifest	template.yml を解析・検証し、ケーシングを導出
source	テンプレートをメモリ内の FileSet として取得
planner	(manifest, inputs, FileSet) → Plan — 純粋処理
ops	操作の型をデータとして定義
render	仮想ファイルツリーに対して Plan を実行
verify	Docker でテンプレートの検証コマンドを実行
update	更新サイクル：記録された入力で再レンダリングし、差分を取り、3方向マージ
answers	.templetry-answers.yml の記録：決定論的な読み取り・出力処理を一元化
piece	遅延ピース（ADR-0014）：独自のライフサイクルを持つ疎結合な単位
cmd/templetry	薄い CLI：list、init、plan、render、verify、update、pieces、add、version
cmd/templetry-mcp	MCP サーバー（stdio）：エンジンの動詞を AI エージェント向けのツールとして提供

設計の根拠：study I · study II。

インストール

次のいずれかを選んでください（Homebrew、Scoop、インストールスクリプト、リリースアーカイブには templetry-mcp も含まれています）。

1. Homebrew（macOS、Linux）— brew install Templetry/tap/templetry（tap）。
2. Scoop（Windows）— scoop bucket add templetry https://github.com/Templetry/scoop-bucket の後に scoop install templetry（bucket）。
3. インストールスクリプト（macOS、Linux）— curl -fsSL https://raw.githubusercontent.com/Templetry/engine/main/install.sh | sh（install.shを参照してください。TEMPLETRY_VERSION でタグを指定し、TEMPLETRY_BIN_DIR でインストール先のフォルダーを指定します）。
4. バイナリ — Releasesからお使いのプラットフォーム用の実行ファイルをダウンロードし、templetry（または templetry.exe）に名前を変更して PATH に配置します。
5. Go ツールチェーン — go install github.com/Templetry/engine/cmd/templetry@latest（$(go env GOPATH)/bin にインストールされます）。
6. ソースからビルド — クローンして go build -o templetry ./cmd/templetry を実行します。

次に：

templetry list                                  # browse the official catalog
templetry list --kind database --language go --tags   # filter it
templetry init kmp/single-module --out my-app \
  --set "project_name=My App" --set "base_package=com.me.myapp"
templetry plan --template <dir> --set key=value --feature name
templetry render --template <dir> --out <dir> --set key=value
templetry verify --template <dir> --set key=value    # render to a temp dir and compile it in Docker
templetry update ./my-app                            # preview a template update (--apply to write)
templetry pieces ./my-app                            # lazy pieces the template ships
templetry add axios-api ./my-app --set api_base=/v2  # adopt a piece into a living project

MCP サーバー（AI エージェント）

templetry-mcp（同じリリースに含まれています）は、依存関係や設定なしで、標準入出力を介して Model Context Protocol を使用します。7 つのツール、list_templates、get_form_schema、plan、render、update、list_pieces、add_piece を公開しており、エージェントはカタログを閲覧し、すぐに作業を始められるプロジェクトを生成し、ピースを取り入れて、すべてを最新の状態に保つことができます。一般的なクライアント向けの設定例を以下に示します。このサーバーは通常の実行ファイルなので、ほかの MCP クライアントでも同様に動作します。公式 MCP レジストリには io.github.Templetry/templetry-mcp として登録されており、各リリース後に自動公開されます。

バイナリの場所

templetry-mcp が PATH にある場合は、コマンドに templetry-mcp をそのまま指定してください。一部のアプリ（特に Claude Desktop）はシェルの PATH を引き継がないため、絶対パスを指定してください。

インストール方法	パス
Homebrew、Apple Silicon	/opt/homebrew/bin/templetry-mcp
Homebrew、Intel Mac／Linux	/usr/local/bin/templetry-mcp（Linux の brew：/home/linuxbrew/.linuxbrew/bin/templetry-mcp）
install.sh	~/.local/bin/templetry-mcp（root で実行した場合は /usr/local/bin/templetry-mcp）。JSON にはホームディレクトリのフルパスを記述してください。~ は展開されません
Scoop（Windows）	C:\Users\<you>\scoop\shims\templetry-mcp.exe
ダウンロードしたリリースバイナリ	配置した場所

where templetry-mcp（Windows）または command -v templetry-mcp を実行すると、正しいパスが表示されます。

Claude Code

claude mcp add templetry -- templetry-mcp            # this project, private to you
claude mcp add --scope user templetry -- templetry-mcp   # every project
claude mcp list

Claude Desktop

claude_desktop_config.json を編集し（Settings > Developer > Edit Config。macOS では ~/Library/Application Support/Claude/、Windows では %APPDATA%\Claude\）、アプリを再起動します。

{
  "mcpServers": {
    "templetry": {
      "command": "/opt/homebrew/bin/templetry-mcp"
    }
  }
}

Windows では "command": "C:\Users\<you>\scoop\shims\templetry-mcp.exe" を使用してください。

Cursor

プロジェクトには .cursor/mcp.json、すべてのプロジェクトには ~/.cursor/mcp.json を使用します。

{
  "mcpServers": {
    "templetry": {
      "command": "templetry-mcp"
    }
  }
}

VS Code

ワークスペースの .vscode/mcp.json を使用します（すべてのワークスペースに適用する場合は「MCP: Open User Configuration」を使用します）。キーは mcpServers ではなく servers です。

{
  "servers": {
    "templetry": {
      "type": "stdio",
      "command": "templetry-mcp"
    }
  }
}

このサーバーは引数も環境変数も必要としません。プライベートカタログを使用する場合は、エージェントが各ツール呼び出しで registry を渡します。

ドキュメント

使い方ガイドは Wiki にあります：入門ガイド、テンプレートの使用、ピースの使用、プロジェクトを最新の状態に保つ、テンプレートの作成、AI エージェントと MCP。規範的な動作については spec/ を参照してください。

開発

go build ./...
go test ./...          # CI also runs -race and golangci-lint v2

update は git merge-file を使ってマージするため、テストの実行には git が PATH 上にある必要があります。ネットワークに接続するテストも、Docker が必要なテストもありません。

• internal/forgetest は http.DefaultClient の背後で動作するメモリ内の GitHub（codeload tarball とコミット API）です。テストが公開するテンプレートに対して、コミットごとに init → 編集 → update をエンドツーエンドで実行します。
• internal/fakedocker はテストバイナリのコピーを PATH 上に docker として配置し、verify が実行するはずだった内容を記録します。
• どちらのバイナリもプロセス内でテストします。templetry は run(args, stdout, stderr) を通じて、templetry-mcp はパイプ経由の JSON-RPC セッションである serve(in, out) を通じてテストします。

上記のデモも同じ方法で記録されているため、常に実際の出力が表示されます。再生成するには、次のようにします。

TEMPLETRY_DEMO_CAST=$PWD/docs/demo.cast go test ./cmd/templetry -run TestRecordDemo -count=1
npx [email protected] --in docs/demo.cast --out docs/demo.svg --window --no-cursor

ライセンス

Apache License 2.0 — 明示的な特許許諾が付与されており、商用を含め、あらゆる用途に使用できます。テンプレートとデスクトップアプリは、それぞれ独自のリポジトリで MIT ライセンスのもとに公開されています。