scratch-archive

Scratch プロジェクトをローカルにアーカイブし、必要なら Hugging Face Dataset へアップロードする CLI です。

セットアップ

bun install

使い方

1. scrape（アーカイブ収集）

bun run src/index.ts scrape [options]

scrape は 1 回の実行で複数プロジェクトを連続処理し、Ctrl+C まで継続します。
進捗は色付き CUI ダッシュボードで表示されます（TTY 環境）。

挙動

• --project-files <path> を指定した場合:
  • 改行区切りのプロジェクト ID を読み込みます
  • その中からランダム順で処理します
  • すでにローカルにアーカイブ済みの ID は除外します
• --project-files 未指定の場合:
  • 1 から 1282453125 の範囲からランダム選択します
  • すでにローカルにアーカイブ済みの ID は除外します

オプション

• --project-files <path>: 改行区切り ID ファイルを指定
• --out <dir>: アーカイブの配置先ベースディレクトリ（デフォルト: .、実際の保存先は <dir>/.archive/）
• --dataset <repo>: Hugging Face dataset（デフォルト: pnsk-lab/scratch-archive）
• --skip-existing: リモートに同一スナップショットがある場合はスキップ
• --cache-dir <dir>: Hugging Face アセットツリーのキャッシュディレクトリ（デフォルト: .scratch-archive-cache）

404 のプロジェクトは projects/{project_id}/{timestamp}/metadata.json として自動で記録されます（notFound: true）。

例

# 全IDレンジからランダムに連続収集（Ctrl+C で停止）
bun run src/index.ts scrape

# ids.txt をランダム順で消化
bun run src/index.ts scrape --project-files ids.txt --out ./work --skip-existing

Ctrl+C の挙動:

• 1 回目: 現在処理中のプロジェクト完了後に停止
• 2 回目: 即時終了

2. upload（Hugging Face へアップロード）

bun run src/index.ts upload [--path <dir>] [--dataset <repo>]

• --path <dir>: アップロード元ディレクトリ（デフォルト: .archive）
• --dataset <repo>: 送信先 dataset（デフォルト: pnsk-lab/scratch-archive）

例:

bun run src/index.ts upload --path ./.archive --dataset pnsk-lab/scratch-archive

upload は内部で hf upload-dir を実行するため、事前に Hugging Face CLI のインストールとログインが必要です。

--project-files の書式

1 行に 1 つの数値 ID を書きます。

123456789
987654321

• 空行は無視されます
• 重複 ID は自動で除外されます
• 有効範囲は 1 から 1_300_000_000 です

3. make-project-list-from-users（ユーザー一覧からプロジェクト ID を作成）

bun run src/index.ts make-project-list-from-users users.txt projects.txt
bun run src/index.ts make-project-list-from-users --concurrency 50 users.txt projects.txt

users.txt には 1 行 1 ユーザー名で記述します。
users.json では string[] として扱います。

bun run src/index.ts make-project-list-from-users users.txt projects.txt
bun run src/index.ts make-project-list-from-users users.json projects.txt

• projects.txt には重複を除外した project_id を 1 行ずつ出力します
• 404 ユーザーは警告してスキップします。
• projects.txt は追記方式で書き込むため、処理件数が多い場合でも進捗表示に合わせて段階的にファイルが増えていきます。
• TTY 環境では色付きの進捗ダッシュボードを表示します。
• --concurrency 未指定時のデフォルトは 50 です。