@helpfeel/cosense-cli 1.3.0

package/README.md

@@ -0,0 +1,30 @@
+# @helpfeel/cosense-cli
+
+Cosenseのページを読み・調べ・編集する為のCLIとAgent Skill
+
+## Install
+
+### CLI
+
+```bash
+npm install -g https://github.com/helpfeel/cosense-cli
+cosense --help
+```
+
+### Claude Code Agent Skill
+
+```
+/plugin marketplace add helpfeel/cosense-cli
+```
+
+```
+/plugin install cosense-cli@cosense-cli
+```
+
+Skillの実行にはCLIが必要
+
+## 開発
+
+- install [direnv](https://direnv.net/)
+- run `npm install`
+- run `claude` or `codex`

package/bin/cosense

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { tsImport } from "tsx/esm/api";
+await tsImport("../src/cli.ts", import.meta.url);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@helpfeel/cosense-cli",
+  "version": "1.3.0",
+  "description": "Cosense (旧Scrapbox) のページを読み・調べ・編集するCLI",
+  "homepage": "https://github.com/helpfeel/cosense-cli",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/helpfeel/cosense-cli.git"
+  },
+  "bin": {
+    "cosense": "./bin/cosense"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "type": "module",
+  "scripts": {
+    "lint": "run-s lint:**",
+    "lint:oxfmt": "oxfmt --check",
+    "lint:tsc": "tsc -p tsconfig.json",
+    "lint:oxlint": "oxlint --report-unused-disable-directives-severity error",
+    "format": "oxfmt"
+  },
+  "dependencies": {
+    "tsx": "4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.2",
+    "npm-run-all": "4.1.5",
+    "oxfmt": "0.46.0",
+    "oxlint": "1.61.0",
+    "typescript": "6.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.com/"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  browsePage,
+  browsePageHelp,
+  browsePageSummary
+} from './commands/browsePage.ts';
+import {
+  browseRelatedPages,
+  browseRelatedPagesHelp,
+  browseRelatedPagesSummary
+} from './commands/browseRelatedPages.ts';
+import {
+  list1hopLinks,
+  list1hopLinksHelp,
+  list1hopLinksSummary
+} from './commands/list1hopLinks.ts';
+import {
+  list2hopLinks,
+  list2hopLinksHelp,
+  list2hopLinksSummary
+} from './commands/list2hopLinks.ts';
+import {
+  listPages,
+  listPagesHelp,
+  listPagesSummary
+} from './commands/listPages.ts';
+import {
+  listProjects,
+  listProjectsHelp,
+  listProjectsSummary
+} from './commands/listProjects.ts';
+import { login, loginHelp, loginSummary } from './commands/login.ts';
+import {
+  previewEdit,
+  previewEditHelp,
+  previewEditSummary
+} from './commands/previewEdit.ts';
+import {
+  readPage,
+  readPageHelp,
+  readPageSummary
+} from './commands/readPage.ts';
+import {
+  readProjectMembers,
+  readProjectMembersHelp,
+  readProjectMembersSummary
+} from './commands/readProjectMembers.ts';
+import {
+  submitEdit,
+  submitEditHelp,
+  submitEditSummary
+} from './commands/submitEdit.ts';
+import {
+  search1hopLinks,
+  search1hopLinksHelp,
+  search1hopLinksSummary
+} from './commands/search1hopLinks.ts';
+import {
+  search2hopLinks,
+  search2hopLinksHelp,
+  search2hopLinksSummary
+} from './commands/search2hopLinks.ts';
+import {
+  searchFullText,
+  searchFullTextHelp,
+  searchFullTextSummary
+} from './commands/searchFullText.ts';
+import {
+  searchVector,
+  searchVectorHelp,
+  searchVectorSummary
+} from './commands/searchVector.ts';
+import { whoami, whoamiHelp, whoamiSummary } from './commands/whoami.ts';
+
+interface CommandSpec {
+  handler: (args: string[]) => Promise<void>;
+  summary: string;
+  help: string;
+}
+
+const packageJsonPath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'package.json'
+);
+const { version } = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+  version: string;
+};
+
+const commands: Record<string, CommandSpec> = {
+  login: { handler: login, summary: loginSummary, help: loginHelp },
+  whoami: { handler: whoami, summary: whoamiSummary, help: whoamiHelp },
+  listProjects: {
+    handler: listProjects,
+    summary: listProjectsSummary,
+    help: listProjectsHelp
+  },
+  browsePage: {
+    handler: browsePage,
+    summary: browsePageSummary,
+    help: browsePageHelp
+  },
+  browseRelatedPages: {
+    handler: browseRelatedPages,
+    summary: browseRelatedPagesSummary,
+    help: browseRelatedPagesHelp
+  },
+  readPage: { handler: readPage, summary: readPageSummary, help: readPageHelp },
+  readProjectMembers: {
+    handler: readProjectMembers,
+    summary: readProjectMembersSummary,
+    help: readProjectMembersHelp
+  },
+  listPages: {
+    handler: listPages,
+    summary: listPagesSummary,
+    help: listPagesHelp
+  },
+  list1hopLinks: {
+    handler: list1hopLinks,
+    summary: list1hopLinksSummary,
+    help: list1hopLinksHelp
+  },
+  list2hopLinks: {
+    handler: list2hopLinks,
+    summary: list2hopLinksSummary,
+    help: list2hopLinksHelp
+  },
+  searchVector: {
+    handler: searchVector,
+    summary: searchVectorSummary,
+    help: searchVectorHelp
+  },
+  searchFullText: {
+    handler: searchFullText,
+    summary: searchFullTextSummary,
+    help: searchFullTextHelp
+  },
+  search1hopLinks: {
+    handler: search1hopLinks,
+    summary: search1hopLinksSummary,
+    help: search1hopLinksHelp
+  },
+  search2hopLinks: {
+    handler: search2hopLinks,
+    summary: search2hopLinksSummary,
+    help: search2hopLinksHelp
+  },
+  previewEdit: {
+    handler: previewEdit,
+    summary: previewEditSummary,
+    help: previewEditHelp
+  },
+  submitEdit: {
+    handler: submitEdit,
+    summary: submitEditSummary,
+    help: submitEditHelp
+  }
+};
+
+const renderTopLevelHelp = (): string => {
+  const nameWidth = Math.max(...Object.keys(commands).map(n => n.length));
+  const lines = [
+    `cosense v${version} - Cosenseのページを読み・調べ・編集するCLI`,
+    '',
+    'Usage:',
+    '  cosense <command> [args...]',
+    '  cosense <command> --help    個別コマンドの詳細を表示',
+    '  cosense --help              このヘルプを表示',
+    '  cosense --version           バージョンを表示',
+    '',
+    'Commands:'
+  ];
+  for (const [name, { summary }] of Object.entries(commands)) {
+    lines.push(`  ${name.padEnd(nameWidth)}  ${summary}`);
+  }
+  return lines.join('\n');
+};
+
+const [, , command, ...rest] = process.argv;
+
+if (command === '--help') {
+  process.stdout.write(`${renderTopLevelHelp()}\n`);
+  process.exit(0);
+}
+
+if (command === '--version') {
+  process.stdout.write(`cosense v${version}\n`);
+  process.exit(0);
+}
+
+const spec = command ? commands[command] : undefined;
+if (!spec) {
+  process.stderr.write(
+    `invalid command${command ? `: ${command}` : ''}\n` +
+      'See `cosense --help` for usage.\n'
+  );
+  process.exit(2);
+}
+
+if (rest.includes('--help')) {
+  process.stdout.write(`${spec.help}\n`);
+  process.exit(0);
+}
+
+try {
+  await spec.handler(rest);
+} catch (err) {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+}

package/src/commands/browsePage.ts

@@ -0,0 +1,324 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parsePageUrl } from '../lib/parseUrl.ts';
+import { fetchRelatedPages } from '../lib/relatedPages.ts';
+import {
+  buildGroups,
+  dedupAndSortByPageRank,
+  type Page as RelatedPage,
+  renderGroups
+} from '../lib/relatedPagesFormat.ts';
+import { requestJson } from '../lib/request.ts';
+import {
+  enrichPageUsers,
+  fetchUserMap,
+  type UserMap
+} from '../lib/resolveUsers.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const browsePageSummary =
+  '単一ページを読む。メタデータ+アイコン記法+テロメア+本文をAIが読みやすい形式で出力する';
+
+export const browsePageHelp = `browsePage - 単一ページを読む。メタデータ+アイコン記法+テロメア+本文をAIが読みやすい形式で出力する
+
+Usage:
+  cosense browsePage <pageUrl>
+
+引数:
+  <pageUrl>  読むページの完全なURL（例: https://scrapbox.io/shokai/foo）
+             URLに #<lineId> fragmentが付いていれば、本文のその行末に行permalinkマーカーを付与する
+
+出力形式（Markdown plain text。JSONではない）:
+  # <title>
+
+  ## メタデータ
+    タイトル / 作成日時 / 最終更新日時 / 最終アクセス日時 / 被リンク数 / pageRank /
+    views / snapshot / 行数 / 文字数 / 作成者 / 最終更新者 / 関わったユーザー
+
+  ## 人間のアイコン記法
+    本文中の [name.icon] のうち、現メンバーまたは退去済みメンバー (memberSnapshots) の
+    name に合致するものだけを [name.icon] の形で箇条書きする。
+    一致が0件ならセクションごと省略
+
+  ## テロメアのサマリー
+    lines[] を最終更新者でグルーピングし、 displayName  更新期間 YYYY/M/D 〜 YYYY/M/D  N行更新
+    の形式で行数降順に全員出力
+
+  ## 本文
+    各行の text を改行で結合。fragment 指定行のみ末尾に  #<lineId>  を付与
+
+  -------------------- Related Pages --------------------
+    本文と関連ページ一覧の境界を示す非Markdown区切り線。Cosenseの#hashtag記法と
+    衝突しないようにMarkdown見出しを避ける。
+  ## 1 hop link
+    このページの 1-hop 近傍ページタイトル一覧。 1-hop が 0 件なら区切り線ごと省略
+
+非存在ページ (persistent: false):
+  メタデータ・アイコン・テロメアは省略。 (このページはまだ作成されていません) と
+  本文（テンプレート）と Related Pages を出力する
+
+URLに #<lineId> fragmentが指定された時:
+  タイトル直後に判定結果を1行出力する。
+    - 24文字の小文字16進数フォーマットで本文に該当行があれば、行permalinkマーカーを本文中に付ける
+    - フォーマット正、本文に該当行なし
+    - フォーマット不正 (24文字の小文字16進数でない)
+`;
+
+interface PageLine {
+  id?: string;
+  text?: string;
+  userId?: string;
+  user?: { id?: string };
+  updated?: number | string;
+  created?: number | string;
+}
+
+interface UserRef {
+  id?: string;
+  name?: string;
+  displayName?: string;
+}
+
+interface PageData {
+  title?: string;
+  persistent?: boolean;
+  pageRank?: number;
+  linked?: number;
+  views?: number;
+  linesCount?: number;
+  charsCount?: number;
+  snapshotCount?: number;
+  snapshotCreated?: number | string;
+  created?: number | string;
+  updated?: number | string;
+  accessed?: number | string;
+  lastAccessed?: number | string;
+  user?: UserRef | null;
+  lastUpdateUser?: UserRef | null;
+  users?: UserRef[];
+  lines?: PageLine[];
+  icons?: string[];
+}
+
+const LINE_ID_PATTERN = /^[0-9a-f]{24}$/;
+
+const extractFragment = (input: string): string | null => {
+  const u = new URL(input);
+  if (!u.hash) return null;
+  const value = u.hash.slice(1);
+  return value === '' ? null : value;
+};
+
+const formatUserDisplay = (u: UserRef | null | undefined): string | null => {
+  if (!u) return null;
+  if (u.displayName && u.name) return `${u.displayName} (${u.name})`;
+  return u.displayName ?? u.name ?? u.id ?? null;
+};
+
+const formatDateYMD = (unixSec: number): string => {
+  const d = new Date(unixSec * 1000);
+  return `${d.getFullYear()}/${d.getMonth() + 1}/${d.getDate()}`;
+};
+
+const normalizeIndent = (text: string): string =>
+  text.replace(/^\s+/, m => '\t'.repeat(m.length));
+
+interface TelomereEntry {
+  userId: string;
+  lineCount: number;
+  minUpdated: number;
+  maxUpdated: number;
+}
+
+const buildTelomere = (lines: PageLine[]): TelomereEntry[] => {
+  const byUser = new Map<string, TelomereEntry>();
+  for (const line of lines) {
+    const uid = line.userId;
+    const updated = line.updated;
+    if (!uid || typeof updated !== 'number') continue;
+    const entry = byUser.get(uid);
+    if (entry) {
+      entry.lineCount += 1;
+      if (updated < entry.minUpdated) entry.minUpdated = updated;
+      if (updated > entry.maxUpdated) entry.maxUpdated = updated;
+    } else {
+      byUser.set(uid, {
+        userId: uid,
+        lineCount: 1,
+        minUpdated: updated,
+        maxUpdated: updated
+      });
+    }
+  }
+  return [...byUser.values()].sort((a, b) => b.lineCount - a.lineCount);
+};
+
+const renderMetadata = (page: PageData): string => {
+  const items: string[] = [];
+  if (typeof page.title === 'string') items.push(`- タイトル: ${page.title}`);
+  if (page.created) items.push(`- 作成日時: ${page.created}`);
+  if (page.updated) items.push(`- 最終更新日時: ${page.updated}`);
+  if (page.accessed) items.push(`- 最終アクセス日時: ${page.accessed}`);
+  if (typeof page.linked === 'number')
+    items.push(`- 被リンク数: ${page.linked}`);
+  if (typeof page.pageRank === 'number') {
+    items.push(`- pageRank: ${page.pageRank}`);
+  }
+  if (typeof page.views === 'number') items.push(`- views: ${page.views}`);
+  if (typeof page.snapshotCount === 'number' && page.snapshotCount > 0) {
+    const latest = page.snapshotCreated ? `、最新 ${page.snapshotCreated}` : '';
+    items.push(`- snapshot: ${page.snapshotCount} 件${latest}`);
+  }
+  if (typeof page.linesCount === 'number') {
+    items.push(`- 行数: ${page.linesCount}`);
+  }
+  if (typeof page.charsCount === 'number') {
+    items.push(`- 文字数: ${page.charsCount}`);
+  }
+  const author = formatUserDisplay(page.user);
+  if (author) items.push(`- 作成者: ${author}`);
+  const lastUpdater = formatUserDisplay(page.lastUpdateUser);
+  if (lastUpdater) items.push(`- 最終更新者: ${lastUpdater}`);
+  if (page.users && page.users.length > 0) {
+    items.push('- 関わったユーザー:');
+    for (const u of page.users) {
+      const f = formatUserDisplay(u);
+      if (f) items.push(`  - ${f}`);
+    }
+  }
+  return `## メタデータ\n\n${items.join('\n')}`;
+};
+
+const renderHumanIcons = (
+  icons: string[] | undefined,
+  userMap: UserMap
+): string | null => {
+  if (!icons || icons.length === 0) return null;
+  const memberNames = new Set<string>();
+  for (const info of userMap.values()) {
+    if (info.name) memberNames.add(info.name);
+  }
+  const human = icons.filter(name => memberNames.has(name));
+  if (human.length === 0) return null;
+  return `## 人間のアイコン記法\n\n${human.map(name => `- [${name}.icon]`).join('\n')}`;
+};
+
+const renderTelomere = (
+  entries: TelomereEntry[],
+  userMap: UserMap
+): string | null => {
+  if (entries.length === 0) return null;
+  const lines = entries.map(e => {
+    const info = userMap.get(e.userId);
+    const name = info?.displayName ?? info?.name ?? e.userId;
+    return `- ${name}\t更新期間 ${formatDateYMD(e.minUpdated)} 〜 ${formatDateYMD(e.maxUpdated)}\t${e.lineCount}行更新`;
+  });
+  return `## テロメアのサマリー\n\n${lines.join('\n')}`;
+};
+
+interface BodyRender {
+  body: string;
+  matchedFragment: boolean;
+}
+
+const renderBody = (lines: PageLine[], fragment: string | null): BodyRender => {
+  let matchedFragment = false;
+  const out: string[] = [];
+  for (const line of lines) {
+    const text = normalizeIndent(line.text ?? '');
+    if (fragment && line.id === fragment) {
+      matchedFragment = true;
+      out.push(`${text}\t#${line.id}`);
+    } else {
+      out.push(text);
+    }
+  }
+  return { body: out.join('\n'), matchedFragment };
+};
+
+const renderRelatedPages = (hopValue: unknown): string | null => {
+  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))}`;
+};
+
+export const browsePage = async (args: string[]): Promise<void> => {
+  if (args.length !== 1) {
+    throw new Error('Usage: cosense browsePage <pageUrl>');
+  }
+  const [input] = args as [string];
+  const fragment = extractFragment(input);
+  const { origin, projectName, encodedTitle } = parsePageUrl(input);
+  const apiUrl = `${origin}/api/pages/v2/${projectName}/${encodedTitle}`;
+  const credential = resolveCredential(origin, projectName);
+
+  // 必要なAPIのいずれかが失敗したら exit 1 で落とす。 graceful degradation
+  // させると「アイコンが0件」「1-hopが0件」と区別がつかなくなり、AIに誤った
+  // 文脈を渡してしまう
+  const [page, userMap, hopValue] = await Promise.all([
+    requestJson(apiUrl, { credential }) as Promise<PageData>,
+    fetchUserMap(origin, projectName),
+    fetchRelatedPages(input, 1)
+  ]);
+
+  const title = page.title ?? '';
+  const persistent = page.persistent !== false;
+  const sections: string[] = [`# ${title}`];
+
+  if (!persistent) {
+    sections.push('(このページはまだ作成されていません)');
+    const { body } = renderBody(page.lines ?? [], null);
+    sections.push(`## 本文（テンプレート）\n\n${body}`);
+    const related = renderRelatedPages(hopValue);
+    if (related) sections.push(related);
+    process.stdout.write(`${sections.join('\n\n')}\n`);
+    return;
+  }
+
+  // 本文を先にrenderしてfragment一致状況を取得し、タイトル直後の説明文に反映する
+  const validFragment = fragment !== null && LINE_ID_PATTERN.test(fragment);
+  const { body, matchedFragment } = renderBody(
+    page.lines ?? [],
+    validFragment ? fragment : null
+  );
+  if (fragment !== null) {
+    if (!validFragment) {
+      sections.push(`#${fragment} は行IDとしてフォーマットが正しくない`);
+    } else if (matchedFragment) {
+      sections.push(
+        `指定された行ID #${fragment} に合致する行が存在する。本文のセクション内で示す`
+      );
+    } else {
+      sections.push(
+        `指定された行ID #${fragment} に合致する行は本文に存在しなかった`
+      );
+    }
+  }
+
+  // telomere は line.updated が unix秒のうちに集計する
+  const telomere = buildTelomere(page.lines ?? []);
+
+  enrichTimestampsOf(page as Record<string, unknown>, [
+    'created',
+    'updated',
+    'accessed',
+    'lastAccessed',
+    'snapshotCreated'
+  ]);
+  enrichPageUsers(page, userMap);
+
+  sections.push(renderMetadata(page));
+
+  const iconsSection = renderHumanIcons(page.icons, userMap);
+  if (iconsSection) sections.push(iconsSection);
+
+  const telomereSection = renderTelomere(telomere, userMap);
+  if (telomereSection) sections.push(telomereSection);
+
+  sections.push(`## 本文\n\n${body}`);
+
+  const related = renderRelatedPages(hopValue);
+  if (related) sections.push(related);
+
+  process.stdout.write(`${sections.join('\n\n')}\n`);
+};

package/src/commands/browseRelatedPages.ts

@@ -0,0 +1,79 @@
+import {
+  buildGroups,
+  dedupAndSortByPageRank,
+  type Page,
+  renderGroups
+} from '../lib/relatedPagesFormat.ts';
+import { fetchRelatedPages } from '../lib/relatedPages.ts';
+
+export const browseRelatedPagesSummary =
+  '1-hop+2-hopのタイトル一覧を眺める。単独のページだけを見ていては掴みきれない文脈が浮かび上がる';
+
+export const browseRelatedPagesHelp = `browseRelatedPages - 1-hop+2-hopのタイトル一覧を眺める。単独のページだけを見ていては掴みきれない文脈が浮かび上がる
+
+Usage:
+  cosense browseRelatedPages <pageUrl>
+
+引数:
+  <pageUrl>  対象ページの完全なURL
+
+出力:
+  1-hop と 2-hop の関連ページそれぞれを pageRank 降順で並べたタイトルの一覧。
+  他のコマンドと異なり、JSON ではなく Markdown 形式で出力する。
+
+  # Related Pages
+
+  ## 1 hop link
+
+  - タイトル
+  - 日記 2025-01-01
+    他、48件の日記を省略します
+
+  ## 2 hop link
+
+  - タイトル
+`;
+
+export const browseRelatedPages = async (args: string[]): Promise<void> => {
+  if (args.length !== 1) {
+    throw new Error('Usage: cosense browseRelatedPages <pageUrl>');
+  }
+  const [url] = args as [string];
+
+  const [result1hop, result2hop] = await Promise.allSettled([
+    fetchRelatedPages(url, 1),
+    fetchRelatedPages(url, 2)
+  ]);
+
+  if (result1hop.status === 'rejected' && result2hop.status === 'rejected') {
+    throw result1hop.reason;
+  }
+
+  // seen は 1-hop と 2-hop で共有して、 1-hop に出たページが 2-hop にも再掲されないようにする
+  const seen = new Set<string>();
+  const pages1hop =
+    result1hop.status === 'fulfilled'
+      ? dedupAndSortByPageRank(
+          (result1hop.value as { links1hop?: Page[] }).links1hop,
+          seen
+        )
+      : [];
+  const pages2hop =
+    result2hop.status === 'fulfilled'
+      ? dedupAndSortByPageRank(
+          (result2hop.value as { links2hop?: Page[] }).links2hop,
+          seen
+        )
+      : [];
+
+  const sections: string[] = [];
+  if (pages1hop.length > 0) {
+    sections.push(`## 1 hop link\n\n${renderGroups(buildGroups(pages1hop))}`);
+  }
+  if (pages2hop.length > 0) {
+    sections.push(`## 2 hop link\n\n${renderGroups(buildGroups(pages2hop))}`);
+  }
+  if (sections.length > 0) {
+    process.stdout.write(`# Related Pages\n\n${sections.join('\n\n')}\n`);
+  }
+};