@helpfeel/cosense-cli 1.13.0 → 1.14.1

package/package.json

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

package/src/cli.ts

@@ -42,6 +42,11 @@ import {
   listPagesHelp,
   listPagesSummary
 } from './commands/listPages.ts';
+import {
+  listPageSnapshots,
+  listPageSnapshotsHelp,
+  listPageSnapshotsSummary
+} from './commands/listPageSnapshots.ts';
 import {
   listProjects,
   listProjectsHelp,
@@ -68,6 +73,11 @@ import {
   readPageHelp,
   readPageSummary
 } from './commands/readPage.ts';
+import {
+  readPageSnapshot,
+  readPageSnapshotHelp,
+  readPageSnapshotSummary
+} from './commands/readPageSnapshot.ts';
 import {
   readProjectMembers,
   readProjectMembersHelp,
@@ -149,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,
@@ -179,6 +194,11 @@ const commands: Record<string, CommandSpec> = {
     summary: listPagesSummary,
     help: listPagesHelp
   },
+  listPageSnapshots: {
+    handler: listPageSnapshots,
+    summary: listPageSnapshotsSummary,
+    help: listPageSnapshotsHelp
+  },
   list1hopLinks: {
     handler: list1hopLinks,
     summary: list1hopLinksSummary,

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

@@ -15,7 +15,9 @@ Usage:
   <pageId>      削除対象ページのID。 readPage 出力の top-level "id" field から取得する
 
 戻り値（plain text）:
-  previewId / expireAt / status (delete) / project / title のヘッダー + 削除されるpage全体。
+  previewId / expireAt / status (delete) / project / title / commitId のヘッダー +
+  削除されるpage全体。
+  commitId は preview を作った時点の削除対象ページの最新コミット。
   preview は dry-run なのでこの段階では削除されない。
   previewId を submitEdit に渡すと削除が確定する。5分で expire する。
 
@@ -27,6 +29,7 @@ HTTPエラー:
 
 interface PagePreview {
   title?: string;
+  commitId?: string;
   lines?: { id: string; text: string }[];
 }
 
@@ -67,6 +70,7 @@ export const previewDelete = async (args: string[]): Promise<void> => {
   lines.push('status:    delete');
   lines.push(`project:   ${projectName}`);
   lines.push(`title:     ${response.pagePreview?.title ?? ''}`);
+  lines.push(`commitId:  ${response.pagePreview?.commitId ?? ''}`);
   lines.push('');
   lines.push('page (will be deleted):');
   for (const line of response.pagePreview?.lines ?? []) {

package/src/commands/previewEdit.ts

@@ -47,8 +47,10 @@ stdinから受け取る入力形式（既存ページ編集モード, JSON）:
   する必要がある（消えた lineId を anchor に指定すると 422）。
 
 戻り値（plain text）:
-  previewId / expireAt / status (create or update) / project / title のヘッダー +
+  previewId / expireAt / status (create or update) / project / title / commitId のヘッダー +
   ops summary + 適用後 page 全体。
+  commitId は preview を作った時点の編集対象ページの最新コミット。 新規作成 (status: create)
+  では出力されない。
   変更行の頭には > (新規) または * (更新) のマーカーと末尾 # <lineId> が付く。
   既存行(変更なし)はマーカーなし。
   preview は dry-run なのでこの段階ではpage URLは確定しない。 確定URLは submitEdit の出力で確認する。
@@ -98,6 +100,7 @@ type RawChange = RawInsertChange | RawUpdateChange | RawDeleteChange;
 interface PagePreview {
   title?: string;
   persistent?: boolean;
+  commitId?: string;
   lines?: { id: string; text: string }[];
 }
 
@@ -212,6 +215,10 @@ const formatPreview = (
   lines.push(`status:    ${status}`);
   lines.push(`project:   ${projectName}`);
   lines.push(`title:     ${title}`);
+  // 新規作成 (persistent: false) のページにはまだcommitが無く、サーバーもcommitIdを返さない
+  if (typeof pagePreview?.commitId === 'string') {
+    lines.push(`commitId:  ${pagePreview.commitId}`);
+  }
   lines.push('');
   lines.push('ops:');
   for (const op of ops) {

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`);
+};