@tocca-systems/twp-cli 0.17.0 → 0.18.0

package/README.md

@@ -80,6 +80,11 @@ twp task comment create <キー|ID> --body-file <背景.md> \
   --ask-question --question "<質問文>" --option ok=このまま進める --option back=差し戻す
 twp task comment create <キー|ID> --body-file <回答.md> --answer-to <コメントID> --select ok
 
+# タスクの添付ファイル
+twp task attachment list     <キー|ID>                                        # id / file_name / content_type / file_size / is_committed / created_at
+twp task attachment upload   <キー|ID> --file <パス> [--name <ファイル名>] [--content-type <型>]
+twp task attachment download <添付ID> --out <パス> [--force]
+
 # --status / --type などに渡せる値を調べる
 twp task status list    [--project <コード>]
 twp task type list      [--project <コード>]
@@ -97,7 +102,9 @@ twp task label list     [--project <コード>]
 - **フラグの値は `--flag 値` でも `--flag=値` でも書けます。** 空白を含む値は `--keyword "山田 太郎"` のように引用し、`-` で始まる値は `--keyword=-foo` の形で渡します
 - **質問（`--ask-question`）は質問文（`--question` / `--question-file`）と選択肢（`--option キー=表示文`・1〜5個）が要ります。** 選択肢のキーは10文字以内で、回答（`--select`）に使う識別子です。複数選択は `--multi-select`、自由記述を禁じるなら `--no-free-text`
 - **`twp task comment list` の `question` / `answer` 列で、回答済みかどうかが分かります**（同じページにある回答を質問の行へ突き合わせます。ページをまたぐ場合は `--all` を付けてください）
-- ヘルプは `twp task help` / `twp task comment help` / `twp task create help`
+- **`twp task attachment upload` はアップロード用URLの発行・ファイルの転送・タスクへの紐づけを1コマンドで行います。** 既にある添付は残したまま追加します。紐づけに失敗したときは添付IDを stderr に出して失敗で終わります（紐づけていない添付はサーバが自動で削除するので、そのまま再実行して構いません）。`--dry-run` は最初のリクエスト（URLの発行）だけを表示します
+- `twp task attachment download` は `twp backlog attachment download` と同じく **`--out` のパスへ実体を書き出し、既存ファイルは `--force` を付けたときだけ上書きします**。添付ID は `twp task attachment list` の `id` です
+- ヘルプは `twp task help` / `twp task comment help` / `twp task create help` / `twp task attachment help`
 
 グローバルオプション: `--profile <名前>` / `--output <json|table|text|tsv>` / `--query <JMESPath>` / `--dry-run` / `--debug` / `--yes` / `--refresh`。**`--output json` は常に API の生のレスポンス**を返します（表示用に間引きません）。
 
@@ -252,8 +259,8 @@ twp login
 
 | モード | ツール | 権限 |
 |---|---|---|
-| 開発 `dev` | ローカルツール全部 ＋ 開発系 TWP ドメイン | 書き込みは確認 / 読み取りは許可 |
-| 業務 `biz` | TWP ドメイン中心 | `bash` と `write_file` は拒否 |
+| 開発 `dev` | ローカルツール全部 ＋ 開発系 TWP ドメイン | 書き込み・コマンド実行（`git` を含む）は確認 / 読み取りは許可 |
+| 業務 `biz` | TWP ドメイン中心 | `bash` と `write_file` と `git` は拒否 |
 | プラン `plan` | 読み取りのみ | 全書き込み拒否 |
 
 **モデルはモードと直交する。** 業務モードに切り替えてもモデルは変わらない（`/model` で別に切り替える）。
@@ -285,6 +292,42 @@ permissions:
 - **書き間違えても起動は止まらない。** 読めなかった項目は警告を出して既定へ戻る。起動時に `⚠ モード定義:` が出たらその行を直す
 - いま何が効いているかは `/context` で確認できる（どのファイルが効いているか・有効ツール glob・常駐ツールの実体が出る）
 
+### 権限ルール（`~/.twp/settings.json` と `--allowed-tools`）
+
+「このコマンドは毎回聞かなくてよい」「このツールは絶対に使わせない」を、Claude Code と同じ記法で書ける。組織で使っている Claude Code の allowlist をそのまま移せる。
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(git status:*)", "Bash(npm test)", "Write(src/**)", "git(log:*)"],
+    "ask": ["Bash(git push:*)"],
+    "deny": ["Bash(rm:*)", "twp_delete_task"]
+  }
+}
+```
+
+| 書き方 | 意味 |
+|---|---|
+| `Bash` / `twp_update_task` | そのツール全体 |
+| `Bash(git status:*)` | `git status` で始まるコマンド（語の区切りで一致） |
+| `Bash(npm test)` | そのコマンドと完全一致 |
+| `Write(src/**)` / `Edit(src/*.ts)` / `Read(~/notes/**)` | パスの glob（素の相対と `/` 始まりは作業ディレクトリ基準・`//` 始まりは絶対パス・`~/` はホーム）。`Edit` は `write_file` も含む |
+| `git(log:*)` | `git` ツールの `<サブコマンド> <引数>` |
+
+置き場所と強さ（上ほど強い）: `--allowed-tools` / `--disallowed-tools`（カンマ区切り・繰り返し可）→ セッション内の「今後聞かない」→ `.twp/settings.local.json` → `.twp/settings.json` → `~/.twp/settings.json` → モードの方針。
+
+- **拒否（deny）は常に勝つ。** どこに書いた deny も、どれだけ具体的な allow にも負けない。**モードの拒否も覆らない**（`--allowed-tools Bash` を付けても業務モードの `bash` は拒否のまま）
+- 拒否が無ければ**より具体的なルールが勝つ**（`Bash` の allow より `Bash(npm test)` の ask が強い）。同じ具体性なら上の置き場所が勝つ
+- **`Bash(git status:*)` を許可しても `git status && rm -rf .` は通らない。** 許可ルールは「解釈の余地が無い文字（英数字と `_ - . / = : , @ % +` と空白）だけでできた1本のコマンド」にしか当たらない。引用符・`$`・`#`・`~`・`*`・分岐・リダイレクトを含むものと `rm -rf` には当たらず、確認へ落ちる（`git commit -m "x"` のような引用符付きも確認になる）。拒否ルールは逆に、分岐した後ろの断片にも当たる
+- **Windows の `shell`（PowerShell / cmd）には `Bash(...)` の許可ルールを当てない**（引用と分岐の規則が bash と違うため。拒否ルールは当たる）
+- **信用できないリポジトリでは git の許可ルールも安全ではない。** `git status` は `.git/config` の `core.fsmonitor` を、`git log -p` は textconv を実行しうる。上の例の `Bash(git status:*)` / `git(log:*)` は、自分で clone した信用できるリポジトリで使う
+- **リポジトリ側（`.twp/settings.json` / `.twp/settings.local.json`）は締める向きにしか効かない。** `allow` は無視して警告する（モード定義ファイルと同じ理由）。緩めるときは自分の `~/.twp/settings.json` に書く
+- **設定ファイルが読めないと自動許可を止める。** 壊れたファイルに書いていた拒否が消えて緩むのを避けるため、直るまで「許可」は「確認」に変わる。起動時に `⚠ 権限設定:` が出たらその行を直す
+- **拒否ルールは「よくある書き方を止める網」であって、書いたコマンドを確実に止める境界ではない。** `sudo rm` `/bin/rm` `then rm` `$(rm …)` のような書き方には当たるが、`find -exec rm` のように引数の中から起動するものは拾えない。確実に止めたいならツールごと拒否する（`Bash`）か、業務・プランモードを使う
+- `Read(...)` の拒否は `grep` / `glob` にも効くが、**探索の起点がその範囲の中にあるときだけ**（リポジトリ全体を起点にした `grep` は、拒否した範囲の中まで読む）。確実に読ませないなら `Read` ごと拒否するか業務・プランモードを使う
+- 設定ファイルが読めない間は、読み取りも含めて**すべての自動許可が確認に変わる**（`-p` では確認できないので拒否になる）
+- `twp_call`（ツールを名前で呼ぶメタツール）は**中で実行されるツールの名前**で判定するよう権限エンジン側は用意してある。`twp_call` そのものを許可しても何も緩まない。**ただし `twp_call` 自体はまだ無い**（今後のバージョンで追加）
+
 ### `--permission-mode`（実行1回ぶんの上書き）
 
 モードの方針の上に、その実行ぶんの既定を重ねる。CI・SSH・パイプで「何が自動で通るか」を呼び出し側が明示するためのもの。

package/command-model/company.json

@@ -299,30 +299,35 @@
           "name": "keyword",
           "type": "string",
           "required": false,
+          "description": "キーワードで絞り込む",
           "source": "spec"
         },
         {
           "name": "customer_flg",
           "type": "string",
           "required": false,
+          "description": "true で顧客、false で顧客でない企業に絞り込む",
           "source": "spec"
         },
         {
           "name": "supplier_flg",
           "type": "string",
           "required": false,
+          "description": "true で仕入先、false で仕入先でない企業に絞り込む",
           "source": "spec"
         },
         {
           "name": "sort_column",
           "type": "string",
           "required": false,
+          "description": "並べ替える列（id / company_name / company_short_name / created_at / updated_at）",
           "source": "spec"
         },
         {
           "name": "sort_direction",
           "type": "string",
           "required": false,
+          "description": "asc / desc",
           "source": "spec"
         },
         {
@@ -338,6 +343,20 @@
           "required": false,
           "description": "次ページの取得に使うカーソル",
           "source": "curation"
+        },
+        {
+          "name": "page_limit",
+          "type": "integer",
+          "required": false,
+          "description": "1ページあたりの件数（既定 20・最大 100。この一覧は limit ではなくこちらを読む）",
+          "source": "curation"
+        },
+        {
+          "name": "page_no",
+          "type": "integer",
+          "required": false,
+          "description": "ページ番号（1始まり）",
+          "source": "curation"
         }
       ],
       "body": null,

package/command-model/department.json

@@ -14,6 +14,7 @@
           "name": "parent_id",
           "type": "string",
           "required": false,
+          "description": "親部署のID（省略すると最上位の部署）",
           "source": "spec"
         },
         {
@@ -190,12 +191,14 @@
           "name": "status",
           "type": "string",
           "required": false,
+          "description": "部署の状態で絞り込む",
           "source": "spec"
         },
         {
           "name": "keyword",
           "type": "string",
           "required": false,
+          "description": "キーワードで絞り込む",
           "source": "spec"
         },
         {
@@ -247,6 +250,13 @@
           "required": false,
           "description": "次ページの取得に使うカーソル",
           "source": "curation"
+        },
+        {
+          "name": "current_only",
+          "type": "boolean",
+          "required": false,
+          "description": "現在所属しているメンバーだけにする（既定 true。false で過去の所属者も含める）",
+          "source": "curation"
         }
       ],
       "body": null,

package/command-model/equipment.json

@@ -14,18 +14,21 @@
           "name": "category_ids",
           "type": "string",
           "required": false,
+          "description": "備品カテゴリIDで絞り込む（カンマ区切り）",
           "source": "spec"
         },
         {
           "name": "start_date",
           "type": "string",
           "required": false,
+          "description": "貸出開始日（YYYY-MM-DD）。この期間に貸し出せる備品だけを返す",
           "source": "spec"
         },
         {
           "name": "due_date",
           "type": "string",
           "required": false,
+          "description": "返却予定日（YYYY-MM-DD）",
           "source": "spec"
         },
         {
@@ -175,6 +178,7 @@
           "name": "search",
           "type": "string",
           "required": false,
+          "description": "キーワードで絞り込む",
           "source": "spec"
         },
         {
@@ -329,6 +333,7 @@
           "name": "status",
           "type": "string",
           "required": false,
+          "description": "貸出の状態で絞り込む",
           "source": "spec"
         },
         {

package/command-model/index.json

@@ -189,7 +189,7 @@
     },
     {
       "domain": "company",
-      "summary": "",
+      "summary": "取引先企業",
       "operationCount": 5
     },
     {
@@ -234,7 +234,7 @@
     },
     {
       "domain": "customer-contact",
-      "summary": "",
+      "summary": "顧客企業の担当者",
       "operationCount": 8
     },
     {
@@ -259,7 +259,7 @@
     },
     {
       "domain": "department",
-      "summary": "",
+      "summary": "部署",
       "operationCount": 8
     },
     {
@@ -314,7 +314,7 @@
     },
     {
       "domain": "equipment",
-      "summary": "",
+      "summary": "備品と貸出",
       "operationCount": 12
     },
     {
@@ -474,7 +474,7 @@
     },
     {
       "domain": "invoice",
-      "summary": "",
+      "summary": "請求",
       "operationCount": 13
     },
     {
@@ -599,7 +599,7 @@
     },
     {
       "domain": "meeting",
-      "summary": "",
+      "summary": "議事録",
       "operationCount": 13
     },
     {
@@ -649,7 +649,7 @@
     },
     {
       "domain": "my-task",
-      "summary": "",
+      "summary": "自分のタスク（プロジェクト横断）",
       "operationCount": 5
     },
     {
@@ -664,7 +664,7 @@
     },
     {
       "domain": "note",
-      "summary": "",
+      "summary": "ノート",
       "operationCount": 10
     },
     {
@@ -694,7 +694,7 @@
     },
     {
       "domain": "notification",
-      "summary": "",
+      "summary": "通知",
       "operationCount": 10
     },
     {
@@ -784,7 +784,7 @@
     },
     {
       "domain": "private-task",
-      "summary": "",
+      "summary": "個人タスク",
       "operationCount": 7
     },
     {
@@ -804,7 +804,7 @@
     },
     {
       "domain": "project",
-      "summary": "",
+      "summary": "プロジェクト",
       "operationCount": 10
     },
     {
@@ -839,7 +839,7 @@
     },
     {
       "domain": "project-member",
-      "summary": "",
+      "summary": "プロジェクトのメンバー",
       "operationCount": 9
     },
     {
@@ -884,7 +884,7 @@
     },
     {
       "domain": "project-task",
-      "summary": "",
+      "summary": "プロジェクトのタスク",
       "operationCount": 22
     },
     {
@@ -899,7 +899,7 @@
     },
     {
       "domain": "project-task-comment",
-      "summary": "",
+      "summary": "タスクのコメント",
       "operationCount": 7
     },
     {
@@ -959,7 +959,7 @@
     },
     {
       "domain": "prospect",
-      "summary": "",
+      "summary": "見込客",
       "operationCount": 9
     },
     {
@@ -1054,7 +1054,7 @@
     },
     {
       "domain": "report",
-      "summary": "",
+      "summary": "日報・レポート",
       "operationCount": 51
     },
     {
@@ -1214,7 +1214,7 @@
     },
     {
       "domain": "survey",
-      "summary": "",
+      "summary": "アンケート・組織サーベイ",
       "operationCount": 36
     },
     {
@@ -1334,7 +1334,7 @@
     },
     {
       "domain": "user",
-      "summary": "",
+      "summary": "ログイン中のユーザーとテナントのユーザー",
       "operationCount": 30
     },
     {
@@ -1424,7 +1424,7 @@
     },
     {
       "domain": "wiki",
-      "summary": "",
+      "summary": "プロジェクトの Wiki",
       "operationCount": 11
     },
     {
@@ -1479,7 +1479,7 @@
     },
     {
       "domain": "workflow-instance",
-      "summary": "",
+      "summary": "ワークフローの申請",
       "operationCount": 7
     },
     {

package/command-model/invoice.json

@@ -363,7 +363,7 @@
       "operationId": "invoice.destroy",
       "method": "DELETE",
       "path": "/v2/sales/invoices/{id}",
-      "summary": "",
+      "summary": "請求を削除",
       "pathParams": [
         {
           "name": "id",
@@ -391,12 +391,14 @@
           "name": "sort_column",
           "type": "string",
           "required": false,
+          "description": "並べ替える列（一覧と同じ）",
           "source": "spec"
         },
         {
           "name": "sort_direction",
           "type": "string",
           "required": false,
+          "description": "asc / desc",
           "source": "spec"
         },
         {
@@ -432,18 +434,21 @@
           "name": "debit_account",
           "type": "string",
           "required": false,
+          "description": "借方の勘定科目（既定 売上高）",
           "source": "spec"
         },
         {
           "name": "credit_account",
           "type": "string",
           "required": false,
+          "description": "貸方の勘定科目",
           "source": "spec"
         },
         {
           "name": "invoice_date_from",
           "type": "string",
           "required": false,
+          "description": "対象とする取引日の起点",
           "source": "spec"
         },
         {
@@ -515,18 +520,21 @@
           "name": "sort_column",
           "type": "string",
           "required": false,
+          "description": "並べ替える列",
           "source": "spec"
         },
         {
           "name": "sort_direction",
           "type": "string",
           "required": false,
+          "description": "asc / desc",
           "source": "spec"
         },
         {
           "name": "consolidated_view",
           "type": "boolean",
           "required": false,
+          "description": "true で統合請求書の下に統合元の請求書を children として付ける",
           "source": "spec"
         },
         {
@@ -542,10 +550,24 @@
           "required": false,
           "description": "次ページの取得に使うカーソル",
           "source": "curation"
+        },
+        {
+          "name": "page_limit",
+          "type": "integer",
+          "required": false,
+          "description": "1ページあたりの件数（既定 20・最大 100。この一覧は limit ではなくこちらを読む）",
+          "source": "curation"
+        },
+        {
+          "name": "page_no",
+          "type": "integer",
+          "required": false,
+          "description": "ページ番号（1始まり）",
+          "source": "curation"
         }
       ],
       "body": null,
-      "resultPath": null,
+      "resultPath": "list",
       "risk": "read",
       "aliases": []
     },

package/command-model/meeting.json

@@ -7,7 +7,7 @@
       "operationId": "meeting.store",
       "method": "POST",
       "path": "/v2/meetings",
-      "summary": "",
+      "summary": "議事録を作成",
       "pathParams": [],
       "queryParams": [],
       "body": {
@@ -288,7 +288,7 @@
       "operationId": "meeting.createTaskFromActionItem",
       "method": "POST",
       "path": "/v2/meetings/{id}/action-items/{actionItemId}/create-task",
-      "summary": "",
+      "summary": "アクションアイテムからタスクを作成",
       "pathParams": [
         {
           "name": "id",
@@ -327,7 +327,7 @@
       "operationId": "meeting.destroy",
       "method": "DELETE",
       "path": "/v2/meetings/{id}",
-      "summary": "",
+      "summary": "議事録を削除",
       "pathParams": [
         {
           "name": "id",
@@ -466,7 +466,7 @@
       "operationId": "meeting.show",
       "method": "GET",
       "path": "/v2/meetings/{id}",
-      "summary": "",
+      "summary": "議事録詳細を取得",
       "pathParams": [
         {
           "name": "id",
@@ -492,7 +492,7 @@
         }
       ],
       "body": null,
-      "resultPath": "meeting",
+      "resultPath": null,
       "risk": "read",
       "aliases": []
     },
@@ -512,6 +512,7 @@
             "null"
           ],
           "required": false,
+          "description": "プロジェクトIDで絞り込む",
           "source": "spec"
         },
         {
@@ -521,12 +522,14 @@
             "null"
           ],
           "required": false,
+          "description": "キーワードで絞り込む",
           "source": "spec"
         },
         {
           "name": "tags[]",
           "type": "array",
           "required": false,
+          "description": "タグで絞り込む（複数指定可）",
           "source": "spec"
         },
         {
@@ -536,6 +539,7 @@
             "null"
           ],
           "required": false,
+          "description": "並び順（meeting_date / created_at / updated_at / title）",
           "source": "spec"
         },
         {
@@ -545,30 +549,35 @@
             "null"
           ],
           "required": false,
+          "description": "asc / desc",
           "source": "spec"
         },
         {
           "name": "status",
           "type": "string",
           "required": false,
+          "description": "状態で絞り込む",
           "source": "spec"
         },
         {
           "name": "meeting_type",
           "type": "string",
           "required": false,
+          "description": "会議の種類で絞り込む",
           "source": "spec"
         },
         {
           "name": "start_date",
           "type": "string",
           "required": false,
+          "description": "開催日がこの日以降（YYYY-MM-DD）",
           "source": "spec"
         },
         {
           "name": "end_date",
           "type": "string",
           "required": false,
+          "description": "開催日がこの日以前（YYYY-MM-DD）",
           "source": "spec"
         },
         {
@@ -611,24 +620,28 @@
           "name": "status",
           "type": "string",
           "required": false,
+          "description": "状態で絞り込む",
           "source": "spec"
         },
         {
           "name": "meeting_type",
           "type": "string",
           "required": false,
+          "description": "会議の種類で絞り込む",
           "source": "spec"
         },
         {
           "name": "start_date",
           "type": "string",
           "required": false,
+          "description": "開催日がこの日以降（YYYY-MM-DD）",
           "source": "spec"
         },
         {
           "name": "end_date",
           "type": "string",
           "required": false,
+          "description": "開催日がこの日以前（YYYY-MM-DD）",
           "source": "spec"
         },
         {
@@ -647,7 +660,7 @@
         }
       ],
       "body": null,
-      "resultPath": null,
+      "resultPath": "items",
       "risk": "read",
       "aliases": []
     },
@@ -657,7 +670,7 @@
       "operationId": "meeting.pendingActionItems",
       "method": "GET",
       "path": "/v2/meetings/pending-action-items",
-      "summary": "",
+      "summary": "プロジェクトの議事録にある未完了のアクションアイテム一覧を取得",
       "pathParams": [],
       "queryParams": [
         {
@@ -673,6 +686,13 @@
           "required": false,
           "description": "次ページの取得に使うカーソル",
           "source": "curation"
+        },
+        {
+          "name": "project_id",
+          "type": "string",
+          "required": false,
+          "description": "対象プロジェクトのID。省略するとサーバは常に0件を返す",
+          "source": "curation"
         }
       ],
       "body": null,
@@ -686,7 +706,7 @@
       "operationId": "meeting.publish",
       "method": "POST",
       "path": "/v2/meetings/{id}/publish",
-      "summary": "",
+      "summary": "議事録を公開",
       "pathParams": [
         {
           "name": "id",
@@ -736,7 +756,7 @@
       "operationId": "meeting.update",
       "method": "PUT",
       "path": "/v2/meetings/{id}",
-      "summary": "",
+      "summary": "議事録を更新",
       "pathParams": [
         {
           "name": "id",

package/command-model/my-task.json

@@ -108,6 +108,7 @@
           "name": "include_completed",
           "type": "boolean",
           "required": false,
+          "description": "true で完了済みのタスクも含める",
           "source": "spec"
         },
         {