leynier/portifact

portifact は何をしますか？

Portifact は、静的アーティファクトを、独自の URL、アクセス制御、有効期限と復元機能、そして認証されたレビューアからのオプションの注釈とともに公開します。エージェントは、portifact CLI またはリモート MCP サーバーを通じてこれを使用します。

インストールされているバージョンの機能を確認する

Portifact は開発初期段階にあり、リリースごとにコマンドが追加されます。コマンドを使用する前に、以下の手順を実行してください。

1. portifact --version を実行して、CLI がインストールされていることを確認します。
2. portifact --help を実行して、このバージョンでサポートされているコマンドを確認します。
3. --help にリストされているコマンドとフラグのみを使用してください。コマンドを推測しないでください。インストールされているバージョンでユーザーが要求した操作ができない場合は、その旨を伝え、アップデートを提案してください。

--help に login がリストされているバージョンでは、サインイン、サインアウト、およびサインインしているアカウントの表示が可能です。--help に publish もリストされているバージョンでは、ファイルとフォルダの公開、アーティファクトとそのアクセスの管理が可能です。--help に versions、rollback、pull がリストされているバージョンでは、バージョンの一覧表示、ロールバック、ダウンロードが可能です。--help に annotations がリストされているバージョンでは、以下で説明するコメントスレッドの管理が可能です。portifact publish --help に --source、--ref、--assets がリストされているバージョンでは、ZIP ファイルの公開、プライベートソースの添付、Markdown アセットの公開が可能です。portifact pull --help に --git がリストされているバージョンでは、プライベートソースの Git 履歴を構築します。--help に usage がリストされているバージョンでは、アカウントのクォータを表示します。--help に logs がリストされているバージョンでは、誰がアーティファクトを開いたかを表示します。--help に licenses がリストされているバージョンでは、バイナリに含まれるオープンソースソフトウェアのライセンスを表示します（portifact licenses; 参照: https://portifact.com/third-party-notices）。MCP サーバー（https://app.portifact.com/mcp）は、小さなドキュメントの一覧表示、公開、管理、バージョンの一覧表示、ダウンロード、ロールバック、注釈の読み取り、書き込み、モデレート、エクスポート、使用状況とアクセスログの報告が可能です。詳細は以下を参照してください。

CLI のインストールまたは更新

CLI はシングルバイナリであり、Node や Bun は必要ありません。ユーザーのマシンにソフトウェアをインストールする前に、必ず許可を求めてください。

curl -fsSL https://portifact.com/install | bash

irm https://portifact.com/install.ps1 | iex

• Alpine Linux では、最初に C++ ランタイムをインストールしてください: apk add libstdc++ libgcc。
• 同じコマンドを再実行して更新します。
• PORTIFACT_VERSION=0.2.0 を設定して、特定のバージョンをインストールします。
• 非対話型環境やサンドボックス環境では、PORTIFACT_NO_MODIFY_PATH=1 を設定し、シェルプロファイルを編集する代わりに ~/.portifact/bin/portifact を直接呼び出してください。
• インストーラーは、リリースチェックサムに対してダウンロードを検証し、不一致があると停止します。検証に失敗した場合は、回避しないでください。

サインイン

まず portifact whoami --json で確認します。終了コード 0 は {"server","userId","clientId","scopes"} を出力します。終了コード 3 は、このデバイスがサインインしていないか、セッションが終了したことを意味します。

サインインするには、portifact login を実行します（解析可能な結果を得るには --json を追加します）。これは OAuth デバイスフローを使用します。

1. CLI は、ページ（https://app.portifact.com/device）と 8 文字のコードを stderr に出力し、端末に人間がいる場合はブラウザを開きます。ブラウザを開かないようにするには、--no-browser を渡します。
2. 出力されたページとコードをそのままユーザーに表示し、そこにサインインして、ページに同じコードが表示されていることを確認し、承認するように依頼してください。ユーザーに代わって承認したり、そのページから何かを貼り付けるように依頼したりしないでください。サインインページでは、ユーザーが 18 歳以上であることの確認と利用規約（https://portifact.com/terms）への同意が求められます。その選択はユーザー自身のものであるため、代わりに同意することは絶対にしないでください。ページに「メールコードを送信できない」（以前のメールがバウンスしたか、スパムとして報告された）または「今月のメールコードが一時停止されている」と表示された場合は、代わりに Google または GitHub でサインインするようにユーザーに伝えてください。
3. コマンドは、ユーザーが承認または拒否するか、コードが期限切れになるまで（10 分）待機するため、ユーザーが stderr を確認でき、完了するまで実行できる場所で実行してください。

認証情報はオペレーティングシステムの資格情報ストアに保存されます。資格情報ストアがない場合（Secret Service がない Linux サーバーなど）、ユーザー設定ディレクトリ（Linux では ~/.config/portifact、macOS では ~/Library/Application Support/portifact、Windows では %APPDATA%\portifact）の credentials.json に、ユーザーのみがアクセスできるパーミッションで保存され、CLI は警告を出力します。そのファイルや保存されたトークンを読み取ったり、印刷したり、コピーしたり、アップロードしたりしないでください。CLI は自動的にトークンを更新します。

portifact logout は、サーバー上のこのデバイスのトークンを取り消してから削除します。トークンを取り消すため、最初にユーザーに確認してください。サーバーに到達できない場合、認証情報は保持され、終了コード 1 で終了します。後でもう一度実行してください。

PORTIFACT_APP_ORIGIN は、CLI を別のサーバーに向けるもので、テストとステージング用に存在します。ユーザーから要求されない限り、設定しないでください。

公開

--help に publish がリストされているバージョンのみで使用可能です。

1. 最初にプレビュー: portifact publish <path> --dry-run --json は、サインインやアップロードを行わずにマニフェストをビルドします。{"dryRun","type","name","entrypoint","totalBytes","files":[{"path","size","sha256","contentType"}],"excluded":[{"path","reason"}]} を返し、さらに --source を指定した場合は "sources":{"chosenBy","totalBytes","files","excluded","origin","lfsPointers"} も返します。ファイル、ソース、除外されたものをユーザーに表示し、プライベートなものが含まれているように見える場合は停止してください。
2. 公開: portifact publish <path> --json。結果は {"artifactId","versionId","versionNumber","url","expiresAt","uploadId","files","totalBytes","sourceFiles","sourceBytes","sourceOrigin","uploadedFiles","uploadedBytes"} です。進捗状況とマニフェストは stderr に出力されます。

• タイプはパスから推測されます: フォルダ、.zip、.html ファイルは site、.md は markdown、.txt は text です。他のファイルの場合は --type site|markdown|text を渡します。フォルダと ZIP ファイルはサイトとしてのみ公開できます。
• 単一の HTML ファイルは、サイトの index.html として公開されます。フォルダには index.html が必要です。または、最初に開くページを指定する --entry <path> が必要です。
• --name はアーティファクトリストに表示される名前を設定します。デフォルトはファイル名またはフォルダ名です。
• --artifact <id> は、既存のアーティファクトの新しいバージョンを公開し、--name で名前が変更されない限り、その名前、タイプ、アクセスを保持します。間に他の誰かが公開した場合、version_conflict（終了コード 6）で失敗します。アーティファクトを確認して、再度公開してください。
• フォルダは常に、.git、node_modules、キャッシュ、OS ファイル、およびシークレットを保持する可能性のあるファイル（.env と .env.*（サンプルを除く）、.dev.vars、.npmrc、.netrc、SSH キー、*.pem、*.key、*.p12、Terraform 状態など）を除外します。このようなファイルを直接指定することは拒否されます。このフィルターはセーフティネットであり、レビューではありません。それでもマニフェストを確認してください。
• シンボリックリンクと特殊なファイルは拒否され、たどられることはありません。
• アカウントがすでに保存しているファイルは再度アップロードされません。中断されたアップロードは再試行され、アップロード開始後に公開が失敗した場合、CLI はそれをキャンセルするため、中途半端な公開は行われません。
• 進捗状況に Uploaded part <n> of <m> of <path> と表示されるバージョンは、64 MiB を超えるファイルを 16 MiB のパートに分割してディスクからストリーミングアップロードするため、大きなファイルをメモリに収める必要がなく、失敗したパートは個別に再送信されます。バージョンは、公開ファイルの合計で最大 250 MB まで保持できます（パートサイズに関係なく）。
• ZIP ファイルは、アップロード前にユーザーのマシンで展開されます。すべてのファイルが 1 つのフォルダ内にある場合、そのフォルダがルートになります。リンク、特殊ファイル、暗号化されたエントリ、アーカイブ外のパス、名前の競合、エントリの重複、宣言されたサイズを超えて展開されるファイル、または 200 倍を超えるファイル、10,000 を超えるエントリ、およびサイズ制限を超えるものは、拒否されます（invalid_input、終了コード 2、または quota_exceeded、終了コード 7）。デフォルトの除外ルールとシークレットフィルターもそのエントリに適用されます。
• --source <path> は、プライベートソースをバージョンに添付します。所有者のみが表示およびダウンロードでき（pull --source）、ストレージにはカウントされますが、公開サイズにはカウントされず、公開ファイルとソースファイルを合わせて最大 1,000 個までです。パスは、フォルダ、単一ファイル、ZIP ファイルのいずれかです。git リポジトリ内のフォルダの場合、git がファイルを選択します。バージョン管理されているファイルと、無視されていない新しいファイルで、サブモジュールやネストされたリポジトリは含まれません。--ref <commit> は、代わりにそのコミットのツリーを正確に添付します（ブランチ、タグ、コミット ID。コミットされていない変更は含みません）。CLI は、コミット、ブランチ、資格情報なしのリモート、コミットされていない変更があったかどうかを、バージョンの sourceOrigin として記録します。リポジトリの外部、または git がインストールされていない場合、フォルダはデフォルトの除外ルールで走査されます。シークレットを保持する可能性のあるファイルは、git の指示に関係なく、決して添付されません。Git LFS ポインターがある場合、stderr に警告が表示されます。これらはポインターとして添付され、コンテンツとしては添付されません。最初に git lfs pull を提案してください。
• --assets <dir> は、Markdown ドキュメントと一緒に、画像などのファイルを含むフォルダを、ドキュメントからの相対パスで公開するため、相対リンクが機能します。フォルダはドキュメントのフォルダ内にある必要があり、デフォルトの除外ルールが適用されます。
• Portifact は markdown または text アーティファクトを自分自身でレンダリングします。その URL はドキュメントからレンダリングされたページを開き、Markdown 内の生の HTML はテキストとして表示され、何も実行されません。元のファイルは、アーティファクト URL の下の独自のパスからダウンロードできます（例: <url>plan.md、または publish_document の場合は <url>index.md）。アクセスはページと同じです。ドキュメントは最大 5 MB の UTF-8 テキストであり、text アーティファクトは単一のファイルです。

アーティファクトの管理

--help にこれらのコマンドがリストされているバージョンのみで使用可能です。すべてのコマンドは --json を受け付けます。

• portifact list [--limit N] [--cursor C] [--search TEXT] [--state active|archived|suspended|purging] [--type site|markdown|text] [--access public|authenticated|restricted] [--annotations off|open|locked] は {"items":[...],"nextCursor"} を返します。nextCursor を --cursor として、同じフィルターとともに渡すと、次のページを取得できます。各アイテムは portifact info が返すものに "activity":{"versions","currentBytes","openThreads","lastAnnotationAt"} を加えたものです。versions は保持されているバージョン数（現在のバージョンを含む）、currentBytes は現在のバージョンのバイト数（公開ファイルとソース、バージョンがない場合は null）、openThreads は現在のバージョンのオープンスレッド数、lastAnnotationAt はいずれかのバージョンのスレッドが最後に変更された時刻（スレッドがない場合は null）です。トラフィックはアーティファクトごとではなくアカウントごとにカウントされるため、portifact usage にのみ表示されます。--search は名前（大文字小文字を区別しない）または ID の一部に一致し、指定されたすべてのフィルターが成立する必要があるため、すべてのページをめくる代わりにアーティファクトを見つけるために使用してください。portifact info <id> は、1 つのアイテムを返します: {"id","name","type","state","accessMode","annotations","currentVersionId","url","expiresAt","archivedAt","purgeAt","createdAt","updatedAt"}。アーティファクトが停止されている間は、"suspension":{"reason"} も追加されます。
• portifact renew <id>、archive <id>、restore <id> は {"artifactId","state","expiresAt","purgeAt"} を返します。アーカイブする前に確認してください。
• portifact delete <id> は完全に削除します。端末にいる人にアーティファクト ID の入力を求めます。端末がない場合は --yes が必要で、そうでなければ終了コード 2 で失敗します。ユーザーがその正確なアーティファクトを確認した場合にのみ --yes を渡してください。

アクセスの制御

--help に access がリストされているバージョンのみで使用可能です。すべてのコマンドは --json を受け付け、{"artifactId","mode","readers","indexable","embeddable","policyGeneration"} を出力します。

• portifact access <id> は現在のポリシーを表示します。公開後にアクセスモードを報告するために使用してください。
• portifact access set <id> restricted|authenticated|public: restricted は所有者とリストされた閲覧者のみ、authenticated は Portifact にサインインしている全員、public はリンクを知っている全員です。最初の 7 日間のアカウントはアーティファクトを公開できません（account_too_new_for_public、終了コード 7）。
• portifact access add <id> <email>... と access remove <id> <email>... は閲覧者リストを変更します（一度に最大 100 アドレス）。閲覧者は、モードが restricted の場合にのみ意味を持ちます。

バージョン、ロールバック、ダウンロード

--help にこれらのコマンドがリストされているバージョンのみで使用可能です。すべてのコマンドは --json を受け付けます。

アーティファクトは、現在のバージョンと、過去 7 日間に置き換えられたバージョンを保持します。ロールバックとダウンロードは、これらの保持されているバージョンに対してのみ機能します。

• portifact versions <id> は、新しいものから順に一覧表示します。--json は {"artifactId","items":[{"id","number","current","entrypoint","publishedBytes","sourceBytes","publishedFiles","sourceFiles","rendererVersion","committedAt","expiresAt","sourceOrigin"}]} を出力します。expiresAt は、以前のバージョンが保持されなくなる時刻で、現在のバージョンの場合は null です。sourceOrigin は、ソースが git から取得された場合は {"commit","branch","remote","dirty"} で、それ以外の場合は null です。Origin は公開者が宣言したものであり、Portifact はそれを検証できません。
• portifact rollback <id> <version-id> は、保持されているバージョンを現在のバージョンに戻します。これは同じファイルで新しいバージョンとして公開され、30 日間が再開され、アクセスは変更されません。そのバージョン以降に削除された閲覧者は削除されたままです。ロールバックする前にユーザーに確認してください。{"artifactId","versionId","versionNumber","url","expiresAt","fromVersionId","fromVersionNumber"} を返します。間に他の誰かが公開した場合、version_conflict（終了コード 6）で失敗します。versions を再度確認し、ユーザーに確認してください。portifact rollback --help に「バージョン ID または番号」と表示されているバージョンでは、<version-id> にバージョン番号（3 または v3）を指定することもでき、pull --version でも受け付けられます。保持されていない番号は not_found（終了コード 5）で失敗します。
• portifact pull <id> --out <dir> は、現在のバージョンの公開ファイルを <dir>/published にダウンロードします。プライベートソースの場合は --source（<dir>/source に、所有者のみ）、両方の場合は --published --source、以前のバージョンの場合は --version <version-id> を追加してください。<dir> はまだ存在していてはなりません。pull はその外部に書き込むことはなく、.git フォルダ内のパスを拒否し、すべてのファイルの SHA-256 をチェックし、何かが失敗した場合はフォルダを削除します（download_failed、終了コード 1）。{"artifactId","versionId","versionNumber","out","files":[{"kind","path","size","sha256"}],"totalBytes"} を返します。

注釈

--help に annotations がリストされているバージョンのみで使用可能です。

Portifact は、公開されたドキュメントの各バージョンに、認証されたレビューアによる注釈（スレッド化されたコメント）を保存します。各スレッドは、ドキュメント内のテキスト範囲（開始オフセット、終了オフセット、コンテキスト行）またはページ全体に関連付けられます。スレッドは、すべての公開されたアーティファクトタイプ（サイト、Markdown、テキスト）で使用でき、サイトアーティファクトの場合は、オフセットはドキュメントのソースを参照します。

注釈の読み取り

• portifact annotations <id> [--version <version-id>] は、バージョンのすべてのスレッドを一覧表示します。--json は、{"artifactId","versionId","versionNumber","items":[{"id","status","range":{"startOffset","endOffset","context"},"createdAt","createdBy","updatedAt","comments":[{"id","body","createdAt","createdBy","updatedAt"}]}]} を出力します。status は open または locked、range はスレッドの範囲を持つオブジェクト（ページ全体の場合は null）、context は範囲の前後のテキスト行を含みます。createdBy は {"userId","displayName","email"} です。各コメントは body を持ち、createdBy はユーザー情報を持ちます。

注釈の書き込み

• portifact annotations add <id> [--comment <text>] [--range <start-offset>:<end-offset>] は、オプションの初期コメントと範囲を持つ新しいスレッドを作成します。ID を返します。
• portifact annotations comment <id> <thread-id> [--comment <text>] は、スレッドにコメントを追加します。コメント ID を返します。

コメントを投稿するには --comment は必須です。対話的に必要な場合にのみ、エージェントがこれらのコマンドを実行する前にユーザーにテキストを確認するように依頼することを検討してください。

注釈の管理

• portifact annotations lock <id> <thread-id> はスレッドをロックし、新しいコメントを防ぎます。
• portifact annotations export <id> [--format json|csv] は、バージョンのすべての注釈をエクスポートします。デフォルトは JSON です。CSV は標準出力に出力されます。

使用状況

--help に usage がリストされているバージョンのみで使用可能です。

• portifact usage [--json] は、現在のアカウントの使用状況とクォータを表示します。--json は {"account","limits":{"artifacts","storageBytes","sourcesStorageBytes","versions","publishedBytesPerVersion","sourceBytesPerVersion","filesPerVersion","annotations"},"usage":{"artifacts","storageBytes","sourcesStorageBytes","outboundBandwidthBytes","renewals","annotations"},"limitsResetsAt"} を出力します。limits は制限値、usage は現在の使用量を示し、limitsResetsAt は制限がリセットされる時刻を示します（使用量制限がリセットされる場合）。

ログ

--help に logs がリストされているバージョンのみで使用可能です。

• portifact logs <id> [--limit N] [--cursor C] は、アーティファクトのアクセスログエントリを一覧表示します。--json は <id> を含むログエントリの配列を出力します。

ライセンス

--help に licenses がリストされているバージョンのみで使用可能です。

• portifact licenses は、バイナリに含まれるオープンソースソフトウェアのライセンスを出力します。

MCP サーバーの使用

エージェントは、https://app.portifact.com/mcp で Portifact MCP サーバーと通信できます。これにより、以下の機能へのアクセスが提供されます。

利用可能なツール

• portifact_list - アーティファクトを一覧表示します（フィルター: search、state、type、access、annotations、limit、cursor）。
• portifact_publish - アーティファクトを作成または更新します（path、name、type、artifact ID、entry、source、ref、assets）。ファイルの内容は文字列または JSON として渡されます。
• portifact_info - アーティファクトの詳細を取得します。
• portifact_versions - アーティファクトのバージョンを一覧表示します。
• portifact_download - アーティファクトをダウンロードします（artifact ID、version、source）。
• portifact_rollback - バージョンにロールバックします。
• portifact_annotations - 注釈を一覧表示します。
• portifact_annotations_add - 注釈スレッドを作成します。
• portifact_annotations_comment - スレッドにコメントを追加します。
• portifact_annotations_lock - スレッドをロックします。
• portifact_annotations_moderate - コメントをモデレートします（削除または編集）。
• portifact_annotations_export - 注釈をエクスポートします。
• portifact_usage - アカウントの使用状況とクォータを取得します。
• portifact_logs - アーティファクトのアクセスログを取得します。

MCP サーバーを使用する前に、認証が設定されている（つまり、CLI がサインインしている）ことを確認してください。

トラブルシューティング

• 公開に失敗する場合: portifact publish <path> --dry-run --json でマニフェストを確認し、エラーメッセージを確認します。よくある問題としては、ファイルサイズの制限超過、許可されていないファイルタイプ、アクセス権限の問題などがあります。
• サインインに失敗する場合: ブラウザベースのフローを使用していること、ユーザーがコードを正しく入力していることを確認します。メール認証に問題がある場合は、Google または GitHub でのサインインを提案します。
• ダウンロードに失敗する場合: アーティファクト ID とバージョンが正しいこと、出力ディレクトリが存在しないことを確認します。

追加情報

• ドキュメント: https://portifact.com/docs
• サポート: https://portifact.com/support
• ステータス: https://status.portifact.com