metainfoは、Webアプリケーションに必要な基本情報を含む伺かを表現するための拡張可能な標準規格です。
ゴーストキャプターさくら(GCS)を例にしましょう。
現在のGCSのバージョンで必要とされる情報アーキテクチャを考えてみましょう。 GCSでゴーストのプレビュー画像をカスタマイズする必要があるとき、ユーザーが使うこともない1つか2つのapngファイルを shell/master に保存する必要があるのです。
これでは、プロジェクトのレイアウトが乱れるだけでなく、用途の異なるファイルが混在することになり、プロジェクトのメンテナンスに支障をきたします。
現在のGCSのバージョンで提供されているリダイレクトは、作者のホームページへのリダイレクトのみで、カスタマイズに欠けることを考慮してください。
metainfoは、これらの問題を解決するために作られました。
ローカルのゴーストフォルダーではないクラウドストレージのディレクトリにmetainfoフォルダーを保存しておくと、最新の状態を保つことができ、ユーザーのローカルストレージスペースを占有しないのでおすすめです。
ゴーストがgithub上で別のプロジェクトを持っている場合、プロジェクトのデフォルトブランチのルートにmetainfoフォルダを格納することを推奨します。
例えば https://github.com/Taromati2/Taromati2 の場合、標準では、metainfo フォルダは https://github.com/Taromati2/Taromati2/tree/master/.ukagaka に格納されます (ここで master はデフォルトのブランチです)
もし、あなたのゴーストがgithub上の別のプロジェクトとmetainfoフォルダを持っているなら、いくつかのウェブアプリケーションがあなたのゴーストを認識できるように、プロジェクトに ukagaka-ghost タグを追加することをお勧めします。
/.ukagaka
├── descript.txt
├── /preview
│ ├── sakura.png
│ └── kero.png
├── icon.png
├── /links
└── /infos
または
/.ukagaka
└── jump_to.txt
descript.txt: ゴーストの説明ファイル、ウェブアプリケーションの基本情報を提供するために使用されます。preview: ゴーストのプレビューフォルダで、ウェブアプリケーションでプレビュー画像を提供するために使用されます (必須ではありません)icon.png: ゴーストのアイコンファイルで、ウェブアプリケーションでアイコンを提供するために使用されます (必須ではありません)links: ゴーストのリンクフォルダ。ウェブアプリケーションで拡張可能で関連性の高いリンク情報を提供するために使用されます（必須ではありません）。infos: ゴーストの情報フォルダ。ウェブアプリケーションで拡張可能な追加情報を提供するために使用されます (必須ではありません)jump_to.txt: 新しいメタ情報フォルダにリダイレクトするためのメタ情報フォルダジャンプファイル（現在のフォルダが非推奨の場合にのみ使用されます。）
previewフォルダにはいくつでもpngファイルを格納できますが、少なくとも2つのpngファイル（それぞれ sakura.png と kero.png という名前）を格納することを推奨します。
動的なプレビューを提供したい場合は、preview フォルダに sakura.apng と kero.apng という名前でそれぞれ保存しておくとよいでしょう。
ゴーストに複数の相方がいる場合は、kero1.png, kero2.png, kero3.png などのように名前を追加することが可能です。
Webアプリケーションの開発者にとっては、previewフォルダ全体がオプションであり、その中にあるコンテンツもオプションであることに注意する必要があります。
descript.txt ファイルの内容は必須であり、UTF8 でエンコードされ、このフォーマットに従ったものでなければならなりません。
//meta info
type,ghost
name,Taromati2
uuid,R5dVNluBvKjtQqjP0dAuoA==
sakura.name,橘花
kero.name,斗和
has_terms,1
icon,https://github.com/Taromati2/other/raw/master/discord_app/kikka_eye_open.png
homeurl,https://raw.githubusercontent.com/Taromati2/stable-mirror/master/Taromati2/
craftman,8 and other contributors
craftmanurl,https://github.com/Taromati2/Taromati2/blob/master/docs/CONTRIBUTORS.md
languages,Simplified Chinese //,Japanese,English may be available in future行末までの :// で始まらない // はコメントとして扱われ、解析されません。
スタートとして //meta info が必要です。
以下のオプションが必要です。
type: 型 (後の標準的な展開のためのもの)、ghost でなければならない
name: 名前
craftman: 製作者
craftmanurl: 制作者へのリンク
uuid: 一意な識別子、詳しくは UUID規格 を参照
languages: ghost がサポートする言語。複数ある場合は , で区切る。
type が ghost である場合、以下のオプションが必要である。
sakura.name: メインキャラの名前
ghostが必ずしもサーバントを持つとは限らないことを考慮して、kero.nameはオプション（必須ではありません）です。
kero.name: 相方 kero1 の名前 (複数の相方がいる場合は kero1.name, kero2.name 等で区別できる)
オプション項目
has_terms: 項目(terms.txt)があるかどうか (ない場合は 0、ある場合は 1、書かれていない場合はデフォルト 0)
icon: アイコンのリンク (未記載の場合、デフォルトは metainfo フォルダにある icon.png (ファイルが存在する場合))
uuid_base: uuidの衝突を防ぐためのuuidベース (詳細は UUID標準 を参照)
linksフォルダには、関連するリンク情報を保持するために、好きなだけtxtファイルを保存することができます。標準では、以下のファイルが指定されています（ただし、必須ではありません）。
mirror_repo.txt: ゴーストファイルの内容がこのリポジトリで更新されない場合、このファイルにミラーリポジトリへのリンクを書くことができます。 リンクは github リポジトリのリンクである必要があります。nar_release_repo.txt: あなたのゴーストのnarファイルがこのリポジトリでリリースされていない場合、このファイルにあなたのnarリリースリポジトリへのリンクを記述することができます。
リンクは github リポジトリのリンクである必要があります。
上記のファイルの内容は、次のように複数の空白行末を持つ単一のURLにすることができます。
nar_release_repo.txt
https://github.com/Taromati2/package-factory
また、より多くの情報やオプションのコメントを含む複雑なものにすることもできる。
この場合、上記のファイルの内容は UTF8 エンコードされるべきであり、行末までの :// で始まらない // はコメントとみなされ、解析されるべきではありません。
nar_release_repo.txt
//a info file to tell the web app where to find the nar release repo
link, https://github.com/Taromati2/package-factory
nar_file_name, Taromati2.nar //the nar file name
この場合、link フィールドは必須で、他のフィールドはオプションです。
nar_file_name フィールドは nar_release_repo.txt で使用され、ゴーストの nar ファイルとみなすべきリポのリリースの nar ファイルをウェブアプリケーションに伝えます。
それ以外のファイルは、標準的な拡張子はサードパーティに任せ、標準仕様のファイルを新たに追加する可能性は、後から排除することができます。
一般的ではない推奨のサードパーティ製拡張機能は、ファイル名にウェブアプリケーション名またはその略称を含めるべきです（例：GCS_link.txt）。
infosフォルダには、Webアプリケーションの関連情報を格納するために必要な数のtxtファイルを格納することができます。
Ghostの開発者は、ghost/descript.txtに metainfo フィールドを書き、その後にmetainfoフォルダのURLを書いて、特定のアプリケーションをghost経由でmetainfoフォルダに誘導できるようにすることが推奨されます。
また、ghost/descript.txt に githubrepo フィールドを記述し、その後に github プロジェクトの url を記述しても、同じ効果を持ち、同時に存在することができます。
例
//...
mousecursor.grip,./img/curs/hand_grip.cur
//
metainfo,https://raw.githubusercontent.com/Taromati2/Taromati2/master/.ukagaka/
githubrepo,https://github.com/Taromati2/Taromati2metainfoを持たないゴーストは、このようにmetainfoとuuidを付加することができます。
同じゴーストの異なるバージョンや、同じゴーストの異なるブランチが存在する可能性を考慮し、uuidは必要です。
ウェブアプリケーションは、uuidを使用して、同じ名前の実質的に異なるバージョンを区別することができます。
UUIDは、metainfoフォルダのアドレスやhomeurlの追加や変更により変化する可能性があるため、同一のゴーストが複数の過去のUUIDを持つ可能性があります。
UUIDの生成原理については気にしない場合、uuid-gennerを使用してUUIDを直接生成することができます。
UUIDの生成方法は以下の通りです：
- ゴーストがmetainfoフォルダを持っている場合、そのURLを
uuidvalueとして使用します。 ゴーストがmetainfoフォルダを持っていない場合、そのhomeurlをuuidvalueとして使用します。 ゴーストがhomeurlを持っていない場合、その名前をuuidvalueとして使用します。 - ゴーストが
uuid_baseフィールドを持っている場合、その内容を既存のuuidvalueに追加します。 uuidvalueをUTF8でエンコードし、改行を追加せずにMD5で暗号化し、その結果をbase64でエンコードします。
例えば、https://raw.githubusercontent.com/Taromati2/Taromati2/master/.ukagaka/から生成されるUUIDはR5dVNluBvKjtQqjP0dAuoA==です。
ゴーストは、アプリケーションがネットワーク接続なしでUUIDを計算できるように、十分な情報を持つべきです。
そのために、以下の措置を講じます：
ゴーストがmetainfoフォルダを持っている場合、そのURLをdescript.txtに記録します。
ゴーストのmetainfoにuuid_baseフィールドがある場合、それをdescript.txtに記録します。
新しいゴーストをキャプチャまたは受信したときに、そのゴーストのUUIDを検証し、情報の正当性を確認し、異なるゴーストを混同することを防ぐべきです。
UUIDの検証は、metainfoフォルダにアクセスし、jump_to.txtファイルが存在するかどうかを確認することで行います。
metainfoフォルダのアドレスが変更されるとUUIDが変更される可能性があるため、同一のゴーストが複数の過去のUUIDを持つ可能性があります。
アプリケーションは、ゴースト関連のリクエストやロジックを構築する際に、UUIDを使用してゴーストを区別するべきではありません。代わりに、metainfoフォルダのURLを含めて、UUIDの検証が最新の情報に基づいて行われるようにすべきです。
アプリケーションは、ゴーストの過去のUUIDをキャッシュして高速にマッチングを行うことが許可されていますが、マッチングが失敗した場合はキャッシュを更新すべきです。
マッチングが失敗した場合、アプリケーションはそのホストの登録を拒否すべきです。
重要： metainfoフォルダのアドレスを持たないゴーストは、homeurlまたはmetainfoフィールドでmetainfoフォルダのアドレスを指定するまで、同じ名前のmetainfoフォルダのアドレスを持つゴーストと同一のゴーストとして定義すべきではありません。
既存のゴーストにUUIDを追加する方法については、ghost経由でmetainfoフォルダに誘導するを参照してください。
UUIDは、既存のhomeurlを持つホストを混乱や上書きから保護しますが、その履歴にhomeurlがないホストを上書きから保護することはできません。