@helpfeel/cosense-cli 1.6.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpfeel/cosense-cli",
-  "version": "1.6.0",
+  "version": "1.9.0",
   "description": "Cosense (旧Scrapbox) のページを読み・調べ・編集するAgent Skill用のCLI",
   "homepage": "https://github.com/helpfeel/cosense-cli",
   "license": "MIT",
@@ -29,8 +29,8 @@
   "devDependencies": {
     "@types/node": "24.13.2",
     "npm-run-all": "4.1.5",
-    "oxfmt": "0.54.0",
-    "oxlint": "1.70.0",
+    "oxfmt": "0.56.0",
+    "oxlint": "1.71.0",
     "typescript": "6.0.3"
   },
   "engines": {

package/src/cli.ts

@@ -17,6 +17,11 @@ import {
   browseRelatedPagesHelp,
   browseRelatedPagesSummary
 } from './commands/browseRelatedPages.ts';
+import {
+  downloadFile,
+  downloadFileHelp,
+  downloadFileSummary
+} from './commands/downloadFile.ts';
 import {
   list1hopLinks,
   list1hopLinksHelp,
@@ -43,6 +48,11 @@ import {
   previewEditHelp,
   previewEditSummary
 } from './commands/previewEdit.ts';
+import {
+  readFileInfo,
+  readFileInfoHelp,
+  readFileInfoSummary
+} from './commands/readFileInfo.ts';
 import {
   readPage,
   readPageHelp,
@@ -119,6 +129,16 @@ const commands: Record<string, CommandSpec> = {
     help: browseRelatedPagesHelp
   },
   readPage: { handler: readPage, summary: readPageSummary, help: readPageHelp },
+  readFileInfo: {
+    handler: readFileInfo,
+    summary: readFileInfoSummary,
+    help: readFileInfoHelp
+  },
+  downloadFile: {
+    handler: downloadFile,
+    summary: downloadFileSummary,
+    help: downloadFileHelp
+  },
   readProjectMembers: {
     handler: readProjectMembers,
     summary: readProjectMembersSummary,

package/src/commands/browsePage.ts

@@ -1,4 +1,5 @@
 import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { renderLiterateDatabase } from '../lib/literateDatabase.ts';
 import { parsePageUrl } from '../lib/parseUrl.ts';
 import { fetchRelatedPages } from '../lib/relatedPages.ts';
 import {
@@ -60,7 +61,11 @@ Usage:
     本文と関連ページ一覧の境界を示す非Markdown区切り線。Cosenseの#hashtag記法と
     衝突しないようにMarkdown見出しを避ける。
   ## 1 hop link
-    このページの 1-hop 近傍ページタイトル一覧。 1-hop が 0 件なら区切り線ごと省略
+    このページの 1-hop 近傍ページタイトル一覧。 0 件なら区切り線ごと省略。
+    このページがinfobox定義ページ（本文に table:infobox または table:cosense を宣言している）の
+    時は ## 1 hop link（Infoboxの文芸的データベース、TSV形式のテーブル） に変わる。表の構造は
+    cosense browseRelatedPages --help を参照。表に載らなかったページは
+    ## 1 hop link（表に載っていないページ） に出力する
 
 persistent: false の時:
   メタデータ・アイコン・テロメア・Infoboxは省略。 (このページはまだ作成されていません) と
@@ -119,6 +124,7 @@ interface PageData {
   lines?: PageLine[];
   icons?: string[];
   infoboxResult?: InfoboxResult[];
+  infoboxDefinition?: string[];
 }
 
 const LINE_ID_PATTERN = /^[0-9a-f]{24}$/;
@@ -283,11 +289,26 @@ const renderBody = (lines: PageLine[], fragment: string | null): BodyRender => {
   return { body: out.join('\n'), matchedFragment };
 };
 
-const renderRelatedPages = (hopValue: unknown): string | null => {
+const renderRelatedPages = (
+  hopValue: unknown,
+  page: PageData
+): string | null => {
+  const sections: string[] = [];
+  // seen は文芸的データベースと 1 hop link で共有して、表に載ったページを再掲しないようにする
+  const seen = new Set<string>();
+  const literateDatabase = renderLiterateDatabase(page, hopValue, seen);
+  if (literateDatabase) sections.push(literateDatabase);
+
   const links1hop = (hopValue as { links1hop?: RelatedPage[] }).links1hop;
-  const pages = dedupAndSortByPageRank(links1hop);
-  if (pages.length === 0) return null;
-  return `-------------------- Related Pages --------------------\n\n## 1 hop link\n\n${renderGroups(buildGroups(pages))}`;
+  const pages = dedupAndSortByPageRank(links1hop, seen);
+  if (pages.length > 0) {
+    const heading = literateDatabase
+      ? '## 1 hop link（表に載っていないページ）'
+      : '## 1 hop link';
+    sections.push(`${heading}\n\n${renderGroups(buildGroups(pages))}`);
+  }
+  if (sections.length === 0) return null;
+  return `-------------------- Related Pages --------------------\n\n${sections.join('\n\n')}`;
 };
 
 export const browsePage = async (args: string[]): Promise<void> => {
@@ -317,7 +338,7 @@ export const browsePage = async (args: string[]): Promise<void> => {
     sections.push('(このページはまだ作成されていません)');
     const { body } = renderBody(page.lines ?? [], null);
     sections.push(`## 本文（テンプレート）\n\n${body}`);
-    const related = renderRelatedPages(hopValue);
+    const related = renderRelatedPages(hopValue, page);
     if (related) sections.push(related);
     process.stdout.write(`${sections.join('\n\n')}\n`);
     return;
@@ -368,7 +389,7 @@ export const browsePage = async (args: string[]): Promise<void> => {
 
   sections.push(`## 本文\n\n${body}`);
 
-  const related = renderRelatedPages(hopValue);
+  const related = renderRelatedPages(hopValue, page);
   if (related) sections.push(related);
 
   process.stdout.write(`${sections.join('\n\n')}\n`);

package/src/commands/browseRelatedPages.ts

@@ -4,12 +4,19 @@ import {
   type Page,
   renderGroups
 } from '../lib/relatedPagesFormat.ts';
+import {
+  type DefinitionPage,
+  renderLiterateDatabase
+} from '../lib/literateDatabase.ts';
 import { fetchRelatedPages } from '../lib/relatedPages.ts';
+import { parsePageUrl } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveCredential } from '../lib/settings.ts';
 
 export const browseRelatedPagesSummary =
-  '1-hop+2-hopの関連ページタイトル一覧をAIが読みやすい形式で出力する';
+  '1-hop+2-hopの関連ページタイトル一覧をAIが読みやすい形式で出力する。infobox定義ページでは文芸的データベース(TSV表)を出力する';
 
-export const browseRelatedPagesHelp = `browseRelatedPages - 1-hop+2-hopの関連ページタイトル一覧をAIが読みやすい形式で出力する
+export const browseRelatedPagesHelp = `browseRelatedPages - 1-hop+2-hopの関連ページタイトル一覧をAIが読みやすい形式で出力する。infobox定義ページでは文芸的データベース(TSV表)を出力する
 
 Usage:
   cosense browseRelatedPages <pageUrl>
@@ -32,6 +39,26 @@ Usage:
   ## 2 hop link
 
   - タイトル
+
+対象がinfobox定義ページ（本文に table:infobox または table:cosense を宣言している）の時:
+  Web UIと同様に、関連ページリストの先頭が文芸的データベース（TSV形式のテーブル）になる。
+  行 = このページにリンクしているページ（pageRank 降順）。
+  列 = Page / Created / Updated + 定義された項目。
+  セル = 各ページの本文からInfoboxが抜き出した値（Cosense記法のまま。セル内の改行は「 / 」に置換）。
+  表に載らなかった関連ページは、続く ## 1 hop link（表に載っていないページ） に出力する。
+
+  # Related Pages
+
+  ## 1 hop link（Infoboxの文芸的データベース、TSV形式のテーブル）
+
+  Page/Created/Updated以外の列は、各ページの本文からInfoboxが抜き出した値
+
+  Page	Created	Updated	材料	カテゴリ
+  麻婆豆腐	2018-03-04	2026-07-05	[豆腐]、[挽き肉]	中華
+
+  ## 1 hop link（表に載っていないページ）
+
+  - 料理
 `;
 
 export const browseRelatedPages = async (args: string[]): Promise<void> => {
@@ -39,8 +66,15 @@ export const browseRelatedPages = async (args: string[]): Promise<void> => {
     throw new Error('Usage: cosense browseRelatedPages <pageUrl>');
   }
   const [url] = args as [string];
+  const { origin, projectName, encodedTitle } = parsePageUrl(url);
+  const credential = resolveCredential(origin, projectName);
 
-  const [result1hop, result2hop] = await Promise.allSettled([
+  // ページ本体はinfobox定義の取得にだけ使う。失敗しても従来のタイトル一覧に
+  // フォールバックできるよう、関連ページの取得失敗とは区別する
+  const [resultPage, result1hop, result2hop] = await Promise.allSettled([
+    requestJson(`${origin}/api/pages/v2/${projectName}/${encodedTitle}`, {
+      credential
+    }) as Promise<DefinitionPage>,
     fetchRelatedPages(url, 1),
     fetchRelatedPages(url, 2)
   ]);
@@ -49,8 +83,35 @@ export const browseRelatedPages = async (args: string[]): Promise<void> => {
     throw result1hop.reason;
   }
 
-  // seen は 1-hop と 2-hop で共有して、 1-hop に出たページが 2-hop にも再掲されないようにする
+  const sections: string[] = [];
+  // seen は文芸的データベース・1-hop・2-hopで共有して、先に出たページを再掲しないようにする
   const seen = new Set<string>();
+
+  let hasLiterateDatabase = false;
+  if (resultPage.status === 'rejected') {
+    // 非定義ページと区別が付かないまま黙って通常出力に落ちると、AIが不完全な
+    // 出力を信じてしまうので、判定不能である事をstderrで知らせる
+    process.stderr.write(
+      'ページ情報の取得に失敗したため、infobox定義ページかどうか判定できません。文芸的データベースがあっても出力されません\n'
+    );
+  } else if (result1hop.status === 'fulfilled') {
+    const literateDatabase = renderLiterateDatabase(
+      resultPage.value,
+      result1hop.value,
+      seen
+    );
+    if (literateDatabase) {
+      sections.push(literateDatabase);
+      hasLiterateDatabase = true;
+    }
+  } else if ((resultPage.value.infoboxDefinition?.length ?? 0) > 0) {
+    // infobox定義ページだと確定しているのに関連ページの取得に失敗した場合も、
+    // 表が黙って欠落しないように知らせる
+    process.stderr.write(
+      '関連ページの取得に失敗したため、このinfobox定義ページの文芸的データベースを出力できません\n'
+    );
+  }
+
   const pages1hop =
     result1hop.status === 'fulfilled'
       ? dedupAndSortByPageRank(
@@ -66,9 +127,11 @@ export const browseRelatedPages = async (args: string[]): Promise<void> => {
         )
       : [];
 
-  const sections: string[] = [];
   if (pages1hop.length > 0) {
-    sections.push(`## 1 hop link\n\n${renderGroups(buildGroups(pages1hop))}`);
+    const heading = hasLiterateDatabase
+      ? '## 1 hop link（表に載っていないページ）'
+      : '## 1 hop link';
+    sections.push(`${heading}\n\n${renderGroups(buildGroups(pages1hop))}`);
   }
   if (pages2hop.length > 0) {
     sections.push(`## 2 hop link\n\n${renderGroups(buildGroups(pages2hop))}`);

package/src/commands/downloadFile.ts

@@ -0,0 +1,90 @@
+import { parseFileUrl } from '../lib/parseUrl.ts';
+import { downloadToFile } from '../lib/request.ts';
+import { resolveFileCredential } from '../lib/resolveFileCredential.ts';
+
+export const downloadFileSummary =
+  'ファイル本体をダウンロードしてローカルに保存する';
+
+export const downloadFileHelp = `downloadFile - ファイル本体をダウンロードしてローカルに保存する
+
+Usage:
+  cosense downloadFile <fileUrl> <outputPath> [--thumbnail] [--project <projectUrl>]
+
+引数:
+  <fileUrl>     ファイルのURL（例: https://scrapbox.io/files/5f151efbacbb17001a58f120.png）。query/hashは付けない
+  <outputPath>  保存先ファイルパス。既存ファイルは上書きする。親ディレクトリは自動作成しない
+
+オプション:
+  --thumbnail             縮小版（thumbnail）を取得する。thumbnailが存在しないファイル（jpeg/png以外）は原本が返る
+  --project <projectUrl>  Service Account認証で取得する時に、ファイルが属するprojectのURLを指定する（例: https://scrapbox.io/example）。省略時はPersonal Access Tokenを使う
+
+出力（JSON）:
+  path         string         保存したファイルの絶対パス
+  contentType  string | null  取得したファイルのContent-Type
+  size         number         保存したファイルのbyte数
+
+例:
+  cosense downloadFile 'https://scrapbox.io/files/5f151efbacbb17001a58f120.png' ./image.png
+  cosense downloadFile 'https://scrapbox.io/files/5f151efbacbb17001a58f120.png' /tmp/thumb.png --thumbnail
+
+HTTPエラー:
+  401/403: 認証・権限が無い。private projectのファイルはproject member権限が必要
+  404: fileIdに対応するファイルが存在しない
+
+注記:
+  動画ファイルはサーバー側の制限により取得できない場合がある
+`;
+
+interface ParsedArgs {
+  fileUrl: string;
+  outputPath: string;
+  thumbnail: boolean;
+  project?: string;
+}
+
+const parseArgs = (args: string[]): ParsedArgs => {
+  const usage =
+    'Usage: cosense downloadFile <fileUrl> <outputPath> [--thumbnail] [--project <projectUrl>]';
+  let thumbnail = false;
+  let project: string | undefined;
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] as string;
+    if (arg === '--thumbnail') {
+      thumbnail = true;
+    } else if (arg === '--project') {
+      if (project !== undefined) {
+        throw new Error(`--project specified multiple times\n${usage}`);
+      }
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error(`--project requires a value\n${usage}`);
+      }
+      project = value;
+      i += 1;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}\n${usage}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length !== 2) {
+    throw new Error(usage);
+  }
+  return {
+    fileUrl: positional[0] as string,
+    outputPath: positional[1] as string,
+    thumbnail,
+    project
+  };
+};
+
+export const downloadFile = async (args: string[]): Promise<void> => {
+  const { fileUrl, outputPath, thumbnail, project } = parseArgs(args);
+  const { origin, fileId } = parseFileUrl(fileUrl);
+  const credential = resolveFileCredential(origin, project);
+  let requestUrl = `${origin}/files/${fileId}`;
+  if (thumbnail) requestUrl += '?type=thumbnail';
+  const result = await downloadToFile(requestUrl, outputPath, { credential });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+};

package/src/commands/readFileInfo.ts

@@ -0,0 +1,81 @@
+import { parseFileUrl } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveFileCredential } from '../lib/resolveFileCredential.ts';
+
+export const readFileInfoSummary =
+  'ファイルのメタデータと抽出済みテキストを取得する';
+
+export const readFileInfoHelp = `readFileInfo - ファイルのメタデータと抽出済みテキストを取得する
+
+Usage:
+  cosense readFileInfo <fileUrl> [--project <projectUrl>]
+
+引数:
+  <fileUrl>  ファイルのURL（例: https://scrapbox.io/files/5f151efbacbb17001a58f120.pdf）。query/hashは付けない
+
+オプション:
+  --project <projectUrl>  Service Account認証で取得する時に、ファイルが属するprojectのURLを指定する（例: https://scrapbox.io/example）。省略時はPersonal Access Tokenを使う
+
+戻り値（top-levelの主なkey）:
+  id            string   ファイルID
+  projectName   string   ファイルが属するproject名
+  text          string?  ファイルから抽出されたテキスト（画像のOCR、PDFの本文等）。先頭10000文字まで
+  originalname  string?  アップロード時のファイル名
+  contentType   string?  ファイルのContent-Type
+  size          number?  ファイルのbyte数
+
+例:
+  cosense readFileInfo 'https://scrapbox.io/files/5f151efbacbb17001a58f120.pdf'
+
+絞り込み例（jqで欲しい部分だけ抜き出す）:
+  抽出済みテキストだけ:
+    cosense readFileInfo <fileUrl> | jq -r '.text'
+
+HTTPエラー:
+  401/403: 認証・権限が無い。private projectのファイルはproject member権限が必要
+  404: fileIdに対応するファイルが存在しない
+`;
+
+interface ParsedArgs {
+  fileUrl: string;
+  project?: string;
+}
+
+const parseArgs = (args: string[]): ParsedArgs => {
+  const usage =
+    'Usage: cosense readFileInfo <fileUrl> [--project <projectUrl>]';
+  let project: string | undefined;
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] as string;
+    if (arg === '--project') {
+      if (project !== undefined) {
+        throw new Error(`--project specified multiple times\n${usage}`);
+      }
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error(`--project requires a value\n${usage}`);
+      }
+      project = value;
+      i += 1;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}\n${usage}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length !== 1) {
+    throw new Error(usage);
+  }
+  return { fileUrl: positional[0] as string, project };
+};
+
+export const readFileInfo = async (args: string[]): Promise<void> => {
+  const { fileUrl, project } = parseArgs(args);
+  const { origin, fileId } = parseFileUrl(fileUrl);
+  const credential = resolveFileCredential(origin, project);
+  const data = await requestJson(`${origin}/api/gcs/${fileId}/info`, {
+    credential
+  });
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/lib/literateDatabase.ts

@@ -0,0 +1,133 @@
+import { type Page, toTitleLc } from './relatedPagesFormat.ts';
+
+interface InfoboxResultEntry {
+  title?: string;
+  infobox?: Record<string, string>;
+}
+
+export interface LiterateDatabaseSourcePage extends Page {
+  linksLc?: string[];
+  created?: number;
+  updated?: number;
+  infoboxResult?: InfoboxResultEntry[];
+  infoboxDisableLinks?: string[];
+}
+
+interface Links1hopResponse {
+  links1hop?: LiterateDatabaseSourcePage[];
+  pagination?: { total?: number; hasNext?: boolean };
+}
+
+export interface DefinitionPage {
+  title?: string;
+  infoboxDefinition?: string[];
+}
+
+// 定義行はタブ区切りで、第1セルが列名。第2セル以降はInfoboxが値を抜き出す時の
+// 指示文なので列にしない。第1セルがオプション宣言 (ExcludeTitleLine) の行も列にしない。
+// 列名をtrimしないのは意図的: infoboxResultのkeyは未trimの第1セルで生成されるため、
+// trimするとlookupが外れる（オプション宣言の判定だけがtrim込みで行われる）
+const parseInfoboxFieldNames = (infoboxDefinition: string[]): string[] => {
+  const fieldNames: string[] = [];
+  for (const row of infoboxDefinition) {
+    const firstCell = row.split('\t')[0] ?? '';
+    if (firstCell.trim() === 'ExcludeTitleLine') continue;
+    fieldNames.push(firstCell);
+  }
+  return fieldNames;
+};
+
+interface LiterateDatabaseRow {
+  page: LiterateDatabaseSourcePage;
+  infobox: Record<string, string>;
+}
+
+// 行選定はWeb UIの文芸的データベースと同じ:
+// 定義ページにリンクしているページのうち、無効化されていないもの。
+// 並びは通常の関連ページリストとソート基準を揃えたpageRank降順（Web UIとは異なる）
+const buildRows = (
+  definition: DefinitionPage,
+  links1hop: LiterateDatabaseSourcePage[]
+): LiterateDatabaseRow[] => {
+  const definitionTitleLc = toTitleLc(definition.title ?? '');
+
+  const rows: LiterateDatabaseRow[] = [];
+  for (const page of links1hop) {
+    const linksLc = page.linksLc ?? [];
+    if (!linksLc.includes(definitionTitleLc)) continue;
+    if (page.infoboxDisableLinks?.includes(definitionTitleLc)) continue;
+
+    const infobox =
+      page.infoboxResult?.find(
+        entry => toTitleLc(entry.title ?? '') === definitionTitleLc
+      )?.infobox ?? {};
+    rows.push({ page, infobox });
+  }
+
+  rows.sort((a, b) => (b.page.pageRank ?? 0) - (a.page.pageRank ?? 0));
+  return rows;
+};
+
+// TSVの1ページ=1行を守るため、セル内の改行・タブを置換する。
+// セル値はAIが抽出した物なので、文字列以外が混ざっていても落ちないように文字列化する
+const sanitizeCell = (value: unknown): string =>
+  String(value ?? '')
+    .replace(/\t/g, ' ')
+    .replace(/\r\n|[\r\n]/g, ' / ');
+
+const formatDateCell = (unixSec: number | undefined): string => {
+  if (typeof unixSec !== 'number') return '';
+  const d = new Date(unixSec * 1000);
+  const month = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${d.getFullYear()}-${month}-${day}`;
+};
+
+// 対象がinfobox定義ページなら文芸的データベースのセクションを組み立てる。
+// 定義ページでなければ null。表に載せたページは seen に積み、呼び出し側の
+// 1 hop link 一覧に再掲されないようにする
+export const renderLiterateDatabase = (
+  definition: DefinitionPage,
+  hopValue: unknown,
+  seen: Set<string>
+): string | null => {
+  const infoboxDefinition = definition.infoboxDefinition ?? [];
+  if (infoboxDefinition.length === 0) return null;
+
+  const { links1hop = [], pagination } = (hopValue ?? {}) as Links1hopResponse;
+  const fieldNames = parseInfoboxFieldNames(infoboxDefinition);
+  const rows = buildRows(definition, links1hop);
+  for (const { page } of rows) {
+    seen.add(page.titleLc ?? toTitleLc(page.title));
+  }
+
+  const header = ['Page', 'Created', 'Updated', ...fieldNames].join('\t');
+  const lines = rows.map(({ page, infobox }) =>
+    [
+      sanitizeCell(page.title),
+      formatDateCell(page.created),
+      formatDateCell(page.updated),
+      ...fieldNames.map(field => sanitizeCell(infobox[field] ?? ''))
+    ].join('\t')
+  );
+
+  // 見出しは通常ページの「1 hop link」に揃える。「文芸的データベース」を見出し単体で
+  // 使うと、出力だけを読むAIが同名ページを探しに行ってしまう。ただしユーザーはこの表を
+  // 「文芸的データベース」「Infoboxの表」「テーブル」等とも呼ぶので、指示と結びつくよう
+  // 別名として括弧内に残す
+  const parts = [
+    '## 1 hop link（Infoboxの文芸的データベース、TSV形式のテーブル）',
+    'Page/Created/Updated以外の列は、各ページの本文からInfoboxが抜き出した値',
+    [header, ...lines].join('\n')
+  ];
+  if (rows.length === 0) {
+    // ヘッダーだけの表は出力が途切れたようにも見えるので、0件である事を明示する
+    parts.push('表に載るページが無いため、行は0件');
+  }
+  if (pagination?.hasNext) {
+    parts.push(
+      `注意: 関連ページが多いため、全${pagination.total}件のうち取得できた${links1hop.length}件から表を構成しています`
+    );
+  }
+  return parts.join('\n\n');
+};

package/src/lib/parseUrl.ts

@@ -45,6 +45,30 @@ export const parseProjectUrlStrict = (input: string): ProjectUrl => {
   return { origin: u.origin, projectName: m[1] as string };
 };
 
+export interface FileUrl {
+  origin: string;
+  fileId: string;
+}
+
+export const parseFileUrl = (input: string): FileUrl => {
+  const u = new URL(input);
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`File URL must use http: or https: scheme: ${input}`);
+  }
+  if (u.search || u.hash) {
+    throw new Error(
+      `File URL must not have query/hash (use --thumbnail to fetch thumbnail), got: ${input}`
+    );
+  }
+  const m = u.pathname.match(/^\/files\/([0-9a-f]{24})(?:\..*)?$/);
+  if (!m) {
+    throw new Error(
+      `File URL must be https://<host>/files/<fileId>[.<ext>], got: ${input}`
+    );
+  }
+  return { origin: u.origin, fileId: m[1] as string };
+};
+
 export const parsePageUrl = (input: string): PageUrl => {
   const u = new URL(input);
   const m = u.pathname.match(/^\/([^/]+)\/(.+?)\/?$/);

package/src/lib/relatedPagesFormat.ts

@@ -40,7 +40,7 @@ export const buildGroups = (pages: Page[]): Group[] => {
   return groups;
 };
 
-const toTitleLc = (title: string): string =>
+export const toTitleLc = (title: string): string =>
   title.replace(/ /g, '_').toLowerCase();
 
 export const dedupAndSortByPageRank = (

package/src/lib/request.ts

@@ -1,3 +1,10 @@
+import { createWriteStream } from 'node:fs';
+import { rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { Credential } from './settings.ts';
+
 export class HttpError extends Error {
   readonly status: number;
   readonly statusText: string;
@@ -31,20 +38,16 @@ export class HttpError extends Error {
   }
 }
 
-import type { Credential } from './settings.ts';
-
 interface RequestOptions {
   credential?: Credential;
   method?: 'GET' | 'POST';
   body?: unknown;
 }
 
-export const requestJson = async (
-  url: string,
-  options?: RequestOptions
-): Promise<unknown> => {
+const buildCredentialHeaders = (
+  credential?: Credential
+): Record<string, string> => {
   const headers: Record<string, string> = {};
-  const credential = options?.credential;
   if (credential) {
     if (credential.type === 'serviceAccount') {
       headers['x-service-account-access-key'] = credential.value;
@@ -52,6 +55,14 @@ export const requestJson = async (
       headers['x-personal-access-token'] = credential.value;
     }
   }
+  return headers;
+};
+
+export const requestJson = async (
+  url: string,
+  options?: RequestOptions
+): Promise<unknown> => {
+  const headers = buildCredentialHeaders(options?.credential);
   const method = options?.method ?? 'GET';
   const init: RequestInit = { method, headers };
   if (options?.body !== undefined) {
@@ -70,3 +81,82 @@ export const requestJson = async (
   }
   return res.json();
 };
+
+export interface DownloadResult {
+  path: string;
+  contentType: string | null;
+  size: number;
+}
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+export const downloadToFile = async (
+  url: string,
+  outputPath: string,
+  options?: { credential?: Credential }
+): Promise<DownloadResult> => {
+  const absPath = resolve(outputPath);
+  const targetStat = await stat(absPath).catch(() => null);
+  if (targetStat?.isDirectory()) {
+    throw new Error(`<outputPath> is a directory: ${outputPath}`);
+  }
+  const parentDir = dirname(absPath);
+  const parentStat = await stat(parentDir).catch(() => null);
+  if (!parentStat?.isDirectory()) {
+    throw new Error(`Parent directory does not exist: ${parentDir}`);
+  }
+
+  const headers = buildCredentialHeaders(options?.credential);
+  let res = await fetch(url, { headers, redirect: 'manual' });
+  if (REDIRECT_STATUSES.has(res.status)) {
+    const location = res.headers.get('location');
+    await res.body?.cancel();
+    if (!location) {
+      throw new Error(`HTTP ${res.status} without Location header: ${url}`);
+    }
+    const redirectUrl = new URL(location, url);
+    // credential headerは別originのredirect先に転送しない
+    res = await fetch(redirectUrl);
+    if (!res.ok) {
+      await res.body?.cancel();
+      throw new Error(
+        `HTTP ${res.status} ${res.statusText} from ${redirectUrl.origin}${redirectUrl.pathname}`
+      );
+    }
+  } else if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new HttpError({
+      status: res.status,
+      statusText: res.statusText,
+      url,
+      body
+    });
+  }
+  if (!res.body) {
+    throw new Error(`Empty response body: ${url}`);
+  }
+
+  const tmpPath = join(
+    parentDir,
+    `.${basename(absPath)}.${process.pid}.${Math.random().toString(36).slice(2)}.part`
+  );
+  try {
+    await pipeline(
+      Readable.fromWeb(res.body),
+      createWriteStream(tmpPath, { flags: 'wx' })
+    );
+    const { size } = await stat(tmpPath);
+    await rename(tmpPath, absPath);
+    return {
+      path: absPath,
+      contentType: res.headers.get('content-type'),
+      size
+    };
+  } catch (err) {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to write ${absPath}: ${message.replaceAll(tmpPath, absPath)}`
+    );
+  }
+};

package/src/lib/resolveFileCredential.ts

@@ -0,0 +1,30 @@
+import { parseProjectUrlStrict } from './parseUrl.ts';
+import {
+  resolveCredential,
+  resolveUserCredential,
+  type Credential
+} from './settings.ts';
+
+// fileUrlにはproject名が含まれないため、Service Account（project単位）を
+// 使う時だけ--projectでprojectUrlを受け取って解決する
+export const resolveFileCredential = (
+  fileOrigin: string,
+  projectUrl: string | undefined
+): Credential | undefined => {
+  if (projectUrl === undefined) {
+    return resolveUserCredential(fileOrigin);
+  }
+  const { origin, projectName } = parseProjectUrlStrict(projectUrl);
+  if (origin !== fileOrigin) {
+    throw new Error(
+      `--project origin mismatch: ${origin} (--project) vs ${fileOrigin} (file URL)`
+    );
+  }
+  const credential = resolveCredential(origin, projectName);
+  if (!credential) {
+    throw new Error(
+      `No credential found for --project ${projectUrl}. Run \`cosense login ${projectUrl}\` to authenticate.`
+    );
+  }
+  return credential;
+};