@helpfeel/cosense-cli 1.3.0

package/src/commands/searchFullText.ts

@@ -0,0 +1,85 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parseProjectUrl } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { enrichPageUsers, fetchUserMap } from '../lib/resolveUsers.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const searchFullTextSummary = '本文全文を対象に検索する';
+
+export const searchFullTextHelp = `searchFullText - 本文全文を対象に検索する
+
+Usage:
+  cosense searchFullText <projectUrl> <query>
+
+引数:
+  <projectUrl>  プロジェクトのURL（例: https://scrapbox.io/shokai/）
+  <query>       検索クエリ
+
+戻り値（top-levelの主なkey）:
+  projectName            string         プロジェクト名
+  searchQuery            string         実行されたクエリ
+  count                  number         ヒット総数
+  limit                  number         1リクエストで返る上限
+  pages                  Array<Page>    マッチしたページの配列
+  existsExactTitleMatch  boolean        タイトル完全一致がある場合 true
+
+各 Page の field:
+  id              string         ページID
+  title           string         ページタイトル
+  user            User           作成者
+  lastUpdateUser  User | null    最終更新者
+  users           Array<User>    更新者リスト
+  views           number         閲覧数
+  linked          number         被リンク数
+  created         string         作成日時
+  updated         string         更新日時
+  pageRank        number         PageRank
+  linesCount      number         行数
+  charsCount      number         文字数
+  words           string[]       マッチした語の一覧
+  lines           string[]       マッチした本文の行
+
+User の field（user / lastUpdateUser / users[] で共通）:
+  id           string   Cosense内部のID
+  name         string?  ログイン名（自己紹介ページのタイトルや、本文中のアイコン記法で使われる）
+  displayName  string?  表示名
+  email        string?  メールアドレス
+
+戻り値のJSON抜粋例:
+{
+  "projectName": "shokai",
+  "count": 12,
+  "pages": [
+    { "id": "...", "title": "...", "words": ["codex"], "lines": ["...codexと相談する..."] }
+  ]
+}
+`;
+
+interface SearchFullTextData {
+  pages?: {
+    user?: { id: string } | null;
+    lastUpdateUser?: { id: string } | null;
+    users?: { id: string }[];
+  }[];
+}
+
+export const searchFullText = async (args: string[]): Promise<void> => {
+  const [url, query] = args;
+  if (!url || !query) {
+    throw new Error('Usage: cosense searchFullText <projectUrl> <query>');
+  }
+  const { origin, projectName } = parseProjectUrl(url);
+  const apiUrl = `${origin}/api/pages/${projectName}/search/query?q=${encodeURIComponent(query)}`;
+  const credential = resolveCredential(origin, projectName);
+  const data = (await requestJson(apiUrl, {
+    credential
+  })) as SearchFullTextData;
+
+  const userMap = await fetchUserMap(origin, projectName);
+  for (const page of data.pages ?? []) {
+    enrichPageUsers(page, userMap);
+    enrichTimestampsOf(page as Record<string, unknown>);
+  }
+
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/searchVector.ts

@@ -0,0 +1,86 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parseProjectUrl } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { enrichPageUsers, fetchUserMap } from '../lib/resolveUsers.ts';
+import { resolveCredential } from '../lib/settings.ts';
+
+export const searchVectorSummary =
+  'ベクトル検索でページを探す（タイトル+本文中リンク記法のみ対象）';
+
+export const searchVectorHelp = `searchVector - ベクトル検索でページを探す
+
+Usage:
+  cosense searchVector <projectUrl> <query>
+
+引数:
+  <projectUrl>  プロジェクトのURL（例: https://scrapbox.io/shokai/）
+  <query>       検索クエリ
+
+戻り値（top-levelの主なkey）:
+  pages  Array<Page>  類似度順のヒット結果
+
+各 page の field:
+  title           string          ページタイトル
+  image           string          サムネイル画像URL
+  score           number          類似度スコア（高いほど近い）
+  exists          boolean         実体のあるページなら true。false の場合は空ページ（リンク記法だけ存在）
+
+  exists=true のページのみ追加で付くfield:
+    id              string          ページID
+    user            User            作成者
+    lastUpdateUser  User | null     最終更新者
+    users           Array<User>     更新者リスト
+    views           number          閲覧数
+    linked          number          被リンク数
+    created         string          作成日時
+    updated         string          更新日時
+    pageRank        number          PageRank
+    linesCount      number          行数
+    charsCount      number          文字数
+
+User の field（user / lastUpdateUser / users[] で共通）:
+  id           string   Cosense内部のID
+  name         string?  ログイン名（自己紹介ページのタイトルや、本文中のアイコン記法で使われる）
+  displayName  string?  表示名
+  email        string?  メールアドレス
+
+検索対象:
+  - ページタイトル + 本文中のリンク記法（[title]）のみ
+  - 本文の通常テキストは検索対象外
+  - 本文の語で検索したい時は searchFullText を使う
+
+戻り値のJSON抜粋例:
+{
+  "pages": [
+    { "id": "...", "title": "vibe coding", "score": 0.833, "exists": true },
+    { "title": "bug修正", "score": 0.811, "exists": false }
+  ]
+}
+`;
+
+interface SearchVectorData {
+  pages?: {
+    user?: { id: string } | null;
+    lastUpdateUser?: { id: string } | null;
+    users?: { id: string }[];
+  }[];
+}
+
+export const searchVector = async (args: string[]): Promise<void> => {
+  const [url, query] = args;
+  if (!url || !query) {
+    throw new Error('Usage: cosense searchVector <projectUrl> <query>');
+  }
+  const { origin, projectName } = parseProjectUrl(url);
+  const apiUrl = `${origin}/api/pages/${projectName}/search/vector/titles?q=${encodeURIComponent(query)}`;
+  const credential = resolveCredential(origin, projectName);
+  const data = (await requestJson(apiUrl, { credential })) as SearchVectorData;
+
+  const userMap = await fetchUserMap(origin, projectName);
+  for (const page of data.pages ?? []) {
+    enrichPageUsers(page, userMap);
+    enrichTimestampsOf(page as Record<string, unknown>);
+  }
+
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/submitEdit.ts

@@ -0,0 +1,73 @@
+import { encodeTitleForUrl } from '../lib/encodeTitle.ts';
+import { parseProjectUrlStrict } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveUserCredential } from '../lib/settings.ts';
+
+export const submitEditSummary =
+  'previewEditで取得したpreviewIdを使ってページ編集を確定する';
+
+export const submitEditHelp = `submitEdit - previewEditで取得したpreviewIdを使ってページ編集を確定する
+
+Usage:
+  cosense submitEdit <projectUrl> <previewId>
+
+引数:
+  <projectUrl>  プロジェクトのURL (例: https://scrapbox.io/shokai)。 末尾に余分なpathがあるとerror
+  <previewId>   previewEdit の戻り値の previewId
+
+戻り値（plain text）:
+  commitId: <生成されたcommitのID>
+  title:    <実際に書き込まれたpage title>
+  url:      <作成または更新された page の URL>
+
+  url はサーバーが返す title から再構築される。 新規作成時にサーバーが auto-suffix した場合
+  (同名ページが既に存在する場合) は、 title/url にその suffix が反映される。
+
+HTTPエラー:
+  HTTP 400  preview を生成した時と違う project の URL を渡している
+  HTTP 401  認証なし
+  HTTP 403  非memberまたはService Account（書き込みはPAT限定）
+  HTTP 404  preview が見つからない / 期限切れ (5分) / 既にconsume済み / 他userのpreview
+  HTTP 409 {"error":"NotFastForward","latest":...}
+            preview生成後にページが更新された。最新stateを再取得して ops を作り直し、
+            previewEdit からやり直す必要がある
+  HTTP 409 {"error":"DuplicateTitle"}
+            preview→submit の間に他人が同名ページを作った (race condition)
+
+ワークフロー:
+  previewIdは1回しか使えない (consume-on-submit)。submitに失敗したら previewEdit から
+  やり直す。previewIdは5分でexpireするので submit は迅速に。
+`;
+
+interface SubmitResponse {
+  commitId: string;
+  page: { title?: string } | null;
+}
+
+export const submitEdit = async (args: string[]): Promise<void> => {
+  if (args.length !== 2) {
+    throw new Error('Usage: cosense submitEdit <projectUrl> <previewId>');
+  }
+  const [projectUrl, previewId] = args as [string, string];
+
+  const { origin, projectName } = parseProjectUrlStrict(projectUrl);
+  const apiUrl = `${origin}/api/pages/v2/${projectName}/page-edit-for-ai/submit`;
+  // 書き込み系 API は PAT 限定 (Service Account 拒否) なので、PAT を直接解決する
+  const credential = resolveUserCredential(origin);
+  const response = (await requestJson(apiUrl, {
+    credential,
+    method: 'POST',
+    body: { previewId }
+  })) as SubmitResponse;
+
+  const title = response.page?.title;
+  if (typeof title !== 'string') {
+    throw new Error(
+      `submit response missing page field (commitId: ${response.commitId})`
+    );
+  }
+  const url = `${origin}/${projectName}/${encodeTitleForUrl(title)}`;
+  process.stdout.write(
+    `commitId: ${response.commitId}\ntitle:    ${title}\nurl:      ${url}\n`
+  );
+};

package/src/commands/whoami.ts

@@ -0,0 +1,48 @@
+import { enrichTimestampsOf } from '../lib/enrichTimestamps.ts';
+import { parseOrigin } from '../lib/parseUrl.ts';
+import { requestJson } from '../lib/request.ts';
+import { resolveUserCredential } from '../lib/settings.ts';
+
+export const whoamiSummary = '現在の認証ユーザーの情報を取得する';
+
+export const whoamiHelp = `whoami - 現在の認証ユーザーの情報を取得する
+
+Usage:
+  cosense whoami <origin>
+
+引数:
+  <origin>  Cosenseサーバーのorigin（例: https://scrapbox.io）
+
+戻り値（top-levelの主なkey）:
+  id                  string                 Cosense内部のID
+  name                string                 ログイン名
+  displayName         string                 表示名
+  email               string                 メールアドレス
+  photo               string                 アイコン画像URL
+  provider            string                 認証プロバイダ（google / microsoft / saml 等）
+  pageFilters         Array<{type, value}>   page list filter設定
+  created             string                 作成時刻
+  updated             string                 更新時刻
+`;
+
+export const whoami = async (args: string[]): Promise<void> => {
+  const [originArg] = args;
+  if (!originArg) throw new Error('Usage: cosense whoami <origin>');
+  if (args.length > 1) {
+    throw new Error(
+      `Unexpected positional argument: ${args[1]}\nUsage: cosense whoami <origin>`
+    );
+  }
+  const origin = parseOrigin(originArg);
+  const credential = resolveUserCredential(origin);
+  if (!credential) {
+    throw new Error(
+      `No Personal Access Token found for ${origin}. Run \`cosense login ${origin}\` to authenticate.`
+    );
+  }
+  const data = (await requestJson(`${origin}/api/users/me`, {
+    credential
+  })) as Record<string, unknown>;
+  enrichTimestampsOf(data);
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/lib/annotateRelations.ts

@@ -0,0 +1,93 @@
+import { parsePageUrl } from './parseUrl.ts';
+import { HttpError, requestJson } from './request.ts';
+import { resolveCredential } from './settings.ts';
+
+export type Relation = 'outgoing' | 'incoming' | 'bidirectional';
+
+interface Link1Hop {
+  titleLc?: string;
+  linksLc?: string[];
+  relation?: Relation;
+  [key: string]: unknown;
+}
+
+interface ReadPageData {
+  titleLc?: string;
+  title?: string;
+  linksLc?: string[];
+  links?: string[];
+  [key: string]: unknown;
+}
+
+interface RelatedPagesData {
+  links1hop?: Link1Hop[];
+  [key: string]: unknown;
+}
+
+const toTitleLc = (title: string): string =>
+  title.replace(/ /g, '_').toLowerCase();
+
+const computeRelation = (
+  startLinksLcSet: Set<string>,
+  startTitleLc: string,
+  page: Link1Hop
+): Relation => {
+  const linksTo = page.titleLc ? startLinksLcSet.has(page.titleLc) : false;
+  const linksFrom = page.linksLc?.includes(startTitleLc) ?? false;
+  if (linksTo && linksFrom) return 'bidirectional';
+  if (linksTo) return 'outgoing';
+  return 'incoming';
+};
+
+export const fetchRelatedPagesWithRelations = async (
+  url: string,
+  query?: string
+): Promise<RelatedPagesData> => {
+  const { origin, projectName, encodedTitle } = parsePageUrl(url);
+  const queryParam = query ? `?search=${encodeURIComponent(query)}` : '';
+  const startPageUrl = `${origin}/api/pages/v2/${projectName}/${encodedTitle}`;
+  const relatedUrl = `${startPageUrl}/links1hop${queryParam}`;
+  const credential = resolveCredential(origin, projectName);
+
+  const [startPageResult, relatedResult] = await Promise.allSettled([
+    requestJson(startPageUrl, { credential }),
+    requestJson(relatedUrl, { credential })
+  ]);
+
+  // links1hop endpoint must succeed (it has its own backlinks-only fallback for non-existent pages)
+  if (relatedResult.status === 'rejected') {
+    throw relatedResult.reason;
+  }
+  const related = relatedResult.value as RelatedPagesData;
+
+  // readPage returns 404 only when the page is missing and has no backlinks (a page with backlinks
+  // is auto-generated as an empty page and returned with 200). Treat that 404 as empty linksLc so
+  // all entries are classified as 'incoming'. Other failures (5xx, network, auth) must propagate
+  // so we never silently mislabel relations.
+  let startTitleLc: string;
+  let startLinksLcSet: Set<string>;
+  if (startPageResult.status === 'fulfilled') {
+    const startPage = startPageResult.value as ReadPageData;
+    startTitleLc =
+      startPage.titleLc ?? (startPage.title ? toTitleLc(startPage.title) : '');
+    startLinksLcSet = new Set<string>(
+      startPage.linksLc ?? (startPage.links ?? []).map(toTitleLc)
+    );
+  } else if (
+    startPageResult.reason instanceof HttpError &&
+    startPageResult.reason.status === 404
+  ) {
+    startTitleLc = toTitleLc(decodeURIComponent(encodedTitle));
+    startLinksLcSet = new Set<string>();
+  } else {
+    throw startPageResult.reason;
+  }
+
+  if (Array.isArray(related.links1hop)) {
+    for (const page of related.links1hop) {
+      page.relation = computeRelation(startLinksLcSet, startTitleLc, page);
+    }
+  }
+
+  return related;
+};

package/src/lib/encodeTitle.ts

@@ -0,0 +1,13 @@
+// 人が読める URL を作るための encoder (cosense 本家の「Copy readable link」 相当)。
+// Unicode 文字 (Japanese 等) は raw のまま (browser は IRI として透過処理する)。
+// cosense server の route match (`/:projectName/:title`, `:title=[^/]+`) を満たすため
+// title 内の `/` は `%2F` 必須。 URL syntax を破壊する `%` `?` `#` も percent-encode する。
+// space は cosense convention で `_` に置換。
+export const encodeTitleForUrl = (title: string): string => {
+  return title
+    .replace(/%/g, '%25')
+    .replace(/\//g, '%2F')
+    .replace(/\?/g, '%3F')
+    .replace(/#/g, '%23')
+    .replace(/ /g, '_');
+};

package/src/lib/enrichTimestamps.ts

@@ -0,0 +1,21 @@
+import { formatTimestamp } from './formatTimestamp.ts';
+
+const DEFAULT_FIELDS = [
+  'created',
+  'updated',
+  'accessed',
+  'lastAccessed'
+] as const;
+
+export const enrichTimestampsOf = (
+  obj: Record<string, unknown> | null | undefined,
+  fields: readonly string[] = DEFAULT_FIELDS
+): void => {
+  if (!obj) return;
+  for (const field of fields) {
+    const formatted = formatTimestamp(obj[field]);
+    if (formatted !== undefined) {
+      obj[field] = formatted;
+    }
+  }
+};

package/src/lib/formatTimestamp.ts

@@ -0,0 +1,55 @@
+const NOW_MS = Date.now();
+const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+const cache = new Map<number, string>();
+
+const pad = (n: number): string => String(n).padStart(2, '0');
+
+const formatAbsolute = (date: Date): string => {
+  const year = date.getFullYear();
+  const month = pad(date.getMonth() + 1);
+  const day = pad(date.getDate());
+  const hour = pad(date.getHours());
+  const minute = pad(date.getMinutes());
+  const offsetMin = -date.getTimezoneOffset();
+  const sign = offsetMin >= 0 ? '+' : '-';
+  const abs = Math.abs(offsetMin);
+  const oh = pad(Math.floor(abs / 60));
+  const om = pad(abs % 60);
+  return `${year}-${month}-${day}T${hour}:${minute}${sign}${oh}:${om}`;
+};
+
+const formatRelative = (deltaSec: number): string => {
+  const abs = Math.abs(deltaSec);
+  if (abs < 60) return rtf.format(Math.round(deltaSec), 'second');
+  if (abs < 3600) return rtf.format(Math.round(deltaSec / 60), 'minute');
+  if (abs < 86400) return rtf.format(Math.round(deltaSec / 3600), 'hour');
+  if (abs < 86400 * 7) return rtf.format(Math.round(deltaSec / 86400), 'day');
+  if (abs < 86400 * 30)
+    return rtf.format(Math.round(deltaSec / (86400 * 7)), 'week');
+  if (abs < 86400 * 365)
+    return rtf.format(Math.round(deltaSec / (86400 * 30)), 'month');
+  return rtf.format(Math.round(deltaSec / (86400 * 365)), 'year');
+};
+
+export const formatTimestamp = (unixtimeSec: unknown): string | undefined => {
+  if (
+    typeof unixtimeSec !== 'number' ||
+    !Number.isFinite(unixtimeSec) ||
+    unixtimeSec === 0
+  ) {
+    return undefined;
+  }
+  const cached = cache.get(unixtimeSec);
+  if (cached) return cached;
+
+  const ms = unixtimeSec * 1000;
+  const date = new Date(ms);
+  if (Number.isNaN(date.getTime())) return undefined;
+
+  const absolute = formatAbsolute(date);
+  const deltaSec = Math.floor((ms - NOW_MS) / 1000);
+  const relative = formatRelative(deltaSec);
+  const result = `${absolute} (${relative})`;
+  cache.set(unixtimeSec, result);
+  return result;
+};

package/src/lib/parseUrl.ts

@@ -0,0 +1,60 @@
+export interface ProjectUrl {
+  origin: string;
+  projectName: string;
+}
+
+export interface PageUrl extends ProjectUrl {
+  encodedTitle: string;
+}
+
+export const parseOrigin = (input: string): string => {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error(`<origin> is not a valid URL: ${input}`);
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`<origin> must use http: or https: scheme: ${input}`);
+  }
+  return url.origin;
+};
+
+export const parseProjectUrl = (input: string): ProjectUrl => {
+  const u = new URL(input);
+  const parts = u.pathname.split('/').filter(Boolean);
+  if (parts.length < 1) {
+    throw new Error(
+      `Project URL must be https://<host>/<project>, got: ${input}`
+    );
+  }
+  return { origin: u.origin, projectName: parts[0] as string };
+};
+
+export const parseProjectUrlStrict = (input: string): ProjectUrl => {
+  const u = new URL(input);
+  if (u.search || u.hash) {
+    throw new Error(`Project URL must not have query/hash, got: ${input}`);
+  }
+  const m = u.pathname.match(/^\/([^/]+)\/?$/);
+  if (!m) {
+    throw new Error(
+      `Project URL must be https://<host>/<project> (no extra path), got: ${input}`
+    );
+  }
+  return { origin: u.origin, projectName: m[1] as string };
+};
+
+export const parsePageUrl = (input: string): PageUrl => {
+  const u = new URL(input);
+  const m = u.pathname.match(/^\/([^/]+)\/(.+?)\/?$/);
+  if (!m) {
+    throw new Error(
+      `Page URL must be https://<host>/<project>/<title>, got: ${input}`
+    );
+  }
+  const projectName = m[1] as string;
+  const rawTail = m[2] as string;
+  const encodedTitle = rawTail.replace(/\//g, '%2F');
+  return { origin: u.origin, projectName, encodedTitle };
+};

package/src/lib/relatedPages.ts

@@ -0,0 +1,15 @@
+import { parsePageUrl } from './parseUrl.ts';
+import { requestJson } from './request.ts';
+import { resolveCredential } from './settings.ts';
+
+export const fetchRelatedPages = async (
+  url: string,
+  hop: 1 | 2,
+  query?: string
+): Promise<unknown> => {
+  const { origin, projectName, encodedTitle } = parsePageUrl(url);
+  const queryParam = query ? `?search=${encodeURIComponent(query)}` : '';
+  const apiUrl = `${origin}/api/pages/v2/${projectName}/${encodedTitle}/links${hop}hop${queryParam}`;
+  const credential = resolveCredential(origin, projectName);
+  return requestJson(apiUrl, { credential });
+};

package/src/lib/relatedPagesFormat.ts

@@ -0,0 +1,77 @@
+export interface Page {
+  title: string;
+  titleLc?: string;
+  pageRank?: number;
+}
+
+export const STACK_PREVIEW = 1;
+
+const stackPattern =
+  /^([^\d]{3,})\s*([\d\-./()<>{}（）月火水木金土日年春夏秋冬]+|\d+ - [a-zA-Z])$/;
+
+export const detectStackName = (title: string): string | null =>
+  stackPattern.exec(title)?.[1] ?? null;
+
+export type Group =
+  | { type: 'page'; title: string }
+  | { type: 'stack'; name: string; titles: string[] };
+
+export const buildGroups = (pages: Page[]): Group[] => {
+  const groups: Group[] = [];
+  const stackIndexByName = new Map<string, number>();
+
+  for (const page of pages) {
+    const stackName = detectStackName(page.title);
+    if (stackName !== null) {
+      const existingIdx = stackIndexByName.get(stackName);
+      if (existingIdx !== undefined) {
+        (groups[existingIdx] as Extract<Group, { type: 'stack' }>).titles.push(
+          page.title
+        );
+      } else {
+        stackIndexByName.set(stackName, groups.length);
+        groups.push({ type: 'stack', name: stackName, titles: [page.title] });
+      }
+    } else {
+      groups.push({ type: 'page', title: page.title });
+    }
+  }
+
+  return groups;
+};
+
+const toTitleLc = (title: string): string =>
+  title.replace(/ /g, '_').toLowerCase();
+
+export const dedupAndSortByPageRank = (
+  pages: Page[] | undefined,
+  seen: Set<string> = new Set<string>()
+): Page[] => {
+  const collected: Page[] = [];
+  for (const page of pages ?? []) {
+    const tlc = page.titleLc ?? toTitleLc(page.title);
+    if (seen.has(tlc)) continue;
+    seen.add(tlc);
+    collected.push(page);
+  }
+  collected.sort((a, b) => (b.pageRank ?? 0) - (a.pageRank ?? 0));
+  return collected;
+};
+
+export const renderGroups = (groups: Group[]): string => {
+  const lines: string[] = [];
+  for (const group of groups) {
+    if (group.type === 'page') {
+      lines.push(`- ${group.title}`);
+    } else {
+      for (const title of group.titles.slice(0, STACK_PREVIEW)) {
+        lines.push(`- ${title}`);
+      }
+      const remaining = group.titles.length - STACK_PREVIEW;
+      if (remaining > 0) {
+        lines.push(`  他、${remaining}件の${group.name.trimEnd()}を省略します`);
+      }
+    }
+  }
+  return lines.join('\n');
+};