@helpfeel/cosense-cli 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpfeel/cosense-cli",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Cosense (旧Scrapbox) のページを読み・調べ・編集するAgent Skill用のCLI",
   "homepage": "https://github.com/helpfeel/cosense-cli",
   "license": "MIT",

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/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/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/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;
+};