@shimatoworks/stw-agent 0.2.0 → 0.3.0

package/README.md

@@ -35,9 +35,33 @@ set -a && source ~/.config/tamai/stw-agent.env && set +a
 stw-agent --help
 ```
 
-動詞は `doctor` / `projects list` / `projects context` / `slack channels` /
-`slack messages` / `slack next` の 6 つ。正確なオプションは常に `--help` を見る
-（ここに写経しない）。
+動詞は `doctor` / `projects list` / `projects context` / `projects resources` /
+`projects next` / `slack channels` / `slack messages` / `slack next` の 8 つ。
+正確なオプションは常に `--help` を見る（ここに写経しない）。
+
+### Drive の資料を探す（`projects resources`）
+
+```bash
+stw-agent projects resources yoshino
+```
+
+案件に紐付いた **Drive 入口フォルダ配下の索引**（名前・MIME・更新日・親子・
+ショートカット先・「資料候補」の印）を返す。入口の URL だけでは
+「直下に 1 フォルダしかなく、主要資料はさらに下」という形に辿り着けないため。
+
+**本文は返らない。** `fileId` を `gog` へ渡して読む（guide §4）。
+
+読み方で気をつけること:
+
+- 索引は「**SA が読めるメタデータを、台帳で指定された受け手へ公開する**」もので、
+  本人が Google で読める全ファイルではない。入口ごとに admin が有効化したものだけが出る
+- `indexes[].complete` が false なら**まだ全部ではない**（`reason` に理由がある）。
+  **終了コード 0 でも起こる**ので、「これで全部」と書かない
+- 続きは出力の「次:」行をそのまま実行する（`projects next '<query>' --slug <slug>`）。
+  cursor は不透明な値で、手で組み立てると 400 になる
+- `409` は索引が作り直された合図。`--cursor` を外して取り直す
+- `503 drive_unavailable` は一時的な確認失敗。**古い一覧を成功として返さない**ので、
+  空ではなくエラーになる
 
 ### まず `doctor`
 
@@ -73,6 +97,13 @@ token・読み取り API への到達・token の権限・周辺ツール（`ntn
 
 ## 変更履歴
 
+- **0.3.0** — `projects resources`（Drive 入口配下の索引）と `projects next` を追加。
+  資料候補をページ内で先に出し、`complete=false` のときは理由を必ず添える。
+  409 / `503 drive_unavailable` に「取り直す」「一時的」の案内を付けた。
+  **本文は返さない**（`fileId` を `gog` へ渡す）
+- **0.2.1** — `doctor` の bun の案内を「入れたあと PATH に `~/.bun/bin` を足す」まで書くようにした。
+  publish は GitHub Actions（npm trusted publishing・タグ push）へ移した
+  （repo が private なので provenance は付かない）
 - **0.2.0** — `stw-agent doctor` を追加（token・API 到達・権限・周辺ツールの一括確認）。
   `STW_API_BASE` に資格情報が入っていれば要求前に拒否し、表示は origin だけにする。
   `slack channels` の既定出力に、サーバが返すようになれば保存範囲（最古〜最新・件数）と

package/bin/stw-agent.mjs

@@ -53,11 +53,14 @@ export const USAGE = `使い方:
   stw-agent projects context <slug> [--include-slack <true|false>]
                                     [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>]
                                     [--q <text>] [--limit <n>] [--json]
+  stw-agent projects resources <slug> [--system drive] [--resource-id <uuid>]
+                                      [--limit <n>] [--cursor <c>] [--json]
   stw-agent slack channels [--project <slug>] [--limit <n>] [--cursor <c>] [--json]
   stw-agent slack messages (--project <slug> | --channel <id>)
                            [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--q <text>]
                            [--limit <n>] [--thread <ts>] [--cursor <c>] [--json]
   stw-agent slack next <continuationQuery> [--json]
+  stw-agent projects next <continuationQuery> --slug <slug> [--json]
   stw-agent doctor [--json]
 
 環境変数:
@@ -72,6 +75,11 @@ export const USAGE = `使い方:
 docs/guides/案件コンテキストの集め方.md を見る。
 既定の出力は 1 行要約（本文は先頭だけ）。全文が要るときだけ --json を付ける。
 期間を省略すると当日を含む直近 30 日。続きは continuationQuery を slack next へそのまま渡す。
+
+projects resources は Drive 入口の**索引**（名前・MIME・更新日・親子・ショートカット先）を返す。
+**本文は返さない** —— fileId を gog へ渡して読む（guide §4）。
+索引は「SA が読めるメタデータを台帳の受け手へ公開する」もので、本人が Google で読める
+全ファイルではない。complete=false なら**まだ全部ではない**（終了コード 0 でも起こる）。
 `;
 
 // ---------------------------------------------------------------------------
@@ -356,9 +364,17 @@ export function formatFailure(error) {
   if (error.status === 404) {
     lines.push('  対象が無いか、この token の許可範囲外です。403 との違いは guide §3 を見る。');
   }
+  if (error.status === 409) {
+    // **cursor を組み立て直させない**（索引が作り直された後の続きは存在しない）。
+    lines.push('  索引が更新されました。--cursor を外して取り直してください。');
+  }
   if (error.status === 429) {
     lines.push('  枠（60 回/分・1,000 回/時）を超えました。token は他のワーカーと共有です。');
   }
+  if (error.status === 503 && code === 'drive_unavailable') {
+    lines.push('  Drive の再確認ができませんでした（一時的）。少し待って同じ要求を出す。');
+    lines.push('  古い一覧を「成功」として返さないので、空ではなく 503 になります。');
+  }
   return lines.join('\n');
 }
 
@@ -480,6 +496,65 @@ export function formatLastFailure(channel) {
   return `失敗 ${failure.code}${at}`;
 }
 
+/**
+ * Drive の索引 1 行（`projects resources`）。
+ *
+ * **文書候補をページ内で先に出す**（§6）。`hints.candidate` が true のものを上へ持ってきて、
+ * 名前・MIME・更新日・fileId・入口からの相対位置を示す。並べ替えるのは**このページの中だけ**
+ * で、取得順（keyset）そのものは変えない —— 変えると続きのページで取りこぼす。
+ *
+ * 本文は返らないので、読むときは fileId を gog へ渡す（guide §4）。
+ */
+export function formatDriveResourceLines(response) {
+  const lines = [];
+
+  for (const index of response.indexes ?? []) {
+    const parts = [`入口 ${index.resourceId}`];
+    parts.push(index.state === 'never' ? '索引なし' : `索引 ${index.state}`);
+    if (index.indexedAt) parts.push(`取得 ${formatJst(index.indexedAt)}`);
+    // **「全部ある」と読ませない。** complete でなければ理由を必ず添える。
+    parts.push(index.complete ? '読み切り' : `未完（${index.reason ?? '理由不明'}）`);
+    if (index.stale) parts.push('鮮度切れ');
+    lines.push(parts.join('  '));
+  }
+  if ((response.indexes ?? []).length === 0) {
+    lines.push('（索引が有効な Drive 入口はありません）');
+  }
+
+  const items = [...(response.items ?? [])];
+  // 候補を先に（同じ候補の中では取得順のまま）。
+  const ordered = [
+    ...items.filter((item) => item.hints?.candidate === true),
+    ...items.filter((item) => item.hints?.candidate !== true),
+  ];
+  for (const item of ordered) {
+    const mark = item.hints?.candidate ? '*' : ' ';
+    const reasons = (item.hints?.reasons ?? []).join(',') || '-';
+    const modified = item.modifiedTime ? formatJst(item.modifiedTime) : '-';
+    const shortcut = item.shortcut
+      ? item.shortcut.target
+        ? ` → ${item.shortcut.target.fileId}`
+        : ' → （参照先非公開）'
+      : '';
+    lines.push(
+      `${mark} ${item.fileId}  ${item.name}  ${item.mimeType}  更新 ${modified}  ` +
+        `深さ${item.depth} 親=${item.parentFileId}  ${reasons}${shortcut}`,
+    );
+  }
+  if (ordered.length === 0) lines.push('（このページで確認できた資料はありません）');
+
+  if (response.continuationQuery) {
+    // **slug は query に入らない**（path 側）ので、次要求の形にして出す。
+    const slug = response.project?.slug ?? '<slug>';
+    lines.push(
+      `次: stw-agent projects next '${response.continuationQuery}' --slug ${slug}`,
+    );
+  }
+  // **終端は索引世代の終端**であって、Drive 全件の証明ではない（§6）。
+  lines.push('本文は返りません。読むときは fileId を gog へ渡す（guide §4）。');
+  return lines.join('\n');
+}
+
 export function formatChannelLines(response) {
   const lines = (response.items ?? []).map((channel) => {
     const projects = channel.projectSlugs?.length ? channel.projectSlugs.join(',') : '-';
@@ -754,13 +829,49 @@ export function statusFromHttp(status) {
 async function probeApi(api, requestPath, query) {
   try {
     const payload = await api(requestPath, query);
-    return { status: 200, requestId: payload?.requestId ?? null };
+    // 応答本体も返す（Drive の検査に案件 slug が要る）。**保持するのは呼び出し側の判断**で、
+    // ここでは中身を log にも表示にも出さない。
+    return { status: 200, requestId: payload?.requestId ?? null, payload };
   } catch (error) {
     if (error instanceof ApiError) {
-      return { status: error.status, requestId: error.payload?.requestId ?? null };
+      return { status: error.status, requestId: error.payload?.requestId ?? null, payload: null };
     }
-    return { status: null, requestId: null, transport: error?.message ?? 'unknown' };
+    return { status: null, requestId: null, payload: null, transport: error?.message ?? 'unknown' };
+  }
+}
+
+/**
+ * `drive:read` の判定（R1 codex1 #10）。
+ *
+ * 0.3.0 で `projects resources` を足したのに doctor は `projects:read` と `slack:read` しか
+ * 見ておらず、**`drive:read` の無い token でも「権限 OK」**と表示していた。doctor を
+ * 通してから新コマンドで 403 になる。
+ *
+ * Drive の GET は案件 slug を要るので、`projects` の 1 件目を借りて叩く。
+ * **flag OFF の 404 と scope 不足の 403 を区別する** —— 404 は「Drive の索引がこの環境で
+ * 有効でない（か、この案件に索引が無い）」であって、権限が無いとは言えない。
+ */
+async function probeDriveScope(api, projectsScope, slug) {
+  if (projectsScope.status !== 'ok') {
+    return { status: 'unknown', label: '不明', why: '（projects:read が未判定）' };
   }
+  if (!slug) {
+    return { status: 'unknown', label: '不明', why: '（読める案件が無いので未実施）' };
+  }
+  const drive = await probeApi(api, `/api/agent/projects/${encodeURIComponent(slug)}/resources`, {
+    limit: 1,
+  });
+  if (drive.status === 200) return { status: 'ok', label: 'あり', why: '' };
+  if (drive.status === 403) return { status: 'forbidden', label: '権限なし', why: '' };
+  if (drive.status === 404) {
+    // **権限なしに丸めない。** Drive の索引が無効な環境でも 404 になる。
+    return { status: 'unknown', label: '不明', why: '（Drive 索引が無効か、この案件に入口が無い）' };
+  }
+  return {
+    status: 'unknown',
+    label: '不明',
+    why: drive.status === null ? '（接続できず）' : `（HTTP ${drive.status}）`,
+  };
 }
 
 /**
@@ -852,10 +963,13 @@ export async function runDoctor({
       const slack = await probeApi(api, '/api/agent/slack/channels', { limit: 1 });
       const projectsScope = scopeVerdict(projects.status);
       const slackScope = scopeVerdict(slack.status);
+      // Drive は案件 slug が要るので、`projects` の 1 件目を借りる（R1 codex1 #10）。
+      const firstSlug = projects.payload?.items?.[0]?.slug ?? null;
+      const driveScope = await probeDriveScope(api, projectsScope, firstSlug);
       // **「不明」を「権限なし」に丸めない**（R1 codex2 Medium 3）。403 を見たときだけ
       // 権限なし、全部 200 のときだけ OK、それ以外は不明。API 障害を権限の問題として
       // 報告すると、直し方の案内が嘘になる。
-      const verdicts = [projectsScope.status, slackScope.status];
+      const verdicts = [projectsScope.status, slackScope.status, driveScope.status];
       const scopeStatus = verdicts.includes('forbidden')
         ? 'forbidden'
         : verdicts.every((value) => value === 'ok')
@@ -868,7 +982,10 @@ export async function runDoctor({
             ? '（接続できず）'
             : `（HTTP ${slack.status}）`
           : '';
-      const detail = `方式 Bearer service token / projects:read=${projectsScope.label} / slack:read=${slackScope.label}${slackWhy}`;
+      const detail =
+        `方式 Bearer service token / projects:read=${projectsScope.label}` +
+        ` / slack:read=${slackScope.label}${slackWhy}` +
+        ` / drive:read=${driveScope.label}${driveScope.why}`;
       results.push(
         check(
           'scope',
@@ -877,9 +994,11 @@ export async function runDoctor({
           detail,
           slackScope.status === 'forbidden'
             ? 'Slack を読む必要があるなら たま に slack:read と対象チャンネルの許可を頼む'
-            : scopeStatus === 'unknown'
-              ? '判定できなかった側は API が復旧してから確かめる'
-              : '',
+            : driveScope.status === 'forbidden'
+              ? 'Drive の索引を読む必要があるなら たま に drive:read と対象入口の許可を頼む'
+              : scopeStatus === 'unknown'
+                ? '判定できなかった側は API が復旧してから確かめる'
+                : '',
         ),
       );
     }
@@ -1003,7 +1122,16 @@ async function checkBun(execFileImpl, platform, fileExists) {
     );
   }
   if (bun.outcome === 'missing') {
-    return check('bun', 'bun', 'missing', 'コマンドが無い', 'curl -fsSL https://bun.sh/install | bash');
+    // **入れただけでは PATH に入らない。** installer は `~/.bun/bin` へ置いて
+    // シェルの rc を書き換えるが、非対話シェルや別の rc を使っていると効かない
+    // ——「入れたのに使えない」がまさに Hermes の踏んだ形なので、続きまで書く。
+    return check(
+      'bun',
+      'bun',
+      'missing',
+      'コマンドが無い',
+      `curl -fsSL https://bun.sh/install | bash で入れ、PATH に ${path.dirname(homeBun)} を足す`,
+    );
   }
   return check('bun', 'bun', 'unknown', `bun --version が exit ${bun.code}`, 'bun の導入を確認する');
 }
@@ -1112,6 +1240,31 @@ const COMMANDS = {
     },
   },
 
+  /**
+   * Drive 入口配下の索引（2026-09-09 の設計 §6）。
+   *
+   * **`--resource-id` は登録済み入口の UUID** で、Drive の fileId や URL ではない。
+   * 全件取得は `continuationQuery` を `projects next` へ渡して利用者が続ける。
+   */
+  'projects resources': {
+    options: ['system', 'resource-id', 'limit', 'cursor'],
+    async run({ api, options, positional, json, stdout }) {
+      const slug = positional[0];
+      if (!slug) throw usageError('案件 slug を指定してください');
+      const response = await api(`/api/agent/projects/${encodeURIComponent(slug)}/resources`, {
+        system: options.system,
+        resourceId: options['resource-id'],
+        limit: options.limit,
+        cursor: options.cursor,
+      });
+      stdout.write(
+        json
+          ? `${JSON.stringify(response, null, 2)}\n`
+          : `${formatDriveResourceLines(response)}\n`,
+      );
+    },
+  },
+
   'slack channels': {
     options: ['project', 'limit', 'cursor'],
     async run({ api, options, json, stdout }) {
@@ -1198,6 +1351,35 @@ const COMMANDS = {
       );
     },
   },
+
+  /**
+   * Drive 索引の続き。**cursor を組み立て直さない**（opaque な暗号文なので手で作れない）。
+   *
+   * `continuationQuery` は query だけで**案件 slug を含まない**（slug は path 側にある）。
+   * cursor から復元することもしない —— cursor は認可の証明ではないので、
+   * 「どの案件を読んでいたか」を cursor に語らせない。だから `--slug` を必須にする。
+   */
+  'projects next': {
+    options: ['slug'],
+    async run({ api, options, positional, json, stdout }) {
+      const query = positional[0];
+      if (!query) {
+        throw usageError('continuationQuery をそのまま渡してください（前回の出力の「次:」行）');
+      }
+      const slug = options.slug;
+      if (!slug) throw usageError('--slug に前回と同じ案件 slug を指定してください');
+      const response = await requestRawQuery(
+        api,
+        `/api/agent/projects/${encodeURIComponent(slug)}/resources`,
+        query,
+      );
+      stdout.write(
+        json
+          ? `${JSON.stringify(response, null, 2)}\n`
+          : `${formatDriveResourceLines(response)}\n`,
+      );
+    },
+  },
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shimatoworks/stw-agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI for the Shimatoworks project-context read API (project registry entries and Slack discussion).",
   "type": "module",
   "license": "UNLICENSED",