@helpfeel/cosense-cli 1.3.0

package/src/commands/list1hopLinks.ts

@@ -0,0 +1,66 @@
+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 list1hopLinksSummary = '1-hop近傍を取得する';
+
+export const list1hopLinksHelp = `list1hopLinks - 1-hop近傍を取得する
+
+Usage:
+  cosense list1hopLinks <pageUrl>
+
+引数:
+  <pageUrl>  対象ページの完全なURL
+
+戻り値（top-levelの主なkey）:
+  links1hop            Array<Link>  1-hop近傍のページ配列
+  charsCount           number       対象ページの文字数
+  hasBackLinksOrIcons  boolean      被リンク・アイコン参照があるか
+  kcsControlTagsLc     string[]     制御タグ
+  pagination           object       ページネーション情報
+
+各 Link の field:
+  id, title, titleLc, image, descriptions(冒頭数行),
+  linksLc(リンク記法のtitleLc配列), linked(被リンク数), pageRank,
+  infoboxDefinition, infoboxDisableLinks,
+  created, updated, accessed, lastAccessed (string), charsCount,
+  user (作成者 User), lastUpdateUser (最終更新者 User | null), users (更新者リスト Array<User>),
+  relation 'outgoing' | 'incoming' | 'bidirectional'
+    outgoing      対象ページが参照しているページ（正リンク）
+    incoming      対象ページを参照しているページ（逆リンク）
+    bidirectional 双方向リンク
+
+User の field（user / lastUpdateUser / users[] で共通）:
+  id           string   Cosense内部のID
+  name         string?  ログイン名（自己紹介ページのタイトルや、本文中のアイコン記法で使われる）
+  displayName  string?  表示名
+  email        string?  メールアドレス
+
+戻り値のJSON抜粋例:
+{
+  "links1hop": [
+    {
+      "id": "...", "title": "...", "linked": 4, "pageRank": 14,
+      "descriptions": ["..."], "linksLc": ["..."], "relation": "outgoing"
+    }
+  ]
+}
+`;
+
+export const list1hopLinks = async (args: string[]): Promise<void> => {
+  if (args.length !== 1) {
+    throw new Error('Usage: cosense list1hopLinks <pageUrl>');
+  }
+  const [url] = args as [string];
+  const { origin, projectName } = parsePageUrl(url);
+  const [data, userMap] = await Promise.all([
+    fetchRelatedPagesWithRelations(url),
+    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/list2hopLinks.ts

@@ -0,0 +1,53 @@
+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 list2hopLinksSummary = '2-hop近傍を取得する';
+
+export const list2hopLinksHelp = `list2hopLinks - 2-hop近傍を取得する
+
+Usage:
+  cosense list2hopLinks <pageUrl>
+
+引数:
+  <pageUrl>  対象ページの完全なURL
+
+戻り値（top-levelの主なkey）:
+  links2hop          Array<Link>  2-hop近傍のページ配列
+  hiddenHeadwordsLc  string[]     非表示のヘッドワード
+  pagination         object       ページネーション情報
+
+各 Link の field:
+  id, title, titleLc, image, descriptions, linksLc, linked, pageRank,
+  infoboxDefinition, infoboxDisableLinks,
+  created, updated, accessed, lastAccessed (string), charsCount,
+  user (作成者 User), lastUpdateUser (最終更新者 User | null), users (更新者リスト Array<User>)
+
+User の field（user / lastUpdateUser / users[] で共通）:
+  id           string   Cosense内部のID
+  name         string?  ログイン名（自己紹介ページのタイトルや、本文中のアイコン記法で使われる）
+  displayName  string?  表示名
+  email        string?  メールアドレス
+
+注意:
+  - 直接の1-hop近傍は含まれない
+  - list1hopLinks と異なり、relation field は付与されない
+`;
+
+export const list2hopLinks = async (args: string[]): Promise<void> => {
+  if (args.length !== 1) {
+    throw new Error('Usage: cosense list2hopLinks <pageUrl>');
+  }
+  const [url] = args as [string];
+  const { origin, projectName } = parsePageUrl(url);
+  const [data, userMap] = await Promise.all([
+    fetchRelatedPages(url, 2),
+    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`);
+};

package/src/commands/listPages.ts

@@ -0,0 +1,164 @@
+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 listPagesSummary = 'プロジェクトのページ一覧を取得する';
+
+export const listPagesHelp = `listPages - プロジェクトのページ一覧を取得する
+
+Usage:
+  cosense listPages <projectUrl> [options]
+
+引数:
+  <projectUrl>  プロジェクトのURL（例: https://scrapbox.io/shokai/）
+
+オプション:
+  --sort <name>   ソート順（既定: updated）
+                    updated   更新日時降順
+                    created   作成日時降順
+                    accessed  最終アクセス降順
+                    linked    被リンク数降順
+                    views     閲覧数降順
+                    title     タイトル昇順
+                  pinned page は常に先頭に来る
+  --limit <N>     1リクエストで返るページ数（既定 100、最大 1000）
+  --skip <N>      先頭から N 件スキップして取得（既定 0）
+  --filter <name> リストされるページを絞り込む。
+                  本文中に [name.icon] を持つページと
+                  指定したnameを持つユーザーがこれまでに編集したページが返る
+                  ユーザー名で絞り込む場合は user.displayName ではなく users.name を指定する
+                  自分の名前は whoami コマンドで確認できる
+
+戻り値（top-levelの主なkey）:
+  projectName  string        プロジェクト名
+  count        number        条件に一致する総ページ数
+  limit        number        1リクエストで返るページ数の上限（既定 100）
+  skip         number        スキップ件数（オフセット）
+  pages        Array<Page>   ページのメタデータ配列
+
+各 Page の主なfield:
+  id, title, image, descriptions,
+  user (作成者 User), lastUpdateUser (最終更新者 User | null), users (更新者リスト Array<User>),
+  pin (pinned page なら正の値), views, linked,
+  linesCount, charsCount,
+  created, updated, accessed, lastAccessed (string)
+
+User の field（user / lastUpdateUser / users[] で共通）:
+  id           string   Cosense内部のID
+  name         string?  ログイン名（自己紹介ページのタイトルや、本文中のアイコン記法で使われる）
+  displayName  string?  表示名
+  email        string?  メールアドレス
+
+注意:
+  - ページ本文（lines）は含まれない。本文が必要なら readPage を使う
+  - 1000件を超える件数を1リクエストで取ることはできない。--skip でページネーションする
+`;
+
+const ALLOWED_SORTS = new Set([
+  'updated',
+  'created',
+  'accessed',
+  'linked',
+  'views',
+  'title'
+]);
+
+const NON_NEGATIVE_INT = /^(?:0|[1-9]\d*)$/;
+
+interface ParsedArgs {
+  url: string;
+  sort?: string;
+  limit?: string;
+  skip?: string;
+  filter?: string;
+}
+
+const parseArgs = (args: string[]): ParsedArgs => {
+  const usage =
+    'Usage: cosense listPages <projectUrl> [--sort <name>] [--limit <N>] [--skip <N>] [--filter <name>]';
+  let url: string | undefined;
+  const parsed: Partial<ParsedArgs> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    const next = (): string => {
+      const value = args[i + 1];
+      if (value === undefined) throw new Error(`${arg} requires a value`);
+      i += 1;
+      return value;
+    };
+    if (arg === '--sort') {
+      const value = next();
+      if (!ALLOWED_SORTS.has(value)) {
+        throw new Error(
+          `Unknown --sort value: ${value}. Allowed: ${[...ALLOWED_SORTS].join(', ')}`
+        );
+      }
+      parsed.sort = value;
+    } else if (arg === '--limit') {
+      const value = next();
+      if (!NON_NEGATIVE_INT.test(value)) {
+        throw new Error(
+          `--limit must be a non-negative integer, got: ${value}`
+        );
+      }
+      parsed.limit = value;
+    } else if (arg === '--skip') {
+      const value = next();
+      if (!NON_NEGATIVE_INT.test(value)) {
+        throw new Error(`--skip must be a non-negative integer, got: ${value}`);
+      }
+      parsed.skip = value;
+    } else if (arg === '--filter') {
+      const value = next();
+      if (value.trim() === '') {
+        throw new Error('--filter must not be empty');
+      }
+      parsed.filter = value;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}\n${usage}`);
+    } else if (!url) {
+      url = arg;
+    } else {
+      throw new Error(`Unexpected positional argument: ${arg}\n${usage}`);
+    }
+  }
+  if (!url) throw new Error(usage);
+  return { url, ...parsed };
+};
+
+interface PageEntry {
+  user?: { id: string } | null;
+  lastUpdateUser?: { id: string } | null;
+  users?: { id: string }[];
+}
+
+interface ListPagesData {
+  pages?: PageEntry[];
+}
+
+export const listPages = async (args: string[]): Promise<void> => {
+  const { url, sort, limit, skip, filter } = parseArgs(args);
+  const { origin, projectName } = parseProjectUrl(url);
+  const params = new URLSearchParams();
+  if (sort) params.set('sort', sort);
+  if (limit) params.set('limit', limit);
+  if (skip) params.set('skip', skip);
+  if (filter !== undefined) {
+    params.set('filterType', 'icon');
+    params.set('filterValue', filter);
+  }
+  const queryString = params.toString();
+  const apiUrl = `${origin}/api/pages/${projectName}/${queryString ? `?${queryString}` : ''}`;
+  const credential = resolveCredential(origin, projectName);
+  const data = (await requestJson(apiUrl, { credential })) as ListPagesData;
+
+  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/listProjects.ts

@@ -0,0 +1,67 @@
+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 listProjectsSummary = '自分が参加しているprojectの一覧を取得する';
+
+export const listProjectsHelp = `listProjects - 自分が参加しているprojectの一覧を取得する
+
+Usage:
+  cosense listProjects <origin>
+
+引数:
+  <origin>  Cosenseサーバーのorigin（例: https://scrapbox.io）
+
+戻り値（top-levelの主なkey）:
+  projects  Array<Project>  updated降順
+
+Project の field:
+  id              string                       Cosense内部のID
+  name            string                       project名（URLパス）
+  displayName     string                       表示名
+  publicVisible   boolean                      公開projectかどうか
+  loginStrategies Array<string>                認証方法（google / microsoft / saml / email 等）
+  plan            string?                      課金plan名
+  additionalPlans { [planName]: boolean }      追加plan
+  alert           object?                      project内に表示される通知
+  usersCount      number                       メンバー数
+  isMember        boolean                      自分がメンバーか
+  billingId       string?                      billing ID
+  created         string                       作成時刻
+  updated         string                       更新時刻
+  isOwner         boolean?                     自分がownerか
+  isAdmin         boolean?                     自分がadminか
+  adminsCount     number?                      admin数
+`;
+
+export const listProjects = async (args: string[]): Promise<void> => {
+  const [originArg] = args;
+  if (!originArg) throw new Error('Usage: cosense listProjects <origin>');
+  if (args.length > 1) {
+    throw new Error(
+      `Unexpected positional argument: ${args[1]}\nUsage: cosense listProjects <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/projects`, {
+    credential
+  })) as { projects?: Record<string, unknown>[] };
+  if (data.projects) {
+    data.projects.sort((a, b) => {
+      const ua = typeof a.updated === 'number' ? a.updated : 0;
+      const ub = typeof b.updated === 'number' ? b.updated : 0;
+      return ub - ua;
+    });
+  }
+  for (const project of data.projects ?? []) {
+    enrichTimestampsOf(project);
+  }
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+};

package/src/commands/login.ts

@@ -0,0 +1,102 @@
+import { parseOrigin } from '../lib/parseUrl.ts';
+import { settingsPath, writeUserToken } from '../lib/settings.ts';
+
+export const loginSummary = 'Personal Access Tokenを設定ファイルに保存する';
+
+export const loginHelp = `login - Personal Access Tokenを設定ファイルに保存する
+
+Usage:
+  cosense login <origin>
+
+引数:
+  <origin>  Cosenseサーバーのorigin（例: https://scrapbox.io）
+
+動作:
+  - PAT発行URL（<origin>/settings/personal-access-tokens）を出力し、PAT入力を求める
+  - 入力されたPATを ~/.cosense/settings.json の users[] に書き込む
+  - 同じoriginの既存entryは上書きされる
+  - 設定ファイルとディレクトリは存在しなければ作成する（dir 0700, file 0600）
+  - interactive terminal（TTY）でのみ動作する
+
+環境変数:
+  COSENSE_PAT  設定されていれば、ファイルに保存された認証情報より優先される
+`;
+
+const readMaskedLine = async (): Promise<string> => {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'cosense login must be run in an interactive terminal (TTY)'
+    );
+  }
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  const chars: string[] = [];
+  const cleanup = (): void => {
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+  };
+  try {
+    for await (const chunk of process.stdin) {
+      const text = (chunk as Buffer).toString('utf8');
+      for (const ch of text) {
+        const code = ch.charCodeAt(0);
+        if (code === 13 || code === 10) {
+          process.stdout.write('\n');
+          return chars.join('');
+        }
+        if (code === 3 || code === 4) {
+          cleanup();
+          process.stdout.write('\n');
+          process.exit(130);
+        }
+        if (code === 127 || code === 8) {
+          if (chars.length > 0) {
+            chars.pop();
+            process.stdout.write('\b \b');
+          }
+          continue;
+        }
+        if (code < 32) continue;
+        chars.push(ch);
+        process.stdout.write('*');
+      }
+    }
+  } finally {
+    cleanup();
+  }
+  process.stdout.write('\n');
+  return chars.join('');
+};
+
+export const login = async (args: string[]): Promise<void> => {
+  const [originArg, ...rest] = args;
+  if (!originArg) throw new Error('Usage: cosense login <origin>');
+  if (rest.length > 0) {
+    throw new Error(`Unexpected argument: ${rest[0]}`);
+  }
+  const origin = parseOrigin(originArg);
+
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'cosense login must be run in an interactive terminal (TTY)'
+    );
+  }
+
+  process.stdout.write(
+    [
+      `Personal Access Token (PAT) を発行する:`,
+      `  ${origin}/settings/personal-access-tokens`,
+      ``,
+      `発行したPATを以下に貼り付けてEnter（入力は * でマスクされる）:`,
+      `PAT: `
+    ].join('\n')
+  );
+
+  const token = (await readMaskedLine()).trim();
+  if (!token) {
+    throw new Error('PAT is empty');
+  }
+
+  writeUserToken(origin, token);
+  process.stdout.write(`Saved PAT for ${origin} to ${settingsPath}\n`);
+};