@helpfeel/cosense-cli 1.3.0

package/src/commands/previewEdit.ts

@@ -0,0 +1,349 @@
+import { randomBytes } from 'node:crypto';
+import { parseProjectUrlStrict } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveUserCredential } from '../lib/settings.ts';
+
+export const previewEditSummary =
+  'ページ編集opsをdry-runしてpreviewIdを取得する';
+
+export const previewEditHelp = `previewEdit - ページ編集opsをdry-runしてpreviewIdを取得する
+
+Usage:
+  cosense previewEdit <projectUrl> <pageId> < ops.json    既存ページの編集 (stdinはops JSON)
+  cosense previewEdit --new <projectUrl> < body.txt       新規ページ作成 (stdinはプレーンテキスト本文)
+  echo '<opsJSON>' | cosense previewEdit <projectUrl> <pageId>
+  echo '<text>'    | cosense previewEdit --new <projectUrl>
+
+引数:
+  <projectUrl>  プロジェクトのURL (例: https://scrapbox.io/shokai)。 末尾に余分なpathがあるとerror
+  <pageId>      編集対象ページのID。 readPage 出力の top-level "id" field から取得する
+
+オプション:
+  --new   stdin をプレーンテキスト本文として受け取り、 新規ページを作る。 改行で複数行に分割され、
+          1行目が page title、 2行目以降が本文として扱われる。 ops JSON を組み立てる必要は無い
+
+stdinから受け取る入力形式（既存ページ編集モード, JSON）:
+  {
+    "ops": [
+      {"insertBefore": "<lineId> | _end", "text": "..."},
+      {"replace":      "<lineId>", "text": "..."},
+      {"delete":       "<lineId>"}
+    ]
+  }
+
+  insertBefore: <lineId> の直前に新規行を挿入する。textに改行(\\n)を含めると複数行を順に挿入する。
+                anchor に "_end" を指定するとページ末尾に挿入する
+  replace:      <lineId> の本文を置き換える。textは単行のみ。改行を含むtextは拒否される
+  delete:       <lineId> の行を削除する
+
+  「特定行を複数行に分割したい」場合は、insertBefore で対象lineIdの直前に複数行を挿入してから、
+  対象行を delete する。ops は配列順に適用されるので「先に delete してから insertBefore」 とすると
+  anchor が消えて 422 になる。
+
+  ops は順次適用される。同じ lineId に対する insertBefore を [A, B, C] の順で並べると、
+  適用後の行順は元行の直前に [A, B, C] が並ぶ（入力順が保たれる）。
+
+戻り値（plain text）:
+  previewId / expireAt / status (create or update) / project / title のヘッダー +
+  ops summary + 適用後 page 全体。
+  変更行の頭には > (新規) または * (更新) のマーカーと末尾 # <lineId> が付く。
+  既存行(変更なし)はマーカーなし。
+  preview は dry-run なのでこの段階ではpage URLは確定しない。 確定URLは submitEdit の出力で確認する。
+
+  submitEdit でこのpreviewIdを渡してcommitを確定する。previewIdは5分でexpireする。
+
+HTTPエラー:
+  HTTP 401  認証なし
+  HTTP 403  非memberまたはService Account（書き込みはPAT限定）
+  HTTP 404  pageId に対応するpageが存在しない / pageId が不正な形式
+  HTTP 409 {"error":"NotFastForward","latest":...}
+            preview生成後にページが更新された。最新stateを再取得して ops を作り直す必要がある
+  HTTP 422  ops が不正/存在しないlineId/replace に多行textを渡した等
+
+ワークフロー例（既存ページの編集）:
+  cosense readPage https://scrapbox.io/shokai/foo > page.json
+  # page.json から top-level id (pageId) と編集したい行の lineId を把握する
+  cosense previewEdit https://scrapbox.io/shokai <pageId> < ops.json
+  # 出力の plain text を読み、適用後の状態を確認してから submit
+  cosense submitEdit https://scrapbox.io/shokai <previewId>
+
+ワークフロー例（新規ページ作成）:
+  printf 'ページタイトル\\n本文1行目\\n本文2行目\\n' \\
+    | cosense previewEdit --new https://scrapbox.io/shokai
+  cosense submitEdit https://scrapbox.io/shokai <previewId>
+`;
+
+interface InsertBeforeOp {
+  insertBefore: string;
+  text?: string;
+}
+
+interface ReplaceOp {
+  replace: string;
+  text?: string;
+}
+
+interface DeleteOp {
+  delete: string;
+}
+
+type Op = InsertBeforeOp | ReplaceOp | DeleteOp;
+
+interface RawInsertChange {
+  _insert: string;
+  lines: { id: string; text: string };
+}
+
+interface RawUpdateChange {
+  _update: string;
+  lines: { text: string };
+}
+
+interface RawDeleteChange {
+  _delete: string;
+}
+
+type RawChange = RawInsertChange | RawUpdateChange | RawDeleteChange;
+
+interface PagePreview {
+  title?: string;
+  persistent?: boolean;
+  lines?: { id: string; text: string }[];
+}
+
+interface PreviewResponse {
+  previewId: string;
+  expireAt: string;
+  pagePreview: PagePreview | null;
+}
+
+const newLineId = (): string => randomBytes(12).toString('hex');
+
+const opKind = (op: unknown): 'insertBefore' | 'replace' | 'delete' | null => {
+  if (!op || typeof op !== 'object') return null;
+  const o = op as Record<string, unknown>;
+  const kinds = (['insertBefore', 'replace', 'delete'] as const).filter(
+    k => k in o
+  );
+  if (kinds.length !== 1) return null;
+  return kinds[0] ?? null;
+};
+
+interface TranslateResult {
+  changes: RawChange[];
+  newLineIds: Set<string>;
+  updatedLineIds: Set<string>;
+}
+
+const translateOps = (ops: unknown): TranslateResult => {
+  if (!Array.isArray(ops)) {
+    throw new Error('ops must be an Array');
+  }
+  const changes: RawChange[] = [];
+  const newLineIds = new Set<string>();
+  const updatedLineIds = new Set<string>();
+
+  for (const op of ops) {
+    const kind = opKind(op);
+    if (kind === null) {
+      throw new Error(
+        'each op must have exactly one of insertBefore / replace / delete'
+      );
+    }
+    if (kind === 'insertBefore') {
+      const o = op as InsertBeforeOp;
+      if (typeof o.insertBefore !== 'string') {
+        throw new Error('insertBefore must be a string lineId');
+      }
+      if (typeof o.text !== 'string') {
+        throw new Error('insertBefore.text must be a string');
+      }
+      for (const lineText of o.text.split(/\r?\n/)) {
+        const id = newLineId();
+        changes.push({
+          _insert: o.insertBefore,
+          lines: { id, text: lineText }
+        });
+        newLineIds.add(id);
+      }
+    } else if (kind === 'replace') {
+      const o = op as ReplaceOp;
+      if (typeof o.replace !== 'string') {
+        throw new Error('replace must be a string lineId');
+      }
+      if (typeof o.text !== 'string') {
+        throw new Error('replace.text must be a string');
+      }
+      if (/\r?\n/.test(o.text)) {
+        throw new Error(
+          'replace does not support multi-line text. To split a line into multiple lines, insertBefore the new lines first, then delete the original line.'
+        );
+      }
+      changes.push({ _update: o.replace, lines: { text: o.text } });
+      updatedLineIds.add(o.replace);
+    } else {
+      const o = op as DeleteOp;
+      if (typeof o.delete !== 'string') {
+        throw new Error('delete must be a string lineId');
+      }
+      changes.push({ _delete: o.delete });
+    }
+  }
+
+  return { changes, newLineIds, updatedLineIds };
+};
+
+const summarizeOp = (op: Op): string => {
+  if ('insertBefore' in op) {
+    const text = typeof op.text === 'string' ? op.text : '';
+    const lineCount = text.split(/\r?\n/).length;
+    return `  insertBefore ${op.insertBefore}: ${lineCount} line(s)`;
+  }
+  if ('replace' in op) {
+    const text = typeof op.text === 'string' ? op.text : '';
+    return `  replace      ${op.replace}: ${JSON.stringify(text)}`;
+  }
+  return `  delete       ${op.delete}`;
+};
+
+const formatPreview = (
+  response: PreviewResponse,
+  ops: Op[],
+  ids: { newLineIds: Set<string>; updatedLineIds: Set<string> },
+  projectName: string
+): string => {
+  const { pagePreview } = response;
+  const status =
+    pagePreview && pagePreview.persistent === false ? 'create' : 'update';
+  const title = pagePreview?.title ?? '';
+  const lines: string[] = [];
+  lines.push(`previewId: ${response.previewId}`);
+  lines.push(`expireAt:  ${response.expireAt}`);
+  lines.push(`status:    ${status}`);
+  lines.push(`project:   ${projectName}`);
+  lines.push(`title:     ${title}`);
+  lines.push('');
+  lines.push('ops:');
+  for (const op of ops) {
+    lines.push(summarizeOp(op));
+  }
+  lines.push('');
+  lines.push('page (after apply):');
+  for (const line of pagePreview?.lines ?? []) {
+    if (ids.newLineIds.has(line.id)) {
+      lines.push(`> ${line.text} # ${line.id}`);
+    } else if (ids.updatedLineIds.has(line.id)) {
+      lines.push(`* ${line.text} # ${line.id}`);
+    } else {
+      lines.push(`  ${line.text}`);
+    }
+  }
+  return lines.join('\n');
+};
+
+const readStdin = async (): Promise<string> => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+interface ParsedArgs {
+  isNew: boolean;
+  projectUrl: string;
+  pageId: string | undefined;
+}
+
+const parseArgs = (args: string[]): ParsedArgs => {
+  const usage =
+    'Usage: cosense previewEdit <projectUrl> <pageId> < ops.json (use --new <projectUrl> < body.txt for new pages)';
+  let isNew = false;
+  const positional: string[] = [];
+  for (const arg of args) {
+    if (arg === '--new') {
+      if (isNew) {
+        throw new Error(`Duplicate option: --new\n${usage}`);
+      }
+      isNew = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}\n${usage}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (isNew) {
+    if (positional.length !== 1) {
+      throw new Error(
+        'Usage: cosense previewEdit --new <projectUrl> < body.txt'
+      );
+    }
+    return { isNew, projectUrl: positional[0] as string, pageId: undefined };
+  }
+  if (positional.length !== 2) {
+    throw new Error(usage);
+  }
+  return {
+    isNew,
+    projectUrl: positional[0] as string,
+    pageId: positional[1] as string
+  };
+};
+
+export const previewEdit = async (args: string[]): Promise<void> => {
+  const { isNew, projectUrl, pageId } = parseArgs(args);
+
+  if (process.stdin.isTTY) {
+    throw new Error(
+      isNew
+        ? 'previewEdit --new reads plain text body from stdin. Pipe it in, e.g. `printf "Title\\nbody\\n" | cosense previewEdit --new <projectUrl>`.'
+        : 'previewEdit reads ops JSON from stdin. Pipe it in, e.g. `cosense previewEdit <projectUrl> <pageId> < ops.json`.'
+    );
+  }
+
+  const { origin, projectName } = parseProjectUrlStrict(projectUrl);
+  const stdinRaw = await readStdin();
+  if (!stdinRaw.trim()) {
+    throw new Error(
+      isNew
+        ? 'stdin is empty. Pipe page body (plain text) to stdin.'
+        : 'stdin is empty. Pipe ops JSON to stdin.'
+    );
+  }
+
+  // --new はプレーンテキスト本文を _end への単一 _insert に変換する。 ops JSON を組み立てる
+  // 冗長さを避けるショートカット。 改行は translateOps が複数行 _insert に分割する。
+  // body 全体に .trim() を当てると意図的な空行(先頭/末尾)が消えるので、 Unix line terminator
+  // 慣習で末尾の単一改行 (LF または CRLF) だけ取り除く
+  let ops: unknown;
+  if (isNew) {
+    const body = stdinRaw.replace(/\r?\n$/, '');
+    ops = [{ insertBefore: '_end', text: body }];
+  } else {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(stdinRaw);
+    } catch (err) {
+      throw new Error(
+        `stdin is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    ops = (parsed as { ops?: unknown }).ops;
+  }
+  const { changes, newLineIds, updatedLineIds } = translateOps(ops);
+
+  // 書き込み系 API は PAT 限定 (Service Account 拒否) なので、PAT を直接解決する
+  const credential = resolveUserCredential(origin);
+
+  const apiUrl = `${origin}/api/pages/v2/${projectName}/page-edit-for-ai/preview`;
+  const requestBody = pageId ? { pageId, changes } : { changes };
+  const response = (await requestJson(apiUrl, {
+    credential,
+    method: 'POST',
+    body: requestBody
+  })) as PreviewResponse;
+
+  process.stdout.write(
+    `${formatPreview(response, ops as Op[], { newLineIds, updatedLineIds }, projectName)}\n`
+  );
+};

package/src/commands/readPage.ts

@@ -0,0 +1,148 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parsePageUrl } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { fetchUserMap, enrichUser } from '../lib/resolveUsers.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const readPageSummary = '単一ページを読む';
+
+export const readPageHelp = `readPage - 単一ページを読む
+
+Usage:
+  cosense readPage <pageUrl>
+
+引数:
+  <pageUrl>  読むページの完全なURL（例: https://scrapbox.io/shokai/foo）
+
+戻り値（top-levelの主なkey）:
+  title          string               ページタイトル
+  persistent     boolean              実体のあるページなら true。false でも関連ページリストは存在する場合がある
+  id             string               ページID (persistent: true の時のみ)
+  commitId       string               最新コミットID (persistent: true の時のみ)
+  lines          Array<Line>          本文の行配列。Line = { id, text, user, created, updated } (id および user/timestamp 系は persistent: true の時のみ)
+  pageRank       number               ページの重要度指標。被リンクから計算される
+  linked         number               被リンク数
+  views          number               閲覧数
+  created        string               ページ作成時刻
+  updated        string               最終更新時刻
+  accessed       string               最終アクセス時刻
+  user           User                 作成者
+  lastUpdateUser User | null          最終更新者（null の可能性あり）
+  users          Array<User>          このページを編集した事のあるユーザー一覧
+  links          string[]             本文中のリンク記法（[title]）のページタイトル
+  linksLc        string[]             links[] を正規化（小文字化＋空白を _ に置換）した形式
+  projectLinks   string[]             別プロジェクトへのリンク記法
+  icons          string[]             [name.icon] 記法で挿入されたアイコン参照のページタイトル
+  descriptions   string[]             冒頭数行の抜粋
+
+User の field（user / lastUpdateUser / users[] / lines[].user で共通）:
+  id           string   Cosense内部のID
+  name         string?  ログイン名（自己紹介ページのタイトルや、本文中のアイコン記法で使われる）
+  displayName  string?  表示名
+  email        string?  メールアドレス
+
+戻り値のJSON抜粋例:
+{
+  "title": "shokai",
+  "persistent": true,
+  "lines": [
+    {
+      "id": "57bb9aa9c2e0ec0011d2e72b",
+      "text": "shokai",
+      "user": { "id": "5724627723541f110097c291", "name": "shokai" },
+      "created": "2016-08-22T14:35+09:00 (9 years ago)",
+      "updated": "2016-08-22T14:35+09:00 (9 years ago)"
+    }
+  ],
+  "pageRank": 12,
+  "linked": 7,
+  "views": 22301,
+  "links": ["Cosense"],
+  "linksLc": ["cosense"],
+  "projectLinks": [],
+  "icons": ["shokai"],
+  "user": { "id": "5724627723541f110097c291", "name": "shokai" },
+  "lastUpdateUser": { "id": "5724627723541f110097c291", "name": "shokai" }
+}
+
+絞り込み例（jqで欲しい部分だけ抜き出す）:
+  各行のテキストだけ:
+    cosense readPage <pageUrl> | jq -r '.lines[].text'
+`;
+
+interface PageLine {
+  id?: string;
+  text?: string;
+  userId?: string;
+  user?: { id: string };
+  created?: number;
+  updated?: number;
+}
+
+interface PageData {
+  user?: { id: string } | null;
+  lastUpdateUser?: { id: string } | null;
+  users?: { id: string }[];
+  lines?: PageLine[];
+}
+
+export const readPage = async (args: string[]): Promise<void> => {
+  const [url] = args;
+  if (!url) throw new Error('Usage: cosense readPage <pageUrl>');
+  const { origin, projectName, encodedTitle } = parsePageUrl(url);
+  const apiUrl = `${origin}/api/pages/v2/${projectName}/${encodedTitle}`;
+  const credential = resolveCredential(origin, projectName);
+  const data = (await requestJson(apiUrl, { credential })) as PageData;
+
+  if ((data as { persistent?: boolean }).persistent === false) {
+    // 非存在ページに対してサーバーが返すテンプレートには、 仮の pageId / commitId / lines[0].id
+    // が含まれる。 そのまま AI に渡すと previewEdit の anchor に fake な lineId を使ってしまい
+    // 422 になる。 anchor に使えそうな field をここで全部削除し、 新規ページでは "_end" を
+    // 使うしかない状態にする
+    for (const field of [
+      'id',
+      'commitId',
+      'user',
+      'lastUpdateUser',
+      'users',
+      'linked',
+      'created',
+      'updated',
+      'accessed',
+      'lastAccessed',
+      'snapshotCreated'
+    ]) {
+      delete (data as Record<string, unknown>)[field];
+    }
+    for (const line of data.lines ?? []) {
+      for (const field of ['id', 'userId', 'user', 'created', 'updated']) {
+        delete (line as Record<string, unknown>)[field];
+      }
+    }
+  }
+
+  const userMap = await fetchUserMap(origin, projectName);
+  enrichUser(data.user, userMap);
+  enrichUser(data.lastUpdateUser, userMap);
+  for (const editor of data.users ?? []) {
+    enrichUser(editor, userMap);
+  }
+  for (const line of data.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(data as Record<string, unknown>, [
+    'created',
+    'updated',
+    'accessed',
+    'snapshotCreated',
+    'lastAccessed'
+  ]);
+
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/readProjectMembers.ts

@@ -0,0 +1,89 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parseProjectUrl } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const readProjectMembersSummary = 'プロジェクトのメンバー一覧を取得する';
+
+export const readProjectMembersHelp = `readProjectMembers - プロジェクトのメンバー一覧を取得する
+
+Usage:
+  cosense readProjectMembers <projectUrl>
+
+引数:
+  <projectUrl>  プロジェクトのURL（例: https://scrapbox.io/shokai）
+
+戻り値（top-levelの主なkey）:
+  users           Array<User>          現メンバー一覧
+  memberSnapshots Array<Snapshot>?     退去済みメンバーの記録
+
+User の field:
+  id           string    Cosense内部のID
+  name         string?   ログイン名（自己紹介ページのタイトルや、本文中のアイコン記法で使われる）
+  displayName  string?   表示名
+  photo        string?   アイコン画像URL
+  email        string?   メールアドレス
+  provider     string?   認証プロバイダ（google / microsoft / saml 等）
+  created      string?   作成時刻
+  updated      string?   更新時刻
+
+Snapshot の field:
+  id      string                            snapshotのID
+  reason  'deleted' | 'left'                退去理由
+  created string                            退去者snapshot作成時刻
+  updated string                            退去者snapshot更新時刻
+  data    { id, name?, displayName?, email? } 退去時のユーザー情報
+
+戻り値のJSON抜粋例:
+{
+  "users": [
+    {
+      "id": "5724627723541f110097c291",
+      "name": "shokai",
+      "displayName": "Sho Hashimoto",
+      "email": "shokai@example.com",
+      "provider": "google",
+      "created": "2016-08-22T14:35+09:00 (9 years ago)",
+      "updated": "2026-04-25T18:31+09:00 (5 days ago)"
+    }
+  ],
+  "memberSnapshots": [
+    {
+      "id": "65a1...",
+      "reason": "left",
+      "created": "2023-11-14T15:33+09:00 (2 years ago)",
+      "updated": "2023-11-14T15:33+09:00 (2 years ago)",
+      "data": {
+        "id": "59b8...",
+        "name": "former-member",
+        "displayName": "Former Member",
+        "email": "former@example.com"
+      }
+    }
+  ]
+}
+`;
+
+export const readProjectMembers = async (args: string[]): Promise<void> => {
+  const [url] = args;
+  if (!url) throw new Error('Usage: cosense readProjectMembers <projectUrl>');
+  if (args.length > 1) {
+    throw new Error(
+      `Unexpected positional argument: ${args[1]}\nUsage: cosense readProjectMembers <projectUrl>`
+    );
+  }
+  const { origin, projectName } = parseProjectUrl(url);
+  const apiUrl = `${origin}/api/projects/${projectName}/users`;
+  const credential = resolveCredential(origin, projectName);
+  const data = (await requestJson(apiUrl, { credential })) as {
+    users?: Record<string, unknown>[];
+    memberSnapshots?: Record<string, unknown>[];
+  };
+  for (const user of data.users ?? []) {
+    enrichTimestampsOf(user, ['created', 'updated']);
+  }
+  for (const snap of data.memberSnapshots ?? []) {
+    enrichTimestampsOf(snap, ['created', 'updated']);
+  }
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/search1hopLinks.ts

@@ -0,0 +1,43 @@
+import { fetchRelatedPagesWithRelations } from '../lib/annotateRelations.ts';
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parsePageUrl } from '../lib/parseUrl.ts';
+import { enrichPageUsers, fetchUserMap } from '../lib/resolveUsers.ts';
+
+export const search1hopLinksSummary = '1-hop近傍を全文検索でフィルタする';
+
+export const search1hopLinksHelp = `search1hopLinks - 1-hop近傍を全文検索でフィルタする
+
+Usage:
+  cosense search1hopLinks <pageUrl> <query>
+
+引数:
+  <pageUrl>  対象ページの完全なURL
+  <query>    全文検索クエリ（必須・空文字は弾かれる）
+
+戻り値（top-levelの主なkey）:
+  links1hop  Array<Link>  query を本文に含む1-hop近傍ページ
+  ほか list1hopLinks と同じ top-level key
+
+各 Link の field（list1hopLinksに加えて）:
+  search  検索ハイライト情報
+
+検索の制約:
+  - OR検索不可。複数キーワードを試したい時はクエリを分解して複数回叩く
+`;
+
+export const search1hopLinks = async (args: string[]): Promise<void> => {
+  const [url, query] = args;
+  if (args.length !== 2 || !url || !query || query.trim() === '') {
+    throw new Error('Usage: cosense search1hopLinks <pageUrl> <query>');
+  }
+  const { origin, projectName } = parsePageUrl(url);
+  const [data, userMap] = await Promise.all([
+    fetchRelatedPagesWithRelations(url, query),
+    fetchUserMap(origin, projectName)
+  ]);
+  for (const page of (data as { links1hop?: unknown[] }).links1hop ?? []) {
+    enrichPageUsers(page as Record<string, unknown>, userMap);
+    enrichTimestampsOf(page as Record<string, unknown>);
+  }
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/search2hopLinks.ts

@@ -0,0 +1,43 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parsePageUrl } from '../lib/parseUrl.ts';
+import { fetchRelatedPages } from '../lib/relatedPages.ts';
+import { enrichPageUsers, fetchUserMap } from '../lib/resolveUsers.ts';
+
+export const search2hopLinksSummary = '2-hop近傍を全文検索でフィルタする';
+
+export const search2hopLinksHelp = `search2hopLinks - 2-hop近傍を全文検索でフィルタする
+
+Usage:
+  cosense search2hopLinks <pageUrl> <query>
+
+引数:
+  <pageUrl>  対象ページの完全なURL
+  <query>    全文検索クエリ（必須・空文字は弾かれる）
+
+戻り値（top-levelの主なkey）:
+  links2hop  Array<Link>  query を本文に含む2-hop近傍ページ
+  ほか list2hopLinks と同じ top-level key
+
+各 Link の field（list2hopLinksに加えて）:
+  search  検索ハイライト情報
+
+検索の制約:
+  - OR検索不可。複数キーワードを試したい時はクエリを分解して複数回叩く
+`;
+
+export const search2hopLinks = async (args: string[]): Promise<void> => {
+  const [url, query] = args;
+  if (args.length !== 2 || !url || !query || query.trim() === '') {
+    throw new Error('Usage: cosense search2hopLinks <pageUrl> <query>');
+  }
+  const { origin, projectName } = parsePageUrl(url);
+  const [data, userMap] = await Promise.all([
+    fetchRelatedPages(url, 2, query),
+    fetchUserMap(origin, projectName)
+  ]);
+  for (const page of (data as { links2hop?: unknown[] }).links2hop ?? []) {
+    enrichPageUsers(page as Record<string, unknown>, userMap);
+    enrichTimestampsOf(page as Record<string, unknown>);
+  }
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};