@helpfeel/cosense-cli 1.3.0 → 1.4.1

package/README.md

@@ -1,17 +1,10 @@
 # @helpfeel/cosense-cli
 
-Cosenseのページを読み・調べ・編集する為のCLIとAgent Skill
+Cosenseのページを読み・調べ・編集するAgent SkillとCLI
 
-## Install
+## Install Agent Skill
 
-### CLI
-
-```bash
-npm install -g https://github.com/helpfeel/cosense-cli
-cosense --help
-```
-
-### Claude Code Agent Skill
+### for Claude Code
 
 ```
 /plugin marketplace add helpfeel/cosense-cli
@@ -21,7 +14,20 @@ cosense --help
 /plugin install cosense-cli@cosense-cli
 ```
 
-Skillの実行にはCLIが必要
+### for Codex
+
+```
+$skill-installer https://github.com/helpfeel/cosense-cli
+```
+
+## Install CLI
+
+Skillの実行にはCLIが必要です
+
+```bash
+npm install -g @helpfeel/cosense-cli
+cosense --help
+```
 
 ## 開発
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@helpfeel/cosense-cli",
-  "version": "1.3.0",
-  "description": "Cosense (旧Scrapbox) のページを読み・調べ・編集するCLI",
+  "version": "1.4.1",
+  "description": "Cosense (旧Scrapbox) のページを読み・調べ・編集するAgent Skill用のCLI",
   "homepage": "https://github.com/helpfeel/cosense-cli",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/helpfeel/cosense-cli.git"
+    "url": "git+https://github.com/helpfeel/cosense-cli.git"
   },
   "bin": {
-    "cosense": "./bin/cosense"
+    "cosense": "bin/cosense"
   },
   "files": [
     "bin",
@@ -38,6 +38,6 @@
   },
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.com/"
+    "registry": "https://registry.npmjs.org/"
   }
 }

package/src/commands/browsePage.ts

@@ -52,7 +52,7 @@ Usage:
   ## 1 hop link
     このページの 1-hop 近傍ページタイトル一覧。 1-hop が 0 件なら区切り線ごと省略
 
-非存在ページ (persistent: false):
+persistent: false の時:
   メタデータ・アイコン・テロメアは省略。 (このページはまだ作成されていません) と
   本文（テンプレート）と Related Pages を出力する
 

package/src/commands/browseRelatedPages.ts

@@ -7,9 +7,9 @@ import {
 import { fetchRelatedPages } from '../lib/relatedPages.ts';
 
 export const browseRelatedPagesSummary =
-  '1-hop+2-hopのタイトル一覧を眺める。単独のページだけを見ていては掴みきれない文脈が浮かび上がる';
+  '1-hop+2-hopの関連ページタイトル一覧をAIが読みやすい形式で出力する';
 
-export const browseRelatedPagesHelp = `browseRelatedPages - 1-hop+2-hopのタイトル一覧を眺める。単独のページだけを見ていては掴みきれない文脈が浮かび上がる
+export const browseRelatedPagesHelp = `browseRelatedPages - 1-hop+2-hopの関連ページタイトル一覧をAIが読みやすい形式で出力する
 
 Usage:
   cosense browseRelatedPages <pageUrl>

package/src/commands/listPages.ts

@@ -52,7 +52,7 @@ User の field（user / lastUpdateUser / users[] で共通）:
   email        string?  メールアドレス
 
 注意:
-  - ページ本文（lines）は含まれない。本文が必要なら readPage を使う
+  - ページ本文（lines）は含まれない
   - 1000件を超える件数を1リクエストで取ることはできない。--skip でページネーションする
 `;
 

package/src/commands/previewEdit.ts

@@ -9,14 +9,15 @@ export const previewEditSummary =
 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>
+  cosense previewEdit <projectUrl> <pageId> < ops.json      既存ページの編集 (stdinはops JSON)
+  cosense previewEdit --new <projectUrl> < body.txt         新規ページ作成 (stdinはプレーンテキスト本文)
+  printf '%s' '<opsJSON>' | cosense previewEdit <projectUrl> <pageId>
+  printf '%s' '<text>'    | cosense previewEdit --new <projectUrl>
 
 引数:
   <projectUrl>  プロジェクトのURL (例: https://scrapbox.io/shokai)。 末尾に余分なpathがあるとerror
   <pageId>      編集対象ページのID。 readPage 出力の top-level "id" field から取得する
+                ops 内の <lineId> は readPage 出力の lines[].id から取得する
 
 オプション:
   --new   stdin をプレーンテキスト本文として受け取り、 新規ページを作る。 改行で複数行に分割され、
@@ -36,12 +37,9 @@ stdinから受け取る入力形式（既存ページ編集モード, JSON）:
   replace:      <lineId> の本文を置き換える。textは単行のみ。改行を含むtextは拒否される
   delete:       <lineId> の行を削除する
 
-  「特定行を複数行に分割したい」場合は、insertBefore で対象lineIdの直前に複数行を挿入してから、
-  対象行を delete する。ops は配列順に適用されるので「先に delete してから insertBefore」 とすると
-  anchor が消えて 422 になる。
-
-  ops は順次適用される。同じ lineId に対する insertBefore を [A, B, C] の順で並べると、
-  適用後の行順は元行の直前に [A, B, C] が並ぶ（入力順が保たれる）。
+  ops は配列順に適用される。同じ anchor に対する insertBefore を [A, B, C] の順で並べると、
+  適用後の行順は元行の直前に [A, B, C] が並ぶ（入力順が保たれる）。anchor は適用時点で存在
+  する必要がある（消えた lineId を anchor に指定すると 422）。
 
 戻り値（plain text）:
   previewId / expireAt / status (create or update) / project / title のヘッダー +
@@ -49,8 +47,7 @@ stdinから受け取る入力形式（既存ページ編集モード, JSON）:
   変更行の頭には > (新規) または * (更新) のマーカーと末尾 # <lineId> が付く。
   既存行(変更なし)はマーカーなし。
   preview は dry-run なのでこの段階ではpage URLは確定しない。 確定URLは submitEdit の出力で確認する。
-
-  submitEdit でこのpreviewIdを渡してcommitを確定する。previewIdは5分でexpireする。
+  previewId は submitEdit に渡して commit を確定する。5分で expire する。
 
 HTTPエラー:
   HTTP 401  認証なし
@@ -59,18 +56,6 @@ HTTPエラー:
   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 {

package/src/commands/readPage.ts

@@ -16,7 +16,7 @@ Usage:
 
 戻り値（top-levelの主なkey）:
   title          string               ページタイトル
-  persistent     boolean              実体のあるページなら true。false でも関連ページリストは存在する場合がある
+  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 の時のみ)

package/src/commands/search1hopLinks.ts

@@ -22,7 +22,7 @@ Usage:
   search  検索ハイライト情報
 
 検索の制約:
-  - OR検索不可。複数キーワードを試したい時はクエリを分解して複数回叩く
+  - OR検索不可
 `;
 
 export const search1hopLinks = async (args: string[]): Promise<void> => {

package/src/commands/search2hopLinks.ts

@@ -22,7 +22,7 @@ Usage:
   search  検索ハイライト情報
 
 検索の制約:
-  - OR検索不可。複数キーワードを試したい時はクエリを分解して複数回叩く
+  - OR検索不可
 `;
 
 export const search2hopLinks = async (args: string[]): Promise<void> => {

package/src/commands/searchVector.ts

@@ -19,7 +19,7 @@ Usage:
 戻り値（top-levelの主なkey）:
   pages  Array<Page>  類似度順のヒット結果
 
-各 page の field:
+各 Page の field:
   title           string          ページタイトル
   image           string          サムネイル画像URL
   score           number          類似度スコア（高いほど近い）
@@ -47,7 +47,6 @@ User の field（user / lastUpdateUser / users[] で共通）:
 検索対象:
   - ページタイトル + 本文中のリンク記法（[title]）のみ
   - 本文の通常テキストは検索対象外
-  - 本文の語で検索したい時は searchFullText を使う
 
 戻り値のJSON抜粋例:
 {

package/src/commands/submitEdit.ts

@@ -34,9 +34,7 @@ HTTPエラー:
   HTTP 409 {"error":"DuplicateTitle"}
             preview→submit の間に他人が同名ページを作った (race condition)
 
-ワークフロー:
-  previewIdは1回しか使えない (consume-on-submit)。submitに失敗したら previewEdit から
-  やり直す。previewIdは5分でexpireするので submit は迅速に。
+previewId は1回限り (consume-on-submit)。submit 後・5分 expire 後・consume 済みは HTTP 404。
 `;
 
 interface SubmitResponse {