@helpfeel/cosense-cli 1.12.1 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpfeel/cosense-cli",
-  "version": "1.12.1",
+  "version": "1.14.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 {
+  deleteFile,
+  deleteFileHelp,
+  deleteFileSummary
+} from './commands/deleteFile.ts';
 import {
   downloadFile,
   downloadFileHelp,
@@ -37,12 +42,22 @@ import {
   listPagesHelp,
   listPagesSummary
 } from './commands/listPages.ts';
+import {
+  listPageSnapshots,
+  listPageSnapshotsHelp,
+  listPageSnapshotsSummary
+} from './commands/listPageSnapshots.ts';
 import {
   listProjects,
   listProjectsHelp,
   listProjectsSummary
 } from './commands/listProjects.ts';
 import { login, loginHelp, loginSummary } from './commands/login.ts';
+import {
+  previewDelete,
+  previewDeleteHelp,
+  previewDeleteSummary
+} from './commands/previewDelete.ts';
 import {
   previewEdit,
   previewEditHelp,
@@ -58,6 +73,11 @@ import {
   readPageHelp,
   readPageSummary
 } from './commands/readPage.ts';
+import {
+  readPageSnapshot,
+  readPageSnapshotHelp,
+  readPageSnapshotSummary
+} from './commands/readPageSnapshot.ts';
 import {
   readProjectMembers,
   readProjectMembersHelp,
@@ -139,6 +159,11 @@ const commands: Record<string, CommandSpec> = {
     help: browseRelatedPagesHelp
   },
   readPage: { handler: readPage, summary: readPageSummary, help: readPageHelp },
+  readPageSnapshot: {
+    handler: readPageSnapshot,
+    summary: readPageSnapshotSummary,
+    help: readPageSnapshotHelp
+  },
   readFileInfo: {
     handler: readFileInfo,
     summary: readFileInfoSummary,
@@ -154,6 +179,11 @@ const commands: Record<string, CommandSpec> = {
     summary: uploadFileSummary,
     help: uploadFileHelp
   },
+  deleteFile: {
+    handler: deleteFile,
+    summary: deleteFileSummary,
+    help: deleteFileHelp
+  },
   readProjectMembers: {
     handler: readProjectMembers,
     summary: readProjectMembersSummary,
@@ -164,6 +194,11 @@ const commands: Record<string, CommandSpec> = {
     summary: listPagesSummary,
     help: listPagesHelp
   },
+  listPageSnapshots: {
+    handler: listPageSnapshots,
+    summary: listPageSnapshotsSummary,
+    help: listPageSnapshotsHelp
+  },
   list1hopLinks: {
     handler: list1hopLinks,
     summary: list1hopLinksSummary,
@@ -199,6 +234,11 @@ const commands: Record<string, CommandSpec> = {
     summary: previewEditSummary,
     help: previewEditHelp
   },
+  previewDelete: {
+    handler: previewDelete,
+    summary: previewDeleteSummary,
+    help: previewDeleteHelp
+  },
   submitEdit: {
     handler: submitEdit,
     summary: submitEditSummary,

package/src/commands/deleteFile.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 deleteFileSummary = 'ファイルをprojectから削除する';
+
+export const deleteFileHelp = `deleteFile - ファイルをprojectから削除する
+
+Usage:
+  cosense deleteFile <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を使う
+
+出力（JSON）:
+  success  boolean  削除に成功したらtrue
+
+削除後、ファイルが所属するproject内でこのファイルを埋め込んでいるページの本文はサーバーが自動修正するため、クライアント側での本文修正は不要。
+
+例:
+  cosense deleteFile 'https://scrapbox.io/files/5f151efbacbb17001a58f120.pdf'
+
+HTTPエラー:
+  401/403: 認証・権限が無い。projectのmember権限（またはprojectのService Account）が必要
+  404: fileIdに対応するファイルが存在しない
+`;
+
+interface ParsedArgs {
+  fileUrl: string;
+  project?: string;
+}
+
+const parseArgs = (args: string[]): ParsedArgs => {
+  const usage = 'Usage: cosense deleteFile <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 deleteFile = async (args: string[]): Promise<void> => {
+  const { fileUrl, project } = parseArgs(args);
+  const { origin, fileId } = parseFileUrl(fileUrl);
+  const credential = resolveFileCredential(origin, project);
+  if (!credential) {
+    throw new Error(
+      `No credential found for ${origin}. Run \`cosense login ${origin}\` to authenticate.`
+    );
+  }
+  const data = (await requestJson(`${origin}/api/gcs/${fileId}`, {
+    credential,
+    method: 'DELETE'
+  })) as { success?: unknown };
+  if (data?.success !== true) {
+    throw new Error(`unexpected delete response: ${JSON.stringify(data)}`);
+  }
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/listPageSnapshots.ts

@@ -0,0 +1,65 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parseProjectUrlStrict } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const listPageSnapshotsSummary =
+  'ページのsnapshot一覧(Page History)をpageId起点で取得する';
+
+export const listPageSnapshotsHelp = `listPageSnapshots - ページのsnapshot一覧(Page History)をpageId起点で取得する
+
+Usage:
+  cosense listPageSnapshots <projectUrl> <pageId>
+
+引数:
+  <projectUrl>  プロジェクトのURL (例: https://scrapbox.io/shokai)。 末尾に余分なpathがあるとerror
+  <pageId>      ページの不変ID。browsePage / readPage の出力に含まれる
+
+戻り値（top-levelのkey）:
+  pageId      string                   対象ページのID
+  timestamps  Array<{ id, created }>   snapshotの一覧。新しい順、最新100件まで
+    id        string                   snapshotのID。readPageSnapshot に渡す
+    created   string                   snapshot時点のページ最終更新時刻
+
+戻り値のJSON抜粋例:
+{
+  "pageId": "5803c5397ad353b0aee24341",
+  "timestamps": [
+    {
+      "id": "5cef4052dd15ed00447c1405",
+      "created": "2019-05-30T11:29+09:00 (7 years ago)"
+    }
+  ]
+}
+
+HTTPエラー:
+  HTTP 401  認証なし
+  HTTP 403  権限不足（projectのmemberでない 等）
+  HTTP 404  pageId に対応するpageが存在しない / pageId が不正な形式
+`;
+
+interface ListPageSnapshotsData {
+  timestamps?: { id?: string; created?: number | string }[];
+}
+
+export const listPageSnapshots = async (args: string[]): Promise<void> => {
+  if (args.length !== 2) {
+    throw new Error('Usage: cosense listPageSnapshots <projectUrl> <pageId>');
+  }
+  const [projectUrl, pageId] = args as [string, string];
+
+  const { origin, projectName } = parseProjectUrlStrict(projectUrl);
+  const credential = resolveCredential(origin, projectName);
+
+  // APIはx-following-idレスポンスヘッダで100件ずつページングするが、最新100件のみ返し追跡しない
+  const apiUrl = `${origin}/api/page-snapshots/${projectName}/${pageId}`;
+  const data = (await requestJson(apiUrl, {
+    credential
+  })) as ListPageSnapshotsData;
+
+  for (const timestamp of data.timestamps ?? []) {
+    enrichTimestampsOf(timestamp as Record<string, unknown>, ['created']);
+  }
+
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/previewDelete.ts

@@ -0,0 +1,76 @@
+import { parseProjectUrlStrict } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const previewDeleteSummary =
+  'ページ削除をdry-runしてpreviewIdを取得する';
+
+export const previewDeleteHelp = `previewDelete - ページ削除をdry-runしてpreviewIdを取得する
+
+Usage:
+  cosense previewDelete <projectUrl> <pageId>
+
+引数:
+  <projectUrl>  プロジェクトのURL (例: https://scrapbox.io/shokai)。 末尾に余分なpathがあるとerror
+  <pageId>      削除対象ページのID。 readPage 出力の top-level "id" field から取得する
+
+戻り値（plain text）:
+  previewId / expireAt / status (delete) / project / title のヘッダー + 削除されるpage全体。
+  preview は dry-run なのでこの段階では削除されない。
+  previewId を submitEdit に渡すと削除が確定する。5分で expire する。
+
+HTTPエラー:
+  HTTP 401  認証なし
+  HTTP 403  権限不足（PAT利用時、projectのmemberでない 等）
+  HTTP 404  pageId に対応するpageが存在しない / pageId が不正な形式
+`;
+
+interface PagePreview {
+  title?: string;
+  lines?: { id: string; text: string }[];
+}
+
+interface PreviewResponse {
+  previewId: string;
+  expireAt: string;
+  pagePreview: PagePreview | null;
+  pageDelete?: boolean;
+}
+
+export const previewDelete = async (args: string[]): Promise<void> => {
+  if (args.length !== 2) {
+    throw new Error('Usage: cosense previewDelete <projectUrl> <pageId>');
+  }
+  const [projectUrl, pageId] = args as [string, string];
+
+  const { origin, projectName } = parseProjectUrlStrict(projectUrl);
+  // projectに紐づくService Accountがあればそれを、無ければPATを使う（読み取りと同じ）
+  const credential = resolveCredential(origin, projectName);
+
+  const apiUrl = `${origin}/api/pages/v2/${projectName}/page-edit-for-ai/preview`;
+  const response = (await requestJson(apiUrl, {
+    credential,
+    method: 'POST',
+    body: { pageId, changes: [{ deleted: true }] }
+  })) as PreviewResponse;
+
+  // 削除は破壊的操作なので、サーバーが削除previewとして受理した事を確認してから表示する
+  if (response.pageDelete !== true) {
+    throw new Error(
+      'server did not mark this preview as a page deletion. Do not submit the previewId.'
+    );
+  }
+
+  const lines: string[] = [];
+  lines.push(`previewId: ${response.previewId}`);
+  lines.push(`expireAt:  ${response.expireAt}`);
+  lines.push('status:    delete');
+  lines.push(`project:   ${projectName}`);
+  lines.push(`title:     ${response.pagePreview?.title ?? ''}`);
+  lines.push('');
+  lines.push('page (will be deleted):');
+  for (const line of response.pagePreview?.lines ?? []) {
+    lines.push(`  ${line.text}`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+};

package/src/commands/readPageSnapshot.ts

@@ -0,0 +1,138 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parseProjectUrlStrict } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { enrichUser, fetchUserMap } from '../lib/resolveUsers.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const readPageSnapshotSummary =
+  'snapshotのIDを指定してPage History上の過去の本文を読む';
+
+export const readPageSnapshotHelp = `readPageSnapshot - snapshotのIDを指定してPage History上の過去の本文を読む
+
+Usage:
+  cosense readPageSnapshot <projectUrl> <pageId> <snapshotId>
+
+引数:
+  <projectUrl>  プロジェクトのURL (例: https://scrapbox.io/shokai)。 末尾に余分なpathがあるとerror
+  <pageId>      ページの不変ID。browsePage / readPage の出力に含まれる
+  <snapshotId>  snapshotのID。listPageSnapshots の timestamps[].id から取得する
+
+戻り値（top-levelのkey）:
+  page      object   現在のページのメタデータ。field構成は readPage のtop-levelから本文・リンク系
+                     (lines / links / icons 等) を除いたもの。現在の本文は含まれない
+  snapshot  object   snapshot時点のページ
+    title     string       snapshot時点のページタイトル
+    created   string       snapshot時点のページ最終更新時刻
+    lines     Array<Line>  snapshot時点の本文。Line = { id, text, user, created, updated }
+
+戻り値のJSON抜粋例:
+{
+  "page": {
+    "id": "5803c5397ad353b0aee24341",
+    "title": "page1",
+    "commitId": "5cef401cfca37d0018dd9ead"
+  },
+  "snapshot": {
+    "title": "page1",
+    "created": "2019-05-30T11:29+09:00 (7 years ago)",
+    "lines": [
+      {
+        "id": "5803c5397ad353b0aee24341",
+        "text": "page1",
+        "user": { "id": "5803c4bd7ad353b0aee24328", "name": "shokai" },
+        "created": "2019-05-30T11:29+09:00 (7 years ago)",
+        "updated": "2019-05-30T11:29+09:00 (7 years ago)"
+      }
+    ]
+  }
+}
+
+絞り込み例（jqで欲しい部分だけ抜き出す）:
+  snapshot時点の各行のテキストだけ:
+    cosense readPageSnapshot <projectUrl> <pageId> <snapshotId> | jq -r '.snapshot.lines[].text'
+
+HTTPエラー:
+  HTTP 401  認証なし
+  HTTP 403  権限不足（projectのmemberでない 等）
+  HTTP 404  pageId に対応するpageが存在しない / snapshotId がこのページのsnapshotでない
+  HTTP 422  snapshotId が不正な形式
+`;
+
+interface UserRef {
+  id: string;
+}
+
+interface SnapshotLine {
+  id?: string;
+  text?: string;
+  userId?: string;
+  user?: UserRef;
+  created?: number | string;
+  updated?: number | string;
+}
+
+interface PageMetadata {
+  user?: UserRef | null;
+  lastUpdateUser?: UserRef | null;
+  users?: UserRef[];
+}
+
+interface ReadPageSnapshotData {
+  page?: PageMetadata;
+  snapshot?: {
+    created?: number | string;
+    lines?: SnapshotLine[];
+  };
+}
+
+export const readPageSnapshot = async (args: string[]): Promise<void> => {
+  if (args.length !== 3) {
+    throw new Error(
+      'Usage: cosense readPageSnapshot <projectUrl> <pageId> <snapshotId>'
+    );
+  }
+  const [projectUrl, pageId, snapshotId] = args as [string, string, string];
+
+  const { origin, projectName } = parseProjectUrlStrict(projectUrl);
+  const credential = resolveCredential(origin, projectName);
+
+  const apiUrl = `${origin}/api/page-snapshots/${projectName}/${pageId}/${snapshotId}`;
+  const data = (await requestJson(apiUrl, {
+    credential
+  })) as ReadPageSnapshotData;
+
+  const userMap = await fetchUserMap(origin, projectName);
+  const page = data.page;
+  if (page) {
+    enrichUser(page.user, userMap);
+    enrichUser(page.lastUpdateUser, userMap);
+    for (const editor of page.users ?? []) {
+      enrichUser(editor, userMap);
+    }
+    enrichTimestampsOf(page as Record<string, unknown>, [
+      'created',
+      'updated',
+      'accessed',
+      'snapshotCreated',
+      'lastAccessed'
+    ]);
+  }
+  const snapshot = data.snapshot;
+  if (snapshot) {
+    for (const line of snapshot.lines ?? []) {
+      const userId = line.userId;
+      if (typeof userId === 'string' && userId !== '') {
+        line.user = { id: userId };
+        delete line.userId;
+        enrichUser(line.user, userMap);
+      }
+      enrichTimestampsOf(line as Record<string, unknown>, [
+        'created',
+        'updated'
+      ]);
+    }
+    enrichTimestampsOf(snapshot as Record<string, unknown>, ['created']);
+  }
+
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/submitEdit.ts

@@ -4,16 +4,16 @@ import { requestJson } from '../lib/request.ts';
 import { resolveCredential } from '../lib/settings.ts';
 
 export const submitEditSummary =
-  'previewEditで取得したpreviewIdを使ってページ編集を確定する';
+  'previewEdit/previewDeleteで取得したpreviewIdを使ってページ編集・削除を確定する';
 
-export const submitEditHelp = `submitEdit - previewEditで取得したpreviewIdを使ってページ編集を確定する
+export const submitEditHelp = `submitEdit - previewEdit/previewDeleteで取得したpreviewIdを使ってページ編集・削除を確定する
 
 Usage:
   cosense submitEdit <projectUrl> <previewId>
 
 引数:
   <projectUrl>  プロジェクトのURL (例: https://scrapbox.io/shokai)。 末尾に余分なpathがあるとerror
-  <previewId>   previewEdit の戻り値の previewId
+  <previewId>   previewEdit または previewDelete の戻り値の previewId
 
 戻り値（plain text）:
   commitId: <生成されたcommitのID>
@@ -28,6 +28,11 @@ Usage:
   titleChanged: "<変更前title>" -> "<変更後title>"
   新旧タイトルはそれぞれJSON string
 
+  previewDelete の previewId を確定した時は、代わりに以下を出力する:
+  commitId: <生成されたcommitのID>
+  title:    <削除されたpage title>
+  deleted:  true
+
 HTTPエラー:
   HTTP 400  preview を生成した時と違う project の URL を渡している
   HTTP 401  認証なし
@@ -36,6 +41,9 @@ HTTPエラー:
   HTTP 409 {"error":"NotFastForward","latest":...}
             preview生成後にページが更新された。最新stateを再取得して ops を作り直し、
             previewEdit からやり直す必要がある
+  HTTP 409 {"error":"NotFastForward","latest":null}
+            対象ページが既に存在しない。削除の確定でこれが返った場合、ページは別経路で
+            削除済みであり、目的の状態は達成されている。リトライ不要
   HTTP 409 {"error":"DuplicateTitle"}
             preview→submit の間に他人が同名ページを作った (race condition)
 
@@ -45,6 +53,7 @@ previewId は1回限り (consume-on-submit)。submit 後・5分 expire 後・con
 interface SubmitResponse {
   commitId: string;
   page: { title?: string } | null;
+  pageDeleted?: { title?: string };
   titleChanged?: { from?: string; to?: string };
 }
 
@@ -64,6 +73,15 @@ export const submitEdit = async (args: string[]): Promise<void> => {
     body: { previewId }
   })) as SubmitResponse;
 
+  // pageDeletedはページ削除commitの確定時に返る。削除されたページにURLは無い
+  const pageDeleted = response.pageDeleted;
+  if (pageDeleted) {
+    process.stdout.write(
+      `commitId: ${response.commitId}\ntitle:    ${pageDeleted.title ?? ''}\ndeleted:  true\n`
+    );
+    return;
+  }
+
   const title = response.page?.title;
   if (typeof title !== 'string') {
     throw new Error(

package/src/lib/request.ts

@@ -40,7 +40,7 @@ export class HttpError extends Error {
 
 interface RequestOptions {
   credential?: Credential;
-  method?: 'GET' | 'POST';
+  method?: 'GET' | 'POST' | 'DELETE';
   body?: unknown;
 }