モジュールの公開

公開ではモジュールをパッケージ化し、バージョンまたは可変ラベルをWippy Hubから利用できるようにします。

このページは、公開ワークフローとリファレンスです。acme/* モジュール、URL、トークン、認証情報、サンプルソースは例示用です。所属する組織が所有するリソースに置き換えてください。

前提条件

1. hub.wippy.ai でアカウントを作成する
2. 組織を作成するか、既存の組織に参加する
3. その組織でモジュールを作成する権限を持つ — 最初の wippy publish がモジュールを自動的に登録する

モジュール構造

mymodule/
├── wippy.yaml      # Module manifest
├── src/
│   ├── _index.yaml # Entry definitions
│   └── *.lua       # Source files
└── README.md       # Documentation (optional)

wippy.yaml

wippy.yaml にモジュールのメタデータを定義します。

organization: acme
module: http-utils
type: library
description: HTTP utilities and helpers
license: MIT
repository: https://github.com/acme/http-utils
homepage: https://acme.dev
keywords:
  - http
  - utilities
authors:
  - Acme Engineering <eng@acme.dev>
embed:
  - acme.http:assets
exclude:
  - test/**
  - "*.test.lua"
  - acme.http:debug_handler
exclude_meta:
  stage:
    - experimental
metadata:
  support_url: https://acme.dev/support

exclude は個別のフィールドではなく値の形で振り分けられます。_old/**、test/**、*.test.lua は収集時にソースファイルをフィルタします。acme.http:debug_handler はエントリのデコード後にレジストリエントリを無効化します。** セグメントは任意の数のディレクトリセグメントにまたがります。

type はHubでのモジュール分類を制御し、後から公開する際に変更できます。--module-type フラグは、1回の公開に限りこの値を上書きします。省略した場合、新しく作成されるモジュールは非推奨の警告とともにデフォルトで application になります。

エントリ定義

モジュールのエントリは _index.yaml で定義します。

version: "1.0"
namespace: acme.http

entries:
  - name: definition
    kind: ns.definition
    meta:
      title: HTTP Utilities
      description: Helpers for HTTP operations
    readme: file://README.md
    wiki:
      GUIDE.md: file://docs/GUIDE.md
      examples/auth.md: file://docs/auth.md

  - name: client
    kind: library.lua
    source: file://client.lua
    modules:
      - http_client
      - json

ns.definition の wiki: マップは、READMEとともにドキュメントページを公開します。キーはページパス、値は file:// 参照です。内容はパッキング時にインライン化され、HubからモジュールWikiとして提供されます。

依存関係

他のモジュールへの依存関係を宣言します。

entries:
  - name: __dependency.wippy.test
    kind: ns.dependency
    meta:
      description: Testing framework
    component: wippy/test
    version: ">=0.3.0"

バージョン制約:

要件

利用者が指定する必要のある設定を定義します。

entries:
  - name: api_endpoint
    kind: ns.requirement
    meta:
      description: API endpoint URL
    targets:
      - entry: acme.http:client
        path: ".meta.endpoint"
    default: "https://api.example.com"

ターゲットは値を注入する場所を指定します。

• entry — 設定対象の完全なエントリID
• path — 値を注入する対象エントリ内のドットパス

default は任意のスカラー型を受け付けます — default: 20 は数値ターゲットに文字列ではなく数値として流れ込みます。同じことは ns.dependency エントリの parameters[].value にも当てはまり、どちらも ${env:NAME} 参照を受け付けます。参照はそのまま保持され、ターゲットエントリのデコード時に解決されます。

利用者はオーバーライドを通じて対象を設定できます。-o フラグは namespace:entry:field=value 形式の値を受け取ります。

wippy run -o acme.http:client:meta.endpoint=https://custom.api.com

インポート

他のエントリを参照します。

- name: handler
  kind: function.lua
  source: file://handler.lua
  modules:
    - json
  imports:
    client: acme.http:client           # Same namespace
    utils: acme.utils:helpers          # Different namespace
    base_registry: :registry           # Built-in

Luaでは次のように使用します。

local client = require("client")
local utils = require("utils")

コントラクト

公開インターフェースを定義します。

- name: http_contract
  kind: contract.definition
  meta:
    name: HTTP Client Contract
  methods:
    - name: get
      description: Perform GET request
    - name: post
      description: Perform POST request

- name: http_contract_binding
  kind: contract.binding
  contracts:
    - contract: acme.http:http_contract
      methods:
        get: acme.http:get_handler
        post: acme.http:post_handler

公開ワークフロー

1. 認証

wippy auth login

2. 準備

wippy init
wippy update
wippy lint

3. 検証

wippy publish --dry-run

公開処理は --dry-run の有無にかかわらず同じ方法でパックをビルドするため、検証は実際の公開が生成するすべてを対象とします:

• organization と module は小文字の英数字と内部のハイフンで構成されなければならず、version は semver、type は4つのモジュールタイプのいずれかでなければなりません。
• publish.runtime はアプリケーション所有です。type: application なしにその下で source、sections、vars を宣言すると失敗します。
• meta.artifact.format を宣言するすべてのリソースは、そのフォーマットによって検査されます。不正なアーティファクトは消費側ではなくここで失敗し、出力先ディレクトリが重複する2つのアーティファクトは拒否されます。
• node-package フォーマットはさらに、package.json が公開されるモジュールのバージョンと等しいセマンティックな version と、有効なパッケージ name を持ち、preinstall、install、postinstall、prepare のライフサイクルスクリプトを持たないことを要求します。

リリース時に問題になりやすいのは最後の規則です。wippy.yaml とアーティファクトの package.json の version を揃えて上げないと、公開は中断します。

4. 公開

wippy publish --version 1.0.0

リリースノート付き：

wippy publish --version 1.0.0 --release-notes "Initial release"

追加フラグ

静的ファイルの埋め込み

fs.directory エントリ（静的アセット、テンプレート、公開ファイル）を含むモジュールは、それらを公開パッケージに含めるために --embed を使用する必要があります。これがない場合、fs.directory エントリはディレクトリの内容を伴わずにパックされます。

wippy publish --version 1.0.0 --embed app:public_files
wippy publish --version 1.0.0 --embed app:assets,app:templates

マニフェストのリストと --embed フラグは、fs.directory エントリに一致するエントリIDまたは名前を受け付けます。同じCLIフラグは wippy pack でも使用でき、CLIでの選択はその呼び出しに限りマニフェストのリストを上書きします。

初回公開

初回公開時、モジュールはデフォルトでprivateとしてHubに登録され、公開が1回再試行されます。公開前に登録してプロパティを設定するには --create を使用します。

wippy publish --create --version 0.1.0 \
  --module-visibility public \
  --module-type library \
  --module-display-name "HTTP Utils"

--create は冪等です。すでに登録済みのモジュールでは作成ステップは何も行いません。アカウントが組織内でモジュールを作成できない場合、Hubは公開せず権限エラーを返します。

ローカルハブへの公開

--registry をローカルで動作しているハブに向けると、公開とインストールをパブリックレジストリなしで行えます。プレーン HTTP はローカルホストに対してのみ許可されます — localhost、127.0.0.1、およびコンテナエイリアスの host.docker.internal（Docker Desktop / OrbStack）と host.containers.internal（Podman）。それ以外のホストは HTTPS を使用する必要があります。

wippy auth login --registry http://localhost:8080 --token wpy_xxx
wippy publish --registry http://localhost:8080 --create --version 0.1.0

レジストリとトークンは、環境変数 WIPPY_REGISTRY および WIPPY_TOKEN から取得することもできます。未設定の場合、レジストリはデフォルトで https://hub.wippy.ai になります。

クォータ

組織のプライベートモジュールクォータが使い切られている場合、公開は cannot publish: Private-module quota exhausted (5 of 5)... のようなメッセージで失敗します。モジュールを public にするか、組織管理者にクォータの引き上げを依頼してください。アップロードとダウンロードは、一時的なネットワークエラー時に自動でリトライされます。

公開時のランタイムデフォルト {#publishing-runtime-defaults}

type: application のアプリケーションは、wippy.yaml の publish.runtime を通じて、ランタイム設定のデフォルトをパックに含めることができます。

type: application
publish:
  runtime:
    source: .wippy.yaml            # default: .wippy.yaml
    sections: [security, registry, override]
    vars: [public_url]

ルール：

• パックされるのは、選択されたセクションまたは公開されるプロファイルから参照される変数のみです（推移的に辿られます）。それ以外はすべて vars エントリが必要です。
• エクスポートされる設定内の ${env:...} 参照は拒否されます — 公開者の環境がパックに漏れることはありません。
• マシンローカルのセクション boot、extensions、workspace はエクスポートできません。
• ホストのランタイムデフォルトを提供するのはメインのアプリケーションパックのみで、依存パック内のランタイムメタデータは無視されます。

利用先での設定優先順位は、アプリケーションパックのデフォルト、ランタイムデフォルト、ローカル設定ファイル、選択したプロファイル、最後にCLIオーバーライドの順です。

プロファイルの公開 {#publishing-profiles}

ルートアプリケーションのプロファイルは、パックの runtime.profiles メタデータにエクスポートされます。公開時にプロファイルが選択されたり焼き込まれたりすることはありません — 利用者が実行時に wippy run --profile <name> で選択します：

publish:
  profiles:
    enabled: true
    source: config/profiles.yaml   # default: .wippy.yaml
    include: [production]          # omit to publish all non-workspace profiles

include: [] では何も公開されず、未知の名前を指定すると公開に失敗します。workspace サブセクションは、公開されるプロファイル内にあってもエクスポートされません。プロファイルの宣言については、設定を参照してください。

公開モジュールの利用

依存関係の追加

wippy add acme/http-utils
wippy add acme/http-utils@1.0.0
wippy install

要件の設定

ランタイム時に値をオーバーライドします：

wippy run -o acme.http:client:meta.endpoint=https://my.api.com

または .wippy.yaml 内：

override:
  acme.http:client:meta.endpoint: "https://my.api.com"

コードでのインポート

# your src/_index.yaml
entries:
  - name: __dependency.acme.http
    kind: ns.dependency
    component: acme/http-utils
    version: ">=1.0.0"

  - name: my_handler
    kind: function.lua
    source: file://handler.lua
    imports:
      http: acme.http:client

サンプルモジュール

wippy.yaml:

organization: acme
module: cache
type: library
description: In-memory caching with TTL
license: MIT
keywords:
  - cache
  - memory

src/_index.yaml:

version: "1.0"
namespace: acme.cache

entries:
  - name: definition
    kind: ns.definition
    meta:
      title: Cache Module

  - name: cache
    kind: library.lua
    source: file://cache.lua
    modules:
      - time

src/cache.lua:

local time = require("time")

local cache = {}
local store = {}

function cache.set(key, value, ttl)
    store[key] = {
        value = value,
        expires = ttl and (time.now():unix() + ttl) or nil
    }
end

function cache.get(key)
    local entry = store[key]
    if not entry then return nil end
    if entry.expires and time.now():unix() > entry.expires then
        store[key] = nil
        return nil
    end
    return entry.value
end

return cache

公開:

wippy init
wippy update
wippy lint
wippy publish --version 1.0.0

関連項目

• CLIリファレンス — 公開コマンドとフラグ
• エントリ種別 — モジュールと依存関係のエントリ
• 設定 — ランタイム設定とプロファイル