Packs のビルド

概要

Packs は Greentic における配布単位です。このガイドでは、CLI ツールを使って packs を作成、ビルド、署名、公開する方法を説明します。

Pack CLI コマンド

gtc pack

gtc pack <COMMAND>

Commands:
  build     Build a pack from source directory
  verify    Verify pack signature and contents
  info      Display pack metadata
  extract   Extract pack contents
  sign      Sign a pack
  publish   Publish pack to registry

Pack の作成

1. pack のディレクトリ構造を作成する

   mkdir -p my-pack/{flows,components,assets}

2. pack マニフェストを作成する

   my-pack/pack.toml

   [pack]
   name = "my-feature"
   version = "1.0.0"
   description = "My awesome feature pack"
   authors = ["Your Name <you@example.com>"]
   
   [capabilities]
   id = "greentic.cap.app.v1"
   provides = ["my-feature"]
   
   [flows]
   main = "flows/main.ygtc"
   
   [components]
   processor = "components/processor.wasm"
   
   [assets]
   templates = "assets/templates/"

3. flows を追加する

   my-pack/flows/main.ygtc

   name: main
   version: "1.0"
   description: Main flow
   
   nodes:
     - id: process
       type: reply
       config:
         message: "Hello from my pack!"
   
   triggers:
     - type: message
       target: process

4. components を追加する（ある場合）

   WASM components をビルドし、components/ に配置します:

   cd my-component
   cargo build --target wasm32-wasip2 --release
   cp target/wasm32-wasip2/release/my_component.wasm ../my-pack/components/

Packs のビルド

基本的なビルド

gtc pack build ./my-pack

# Output: my-feature-1.0.0.gtpack

オプション付きビルド

# Specify output path
gtc pack build ./my-pack --output ./dist/my-feature.gtpack

# Skip WASM optimization
gtc pack build ./my-pack --no-optimize

# Include debug info
gtc pack build ./my-pack --debug

ビルド出力

• ディレクトリmy-feature-1.0.0.gtpack

  • manifest.cbor
  • ディレクトリflows/

    • main.ygtc
  • ディレクトリcomponents/

    • processor.wasm
  • ディレクトリassets/

    • ディレクトリtemplates/

      • …
  • sbom.json

Packs への署名

注意

配布前には必ず packs に署名してください。未署名の packs は本番環境の runtime で拒否される場合があります。

署名キーを生成する

# Generate new Ed25519 key pair
gtc pack keygen --output my-signing-key

# Creates:
# - my-signing-key.pem (private key - keep secret!)
# - my-signing-key.pub (public key - distribute)

Pack に署名する

gtc pack sign my-feature-1.0.0.gtpack --key my-signing-key.pem

# Output: my-feature-1.0.0.gtpack (updated with signature)

署名を検証する

gtc pack verify my-feature-1.0.0.gtpack --pubkey my-signing-key.pub

# Output: Signature valid

Pack の確認

メタデータを表示する

gtc pack info my-feature-1.0.0.gtpack

出力:

Pack: my-feature
Version: 1.0.0
Description: My awesome feature pack
Authors: Your Name <you@example.com>

Capabilities:
  ID: greentic.cap.app.v1
  Provides: my-feature

Contents:
  Flows: 1
  Components: 1
  Assets: 2 directories

Signature: Valid (signed by: ABC123...)

内容を一覧表示する

gtc pack info my-feature-1.0.0.gtpack --list

# Lists all files in the pack

Pack を展開する

gtc pack extract my-feature-1.0.0.gtpack --output ./extracted/

# Extracts pack contents for inspection

Flow の検証

Flows を検証する

# Validate all flows in a directory
gtc flow doctor ./my-pack/flows/

# Validate specific flow
gtc flow validate ./my-pack/flows/main.ygtc

doctor の出力

gtc flow doctor ./flows/

# Output:
# Checking flows/main.ygtc... OK
# Checking flows/helper.ygtc... OK
#
# 2 flows checked, 0 errors, 0 warnings

よくある検証エラー

Error	原因	修正方法
Unknown node type	無効な node type	利用可能な node types を確認する
Missing target node	edge が存在しない node を指している	node ID の参照を修正する
Circular dependency	nodes が循環を形成している	循環を解消する
No trigger defined	flow にエントリーポイントがない	trigger を追加する

Packs の公開

OCI Registry に公開する

# Login to registry
gtc pack login ghcr.io --username USER --password TOKEN

# Publish pack
gtc pack publish my-feature-1.0.0.gtpack --registry ghcr.io/greentic

Registry から pull する

gtc pack pull ghcr.io/greentic/my-feature:1.0.0

Bundle で使用する

greentic.demo.yaml

apps:
  my-app:
    pack: "oci://ghcr.io/greentic/my-feature:1.0.0"

Pack テンプレート

Provider Pack テンプレート

pack.toml

[pack]
name = "messaging-custom"
version = "1.0.0"
description = "Custom messaging provider"

[capabilities]
id = "greentic.cap.messaging.provider.v1"
provides = ["custom"]

[flows]
setup_default = "flows/setup.ygtc"
verify_webhooks = "flows/verify.ygtc"

[components]
ingress = "components/ingress.wasm"
egress = "components/egress.wasm"
operator = "components/operator.wasm"

[secrets]
required = ["api_key"]
optional = ["webhook_secret"]

Application Pack テンプレート

pack.toml

[pack]
name = "helpdesk-bot"
version = "1.0.0"
description = "IT Helpdesk bot"

[capabilities]
id = "greentic.cap.app.v1"
provides = ["helpdesk"]

[dependencies]
greentic-templates = "^0.4"
greentic-llm-openai = "^0.4"

[flows]
on_message = "flows/on_message.ygtc"
on_ticket = "flows/on_ticket.ygtc"

[assets]
cards = "assets/cards/"
templates = "assets/templates/"

ベストプラクティス

1. セマンティックにバージョン管理する - semver（MAJOR.MINOR.PATCH）を使う
2. すべてのリリースに署名する - 未署名の packs は配布しない
3. SBOM を含める - セキュリティ監査のために依存関係を文書化する
4. 公開前にテストする - flows を検証し、components をテストする
5. 十分に文書化する - pack に README を含める
6. packs は用途を絞る - 1つの pack につき 1つの機能または provider にする
7. CI/CD を使う - ビルドと公開を自動化する

CI/CD の例

.github/workflows/pack.yml

name: Build and Publish Pack

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@1.90.0

      - name: Build Pack
        run: gtc pack build ./my-pack

      - name: Sign Pack
        run: |
          echo "${{ secrets.SIGNING_KEY }}" > key.pem
          gtc pack sign my-feature-*.gtpack --key key.pem

      - name: Publish
        run: |
          gtc pack login ghcr.io --username ${{ github.actor }} --password ${{ secrets.GITHUB_TOKEN }}
          gtc pack publish my-feature-*.gtpack --registry ghcr.io/${{ github.repository }}

次のステップ

• Pack Format Reference - 完全な仕様
• Flow Schema Reference - YAML schema
• Components Guide - WASM components の作成