Zuroku Publish

zuroku-publish

zuroku publish で HTML + 画像をアップロードする手順。AI agent (Claude Code 等) からの呼び出しを想定。

前提: zuroku CLI が PATH にあること。無ければ command -v zuroku で確認し、

未インストールなら npm i -g @zuroku/cli を案内する (このプラグインは CLI を同梱しない)。

TL;DR

# HTML と画像をデプロイ用ディレクトリに集める (sed での書き換えは原則不要、下の注意参照)
mkdir -p /tmp/zuroku-deploy
cp /path/to/index.html /path/to/images/*.png /tmp/zuroku-deploy/

cd /tmp/zuroku-deploy
zuroku publish ./index.html ./*.png --title "..."
# - `images/<画像>` 参照は CLI が **provided asset の filename にアンカーして**
#   自動で `img/<画像>` に正規化する。手動 sed は不要 (外部 URL は壊さない)。
# - sharp で client-side WebP 圧縮 (85%、長辺 2000px)。<img src="img/foo.png"> も
#   CLI が自動で .webp に rewrite (v0.1.1+)。
# - 標準出力の最終行が公開 URL

# 自分だけが見える private で上げたい場合
zuroku publish ./index.html ./*.png --title "..." --private

⚠️ `sed 's|images/|img/|g'` のような bare 置換は使わない。 文字列 images/

をどこでも置換するため、HTML 内の外部画像 URL

(https://.../images/foo.webp 等) まで .../img/... に化けさせて 404 にする。

ローカル参照の正規化は CLI が安全に行うので不要。どうしても手動で直す必要がある

場合 (後述 assets/ 等) は src="images/ のようにローカル参照だけにアンカーすること。

制約

R1. HTML の image src は img/<basename> に統一

• 配信ルートが /p/:slug/img/:filename 固定。HTML 側は相対 <img src="img/foo.png"> で参照する。
• `images/<画像>` (複数形) は CLI が provided asset について自動で `img/` に正規化するので手動修正は不要。外部 URL (https://.../images/...) は provided にアンカーされるため触られない。
• assets/、style/ 等の別ディレクトリ名は自動正規化の対象外。必要なら src="assets/ のようにローカル参照だけにアンカーして書き換える。bare `images/` を global 置換しないこと (外部 URL 内の images/ まで壊して 404 になる)。
• SVG (<img src="img/foo.svg">) は受け付けない。PNG / JPEG / WebP / GIF のみ。

R2. 圧縮 (default ON、client-side で軽量化される)

• default で sharp が PNG/JPEG → WebP 85%、長辺 max 2000px に変換 (帯域 / 表示の両方で大幅軽量化)。
• 拡張子 .png → .webp の rename が発生するが、HTML 内 `<img src="img/foo.png">` は CLI が自動で `.webp` に rewrite する (v0.1.1+)。AI agent 側で sed は不要。
• --no-compress を付けると original のまま upload (filename 不変、HTML も触らず)。サイズが大きい時は事前リサイズしないと R3 に当たる。
• GIF はアニメ保持のため compress でも passthrough (filename 不変)。

R2.5. サムネ / OG 画像 (thumb.* 規約)

• OG 画像 (SNS unfurl / アプリ内一覧のサムネ) は `thumb.{png|jpg|jpeg|webp|gif}` という名前の画像が自動で選ばれる。専用フラグは無く、ファイル名規約で指定する。
• thumb.* が無ければ asset の 1 枚目 (created_at→filename 昇順の先頭) に自動フォールバックする。意図しない画像がサムネになりがちなので、サムネを効かせたい記事では必ず thumb.* を用意する。
• どの画像を `thumb` にするか: その記事の 全体像を最もよく表す 1 枚 を選んで thumb.* にリネームして含める。
• 良い例: 図解全体の俯瞰図 / 完成形のキービジュアル / 記事の結論を 1 枚で示す図。
• 避ける: 部分拡大・補足の細部図・文脈なしでは意味が伝わらない断片。SNS のカードや一覧で「これは何の記事か」が一目で伝わる 1 枚を選ぶ。
• *`thumb. は OG/SNS unfurl 互換のため CLI が自動で JPEG (thumb.jpg) に変換する** (v0.1.8+)。他の asset は WebP 圧縮されるが、サムネだけは LinkedIn / Facebook / LINE 等が WebP の og:image を描画しない問題を避けるため JPEG に揃える (Slack/Discord は WebP でも可)。HTML 内の img/thumb.png 参照も img/thumb.jpg` に自動 rewrite される。
• GIF の thumb.gif はアニメ保持のため変換しない。--no-compress で WebP の thumb を渡すと warn が出る (OG が表示されない可能性)。
• update の全置換でも thumb.* を含めれば再選定される。--keep-assets では既存のサムネがそのまま維持される。

R3. サイズ上限

• HTML: 5 MiB
• asset 1 ファイル: 5 MiB
• 1 日: 50 publish / 500 MB

R4. visibility (公開範囲)

• -V, --visibility <mode>: private (本人のみ) / curator (curator role を持つ Discord メンバーのみ閲覧可) / public (リンクを知る誰でも閲覧可)。
• --private: --visibility private のショートカット。-V curator と併用された場合は --private が勝つ (CLI が warn を出す)。
• どちらも未指定なら順に下記の優先順で解決:

1. CLI flag (--private > --visibility) 2. ~/.config/zuroku/config.json の default_visibility (zuroku config set default-visibility ...) 3. server default = curator

• `public` は per-publish で指定可能 (--visibility public)。リンクを知る誰でも閲覧できるが、アプリ内 timeline/検索には出さず X-Robots-Tag: noindex,nofollow で配信される (リンク共有 / SNS unfurl 用、SEO index はしない)。
• ただし `public` を `config set default-visibility` のデフォルトには保存できない (公開は毎回明示的に選ぶべきで、暗黙のデフォルトにはしない設計)。
• private のまま publish 後に visibility を変えたいときは stderr に表示される manage visibility: <app>/settings/projects の URL から切り替える (Web UI からは public への切替も可)。

CLI が publish 前に弾くケース

zuroku publish は HTML を parse して <img src="img/..."> と asset 引数の整合性を検査し、不一致なら INVALID_INPUT で fail-fast する。stderr に詳細メッセージが出るので、AI agent はタグを見て対処する。

緊急 bypass: ZUROKU_SKIP_PREFLIGHT=1 zuroku publish ... (debug 用、本番では使わない)。

R6. 外部 subresource の hotlink protection (v0.1.5+, 自動)

zuroku CLI は publish/update 時に HTML を scan し、<img src="https://..."> と <iframe src="https://..."> に referrerpolicy="no-referrer" が無ければ 自動付与する。理由:

• 配信ドメイン (例: app.zuroku.masao.ai) を Referer に載せると、X / 一部 CDN /

報道サイトの hotlink protection が 403 / placeholder を返す。

• curl / fetch(url) だと 200 が返るので「URL は生きている」と誤認しがちだが、

ブラウザ subresource として読むと壊れる。初見エージェントが最も機械的に踏む罠。

• 自動付与時は stderr に info html: added referrerpolicy="no-referrer" to N external <img>/<iframe> が出る。
• 既に referrerpolicy が指定済みで値が no-referrer 以外 (origin / unsafe-url 等) なら

CLI は 書き換えず warn を出す (誤設定の hint)。

スコープ外:

• <a href="https://..."> (ナビゲーションは hotlink 制限の対象外)
• img/<basename> (zuroku asset。同一 origin)
• data: / blob: URI

R5. local-path leak preflight (v0.1.3+)

preflight は asset 参照だけでなく HTML 全体を text として scan し、viewer 環境では絶対に解決しない作者マシン path を見つけたら LOCAL_PATH_LEAK で fail-fast する:

検知された場合は HTML 側を直して から再 publish する (絶対パスを削除 / 公開 URL に置換 / ファイル名だけ抽象的に言及)。<code> ブロックや本文中の引用にも leak しやすい。

update (republish) — slug を維持して上書き (v0.1.3+)

# slug でも id でも OK。HTML auto-rewrite / preflight は publish と同じ。
zuroku update my-cool-page ./index.html ./img/*.png

• 既存 project の HTML と asset を 完全置換 して同じ slug / URL で再公開する (-2 は付かない)。
• asset は 全置換。残したい画像も含めて positional 引数で渡すこと (省略すると 0 件で送られる)。
• 新しい URL を発行したい場合は update でなく publish を使う。
• 内部的には republish-init → uploadHtml/uploadAsset (新 token) → republish の 3 段階。失敗しても manifest swap (3 段目) までは旧版が viewer に出続ける。

--keep-assets — 本文だけ直して画像はそのまま (v0.1.5+)

# HTML だけ差し替え、既存の画像は一切触らない。img 引数は不要 (渡しても無視)。
zuroku update my-cool-page ./index.html --keep-assets

• 既存画像を 温存 したまま HTML だけ更新する。全置換モードと違い画像の再アップロード不要。
• 「文言だけ直したい」「typo 修正」など本文のみの更新で、画像の渡し忘れによる一括削除事故を防げる。
• asset 欠落 preflight はスキップされる (HTML が参照する img/* はサーバ側に温存されている前提)。
• ただし新 HTML が*サーバに無い `img/ を参照している**場合は CLI が warn を出す (--keep-assets: HTML references img/ files not present on the server)。「本文だけ直す」つもりで画像参照名を変えると沈黙して 404 になる事故を防ぐためのもの。warn が出たら参照名を直すか、--keep-assets` を外して全画像を渡す全置換モードに切り替える。
• thumbnail / OG 画像も従来のまま維持される。
• 画像を 足す / 差し替える / 消す ときは --keep-assets を付けず、全画像を positional で渡す全置換モードを使う。

認証

# Web UI で API key 発行 → 平文 token をコピー → CLI に登録
zuroku auth login --token zrk_live_xxx --base-url https://app.zuroku.masao.ai

token は HMAC で server 保存、平文は発行時 1 回だけ表示される。

config (per-user 既定値)

zuroku config set default-visibility private    # 既定を private に
zuroku config set default-visibility curator    # 既定を curator に戻す
zuroku config unset default-visibility          # config 削除 → server default 'curator'
zuroku config get default-visibility            # 現在値を stdout に
zuroku config get                               # 一覧

config は ~/.config/zuroku/config.json に 0600 で保存される (XDG_CONFIG_HOME 尊重)。 default-visibility に設定できるのは private / curator のみ。`public` は `set` で reject される (公開は per-publish で --visibility public を明示する設計で、暗黙のデフォルトにはしない)。publish は flag 未指定時に config を fallback する (info 行 visibility: <mode> (from config default_visibility) が出る)。

list / delete

zuroku list              # 自分の publish 一覧
zuroku delete <slug>     # soft delete
zuroku delete <slug> -y  # 確認スキップ

soft delete 後に同じ slug を再 publish すると <slug>-2 が自動採番される。

出力 contract

zuroku publish の stdout 最終行は bare URL のみ。進捗 / info / success は stderr に出る。

URL=$(zuroku publish ./index.html ./img/*.png --title "..." 2>/dev/null | tail -1)

失敗パターン早見表