@shimatoworks/stw-agent 0.1.0 → 0.2.0

package/README.md

@@ -35,8 +35,28 @@ set -a && source ~/.config/tamai/stw-agent.env && set +a
 stw-agent --help
 ```
 
-動詞は `projects list` / `projects context` / `slack channels` / `slack messages` /
-`slack next` の 5 つ。正確なオプションは常に `--help` を見る（ここに写経しない）。
+動詞は `doctor` / `projects list` / `projects context` / `slack channels` /
+`slack messages` / `slack next` の 6 つ。正確なオプションは常に `--help` を見る
+（ここに写経しない）。
+
+### まず `doctor`
+
+```bash
+stw-agent doctor
+```
+
+token・読み取り API への到達・token の権限・周辺ツール（`ntn` / `gog` / `hub` /
+`gh` / `bun`）の有無と認証を一度に見る。各項目は
+**OK / 未導入 / 未認証 / 権限なし / 到達不可 / 不明** のどれかで、
+要対応には直し方が 1 行付く。`--json` あり。
+
+**`不明` は失敗ではない**（確かめられなかっただけ）。終了コードは
+**要対応があるときだけ 1** になるので、`stw-agent doctor && 次の作業` と繋げられる。
+たとえば `hub` は認証を検証する手立てが無いので、設定があっても `不明` のままになる。
+
+秘密は出さない。**token は値も長さも先頭数文字も出さない**（出すのは env から読んだのか
+設定ファイルから読んだのかだけ）。接続先は origin だけを出し、`STW_API_BASE` に
+資格情報（`user:password@`）が入っていれば**要求を投げる前に断る**。
 
 既定の出力は 1 行要約で、メッセージの本文は先頭だけを出す。
 会社の内部のやり取りが端末のログや transcript へ機械的に積み上がるのを避けるため。
@@ -51,6 +71,16 @@ stw-agent --help
   `stw-manage` の `docs/guides/案件コンテキストの集め方.md`
 - なぜこの形なのか・過去の判断: `stw-manage` の `docs/records/235-agent-read-api.md`
 
+## 変更履歴
+
+- **0.2.0** — `stw-agent doctor` を追加（token・API 到達・権限・周辺ツールの一括確認）。
+  `STW_API_BASE` に資格情報が入っていれば要求前に拒否し、表示は origin だけにする。
+  `slack channels` の既定出力に、サーバが返すようになれば保存範囲（最古〜最新・件数）と
+  到達状態（上限到達／さかのぼり中／読み切り／未走査）・最後の失敗が出る
+- **0.1.1** — `npm i -g` した `stw-agent`（symlink）が無出力で終了する不具合を修正。
+  実体パスでの直接実行は 0.1.0 でも動いていた
+- 0.1.0 — 最初の公開
+
 ## ライセンス
 
 `UNLICENSED`（社内利用）。npm の scope は公開だが、利用許諾を与えるものではない。

package/bin/stw-agent.mjs

@@ -31,10 +31,13 @@
 // 契約が 2 か所に増えて食い違う。**CLI が自分で断るのは「使い方」だけ**
 // （`--project` と `--channel` の排他など、要求を組み立てられない場合）。
 
+import { execFile } from 'node:child_process';
+import { accessSync, realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
 
 /** 接続先の既定。看板の仕様値。別環境は `STW_API_BASE` で上書きする。 */
 export const DEFAULT_API_BASE = 'https://api.shimatoworks.jp';
@@ -55,6 +58,7 @@ export const USAGE = `使い方:
                            [--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 doctor [--json]
 
 環境変数:
   STW_AGENT_TOKEN   読み取り token（必須）。~/.config/tamai/stw-agent.env から自動で読む
@@ -62,6 +66,8 @@ export const USAGE = `使い方:
 
   set -a && source ~/.config/tamai/stw-agent.env && set +a
 
+困ったらまず stw-agent doctor（token・API 到達・ntn / gog / hub / gh / bun をまとめて見る）。
+
 読み方の約束・許可の範囲・エラーの意味は stw-manage の
 docs/guides/案件コンテキストの集め方.md を見る。
 既定の出力は 1 行要約（本文は先頭だけ）。全文が要るときだけ --json を付ける。
@@ -192,7 +198,55 @@ export async function configFromEnv(env, readFileImpl = readFile) {
     );
   }
 
-  return { token, baseUrl: (baseUrl || DEFAULT_API_BASE).replace(/\/+$/, '') };
+  // **接続先を検証してから返す。** token より後に見るのは、doctor が
+  // 「token が無い」と「接続先の設定が壊れている」を取り違えないため。
+  return { token, baseUrl: assertSafeBaseUrl(baseUrl || DEFAULT_API_BASE) };
+}
+
+/**
+ * 接続先 URL の検査。**資格情報入りの URL は要求を投げる前に断る**（R1 codex2 High 1）。
+ *
+ * `https://user:password@host` のような形は、`fetch` が拒否しなくても
+ * エラー経路や診断の表示に丸ごと出てしまう。受け取らないのが一番確実である。
+ * query と hash も接続先には要らないので落とす（値が載っていても運ばない）。
+ */
+export function assertSafeBaseUrl(raw) {
+  const trimmed = String(raw).replace(/\/+$/, '');
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw cliError(
+      'STW_API_BASE が URL として読めません（https://host の形で指定してください）。',
+      'base_url_invalid',
+    );
+  }
+  if (url.username !== '' || url.password !== '') {
+    // **値そのものは出さない。** 「どこが悪いか」だけを言う。
+    throw cliError(
+      'STW_API_BASE に資格情報（user:password@）を含めないでください。' +
+        'token は STW_AGENT_TOKEN で渡します。',
+      'base_url_credentials',
+    );
+  }
+  if (url.protocol !== 'https:' && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {
+    throw cliError('STW_API_BASE は https を使ってください。', 'base_url_insecure');
+  }
+  return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+}
+
+/**
+ * 表示してよい接続先の文字列。**origin だけ**（userinfo / query / hash は出さない）。
+ *
+ * `configFromEnv()` を通っていれば資格情報は入っていないが、表示側でも重ねて絞る
+ * ——「設定を読む経路が増えたときに、表示だけが古い前提のまま残る」を防ぐ。
+ */
+export function safeBaseLabel(baseUrl) {
+  try {
+    return new URL(String(baseUrl)).origin;
+  } catch {
+    return '接続先設定が不正';
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -349,15 +403,83 @@ export function formatProjectLines(response) {
  * （guide §5）。読み手が判断できる最小限として、最終同期の時刻・失敗の有無・
  * さかのぼりの途中かを出す。
  */
-export function formatSyncState(channel) {
+export function formatSyncState(channel, { includeBackfill = true } = {}) {
   if (channel.syncHealth === 'never_synced') return '同期 まだ（未取り込み）';
   const at = channel.lastSyncAt ? formatJst(channel.lastSyncAt) : '不明';
   const failed = channel.syncHealth === 'error' ? '・失敗あり' : '';
   // 古い側を読み切っていない ＝ 過去の発言がまだ揃っていない。
-  const backfill = channel.backfillDone === false ? '・さかのぼり中' : '';
+  // **到達状態を別の列で出すときは重ねない**（`includeBackfill: false`）。
+  const backfill = includeBackfill && channel.backfillDone === false ? '・さかのぼり中' : '';
   return `同期 ${at}${failed}${backfill}`;
 }
 
+/**
+ * 保存済みの範囲（最古〜最新・件数）。
+ *
+ * 値は `channel.coverage`（shared の `SlackSyncCoverage`）から読む。
+ * **サーバがこの塊を返さないうちは何も出さない。** CLI は新しい版でも古い
+ * デプロイ先を相手にするので、無い項目を「0 件」や「不明」と書くと、
+ * 「まだ返していない」と「本当に空」が混ざる。
+ */
+export function formatStoredRange(channel) {
+  const coverage = channel?.coverage;
+  if (!coverage) return '';
+
+  const { oldestStoredAt, newestStoredAt, storedMessageCount, storedThreadCount } = coverage;
+  const count = typeof storedMessageCount === 'number' ? storedMessageCount : null;
+  if (count === 0 || (!oldestStoredAt && !newestStoredAt)) {
+    return count === null ? '保存 なし' : `保存 ${count} 件`;
+  }
+  const from = oldestStoredAt ? formatJst(oldestStoredAt) : '?';
+  const to = newestStoredAt ? formatJst(newestStoredAt) : '?';
+  const messages = count === null ? '' : ` ${count} 件`;
+  // スレッドは「返信のある親の数」。0 のときは黙る（無い方が普通なので）。
+  const threads = typeof storedThreadCount === 'number' && storedThreadCount > 0
+    ? `（スレッド ${storedThreadCount}）`
+    : '';
+  return `保存 ${from}〜${to}${messages}${threads}`;
+}
+
+/**
+ * どこまで遡れたか。
+ *
+ * 「全部読めた」を 1 つの真偽値に畳まない（看板 01M1V8PNF9HE6W288PCE8VJXRE）。
+ * フリープランの上限に当たって**それ以上は取れない**のか、まだ遡っている途中なのか、
+ * そもそも始まっていないのかは別のことである。
+ *
+ * `backfillDone` は `coverage` ではなく**チャンネル直下**（shared の互換フィールド）。
+ */
+export function formatReachState(channel) {
+  const coverage = channel?.coverage;
+  if (!coverage) return '';
+
+  const { backfillTargetReachedAt, backfillStartedAt, scannedThrough } = coverage;
+  if (backfillTargetReachedAt) {
+    // 上限に当たった ＝ これ以上は Slack 側に無い。ここが「読み切った」の意味。
+    return `到達 上限まで（${formatJst(backfillTargetReachedAt)}）`;
+  }
+  if (channel.backfillDone === true) return '到達 読み切り';
+  if (backfillStartedAt || scannedThrough) {
+    const through = scannedThrough ? `（${formatJst(scannedThrough)} まで走査）` : '';
+    return `到達 さかのぼり中${through}`;
+  }
+  // **始まっていないものを「さかのぼり中」と言わない。** 走査の記録が 1 つも無い。
+  return '到達 未走査';
+}
+
+/**
+ * いま抱えている失敗（`coverage.lastFailure`）。
+ *
+ * **code だけを出す。** shared 側が `SLACK_SYNC_FAILURE_CODE_RE` で
+ * `snake_case` の短い token に絞っているので、利用者の値は入らない。
+ */
+export function formatLastFailure(channel) {
+  const failure = channel?.coverage?.lastFailure;
+  if (!failure?.code) return '';
+  const at = failure.at ? `・${formatJst(failure.at)}` : '';
+  return `失敗 ${failure.code}${at}`;
+}
+
 export function formatChannelLines(response) {
   const lines = (response.items ?? []).map((channel) => {
     const projects = channel.projectSlugs?.length ? channel.projectSlugs.join(',') : '-';
@@ -365,7 +487,12 @@ export function formatChannelLines(response) {
     const archived = channel.isArchived ? ' アーカイブ済み' : '';
     // bot が居ないチャンネルは本文が 1 件も取れない。件数 0 の理由を先に言う。
     const member = channel.isMember === false ? ' bot未参加' : '';
-    return `${channel.channelId}  #${channel.name}  案件=${projects}${shared}${archived}${member}  ${formatSyncState(channel)}`;
+    // 保存範囲と到達状態はサーバが返したときだけ足す（古い API でも壊れない）。
+    const reach = formatReachState(channel);
+    const extra = [formatStoredRange(channel), reach, formatLastFailure(channel)].filter(Boolean);
+    const tail = extra.length ? `  ${extra.join('  ')}` : '';
+    const sync = formatSyncState(channel, { includeBackfill: reach === '' });
+    return `${channel.channelId}  #${channel.name}  案件=${projects}${shared}${archived}${member}  ${sync}${tail}`;
   });
   if (lines.length === 0) lines.push('（該当なし）');
   if (response.nextCursor) lines.push(`次: --cursor '${response.nextCursor}'`);
@@ -469,6 +596,486 @@ export function filterProjects(items, q) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// doctor
+// ---------------------------------------------------------------------------
+//
+// 「取得できない」理由が**未導入なのか・未認証なのか・権限が無いのか**を、
+// 個別に確かめなくても一目で分かるようにする（Hermes の指摘・看板
+// 01M1V8PNV2DVZ5EC7JBWE1Z19J）。
+//
+// ## 秘密を出さない
+//
+// token は値も長さも先頭数文字も出さない（先頭 4 文字は「どの token か」の特定に足りる）。
+// 出すのは**どこから読んだか**（env か設定ファイルのパス）だけ。
+// `gog` のアカウントは件数とドメインだけにする —— 「どの account 群で認証しているか」は
+// 診断に要るが、メールアドレスそのものを doctor の出力へ並べる必要は無い。
+//
+// ## 判定できないことを OK にしない
+//
+// token が無ければ API の検査は**実行できない**ので `unknown`（不明）にする。
+// 「未実施」を OK と書くと、doctor を通したのに動かない、が起きる。
+
+/** 表示の語彙。看板の受け入れ条件どおり 6 つに固定する。 */
+export const DOCTOR_LABELS = {
+  ok: 'OK',
+  missing: '未導入',
+  unauthenticated: '未認証',
+  forbidden: '権限なし',
+  unreachable: '到達不可',
+  unknown: '不明',
+};
+
+function check(id, label, status, detail, fix = '') {
+  return { id, label, status, detail, fix };
+}
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * 外部コマンドを 1 本走らせる。
+ *
+ * 返すのは `{ outcome, code, stdout }` だけで、**stderr は返さない**
+ * （認証エラーの本文に token やアカウントが載る CLI があるため）。
+ *
+ * `outcome` を 3 つに分けるのが要点（R1 codex2 Medium 2）。
+ *
+ * - `missing` … `ENOENT`。コマンドが無い
+ * - `exit` … **起動できて、終了コードが返った**。非 0 は「そのコマンドが断った」結果
+ * - `error` … タイムアウトや spawn の失敗。**何も判定できていない**
+ *
+ * これを混ぜていたので、`ETIMEDOUT` に「認証をやり直せ」と案内していた。
+ */
+export async function probeCommand(runner, file, args, timeoutMs = 5000) {
+  try {
+    const { stdout } = await runner(file, args, { timeout: timeoutMs, encoding: 'utf8' });
+    return { outcome: 'exit', code: 0, stdout: String(stdout ?? '') };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { outcome: 'missing', code: null, stdout: '' };
+    // **数値の終了コード ＝ 起動できて、そのコマンドが断った**（認証の判定に使える）。
+    // 文字列（`ETIMEDOUT` など）や killed ＝ 実行できていない（何も判定できていない）。
+    if (typeof error?.code === 'number' && !error?.killed) {
+      return { outcome: 'exit', code: error.code, stdout: String(error?.stdout ?? '') };
+    }
+    return {
+      outcome: 'error',
+      code: error?.killed ? 'ETIMEDOUT' : (error?.code ?? 'unknown'),
+      stdout: '',
+    };
+  }
+}
+
+/**
+ * 「起動できなかった」ときの共通の見せ方。
+ *
+ * **未認証とは言わない。** 判定できていないので `到達不可` にして、
+ * 手で叩いて確かめる道を示す（R1 codex2 Medium 2）。
+ */
+function unverifiedByError(id, label, command, probe) {
+  return check(
+    id,
+    label,
+    'unreachable',
+    `${command} を実行できなかった（${probe.code}）`,
+    `時間をおいて再実行する。続くなら手で ${command} を叩いて確かめる`,
+  );
+}
+
+/** `gog auth list` の出力 → 件数とドメイン（**アドレスそのものは持たない**）。 */
+export function summarizeGogAccounts(stdout) {
+  const emails = String(stdout)
+    .split('\n')
+    .map((line) => line.split('\t')[0]?.trim())
+    .filter((value) => value && value.includes('@'));
+  const domains = [...new Set(emails.map((email) => email.split('@')[1]))];
+  return { count: emails.length, domains };
+}
+
+/** Node のメジャー版。`v22.23.2` → 22。 */
+export function nodeMajor(version) {
+  const match = /^v?(\d+)\./.exec(String(version));
+  return match ? Number(match[1]) : null;
+}
+
+/** 実行環境（ホスト・ユーザー・OS・node）。 */
+function checkEnvironment(env, platform) {
+  const user = env.USER || env.LOGNAME || '不明';
+  return check(
+    'environment',
+    '実行環境',
+    'ok',
+    `${platform.hostname} / ${user} / ${platform.type} ${platform.arch}`,
+  );
+}
+
+function checkNode(version) {
+  const major = nodeMajor(version);
+  if (major === null) return check('node', 'Node', 'unknown', String(version));
+  if (major < 20) {
+    return check(
+      'node',
+      'Node',
+      'missing',
+      `${version}（20 以上が要る）`,
+      'Node 20 以上へ上げる（mise なら mise use -g node@22）',
+    );
+  }
+  return check('node', 'Node', 'ok', String(version));
+}
+
+/**
+ * token の有無と**読み込み元**。値は出さない。
+ *
+ * 「env に入っている」と「設定ファイルから読んだ」を分けるのは、
+ * `source` を忘れているのか配布されていないのかで直し方が違うため。
+ */
+function checkToken(config, envFile) {
+  if (!config) {
+    return check(
+      'token',
+      'STW_AGENT_TOKEN',
+      'missing',
+      `env にも ${envFile} にも無い`,
+      `配布は たま（1Password の stw-manage / PJ開設 service token）。受け取ったら ${envFile} に置く`,
+    );
+  }
+  return check('token', 'STW_AGENT_TOKEN', 'ok', `読み込み元: ${config.source}`);
+}
+
+/** HTTP の結果 → 状態の語彙。 */
+export function statusFromHttp(status) {
+  if (status === 200) return 'ok';
+  if (status === 401) return 'unauthenticated';
+  if (status === 403) return 'forbidden';
+  return 'unreachable';
+}
+
+/** API を 1 本叩いて `{ status, requestId }` を返す（doctor 用。例外にしない）。 */
+async function probeApi(api, requestPath, query) {
+  try {
+    const payload = await api(requestPath, query);
+    return { status: 200, requestId: payload?.requestId ?? null };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return { status: error.status, requestId: error.payload?.requestId ?? null };
+    }
+    return { status: null, requestId: null, transport: error?.message ?? 'unknown' };
+  }
+}
+
+/**
+ * 検査を全部走らせて結果の配列を返す。
+ *
+ * 依存はすべて引数で受ける（テストから execFile と fetch を差し替えるため）。
+ */
+export async function runDoctor({
+  env,
+  readFileImpl = readFile,
+  fetchImpl = globalThis.fetch,
+  sleepImpl = defaultSleep,
+  execFileImpl = execFileAsync,
+  platform = {
+    hostname: os.hostname(),
+    type: os.type(),
+    arch: os.arch(),
+    homedir: os.homedir(),
+    version: process.version,
+  },
+  fileExists = (target) => {
+    try {
+      accessSync(target);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+} = {}) {
+  const results = [];
+  const envFile = env.STW_AGENT_ENV_FILE || defaultEnvFilePath(platform.homedir);
+
+  results.push(checkEnvironment(env, platform));
+  results.push(checkNode(platform.version));
+
+  // token は configFromEnv と**同じ経路**で解決する（doctor だけ別の読み方をしない）。
+  // 失敗の理由は 2 通りあり、直し方が違うので区別する（R1 codex2 High 1）。
+  let config = null;
+  let configError = null;
+  try {
+    const resolved = await configFromEnv(env, readFileImpl);
+    config = {
+      ...resolved,
+      source: env.STW_AGENT_TOKEN?.trim() ? '環境変数 STW_AGENT_TOKEN' : envFile,
+    };
+  } catch (error) {
+    configError = error;
+  }
+
+  // 接続先の設定が悪いだけなら、token は解決できている（`configFromEnv` は
+  // token を先に見る）。**「token が無い」と混同しない。**
+  const baseUrlBroken = configError !== null && configError.code !== 'token_missing';
+  results.push(baseUrlBroken ? check('token', 'STW_AGENT_TOKEN', 'ok', '読み込み済み') : checkToken(config, envFile));
+
+  if (baseUrlBroken) {
+    // **例外 message をそのまま出す。** これは CLI が書いた固定文で、
+    // 設定値そのもの（＝資格情報を含みうる）は入っていない。
+    const skip = 'STW_API_BASE を直してから doctor をやり直す';
+    results.push(check('api', '読み取り API', 'unreachable', configError.message.split('\n')[0], skip));
+    results.push(check('scope', 'token の権限', 'unknown', '接続先が不正なので未実施', skip));
+  } else if (!config) {
+    const skip = 'token を設定してから doctor をやり直す';
+    results.push(check('api', '読み取り API', 'unknown', 'token が無いので未実施', skip));
+    results.push(check('scope', 'token の権限', 'unknown', 'token が無いので未実施', skip));
+  } else {
+    const api = createAgentApi(config, fetchImpl, sleepImpl);
+    const projects = await probeApi(api, '/api/agent/projects', { limit: 1 });
+    // **origin だけを出す。** 設定に userinfo / query が付いていても運ばない。
+    const where = safeBaseLabel(config.baseUrl);
+    if (projects.status === null) {
+      results.push(
+        check('api', '読み取り API', 'unreachable', `${where} へ接続できない`, 'ネットワークと STW_API_BASE を確認する'),
+      );
+      results.push(check('scope', 'token の権限', 'unknown', 'API へ到達できないので未判定'));
+    } else {
+      const apiStatus = statusFromHttp(projects.status);
+      results.push(
+        check(
+          'api',
+          '読み取り API',
+          apiStatus,
+          `HTTP ${projects.status} / requestId ${projects.requestId ?? '-'} / ${where}`,
+          apiStatus === 'ok' ? '' : doctorApiFix(projects.status),
+        ),
+      );
+
+      // scope は**応答から分かる範囲**で見る。200 なら持っている、403 なら無い。
+      // それ以外（401 や到達不可）は「不明」で、持っていないとは言い切らない。
+      const slack = await probeApi(api, '/api/agent/slack/channels', { limit: 1 });
+      const projectsScope = scopeVerdict(projects.status);
+      const slackScope = scopeVerdict(slack.status);
+      // **「不明」を「権限なし」に丸めない**（R1 codex2 Medium 3）。403 を見たときだけ
+      // 権限なし、全部 200 のときだけ OK、それ以外は不明。API 障害を権限の問題として
+      // 報告すると、直し方の案内が嘘になる。
+      const verdicts = [projectsScope.status, slackScope.status];
+      const scopeStatus = verdicts.includes('forbidden')
+        ? 'forbidden'
+        : verdicts.every((value) => value === 'ok')
+          ? 'ok'
+          : 'unknown';
+      // 判定できなかった側は理由まで出す（HTTP か、そもそも届かなかったのか）。
+      const slackWhy =
+        slackScope.status === 'unknown'
+          ? slack.status === null
+            ? '（接続できず）'
+            : `（HTTP ${slack.status}）`
+          : '';
+      const detail = `方式 Bearer service token / projects:read=${projectsScope.label} / slack:read=${slackScope.label}${slackWhy}`;
+      results.push(
+        check(
+          'scope',
+          'token の権限',
+          scopeStatus,
+          detail,
+          slackScope.status === 'forbidden'
+            ? 'Slack を読む必要があるなら たま に slack:read と対象チャンネルの許可を頼む'
+            : scopeStatus === 'unknown'
+              ? '判定できなかった側は API が復旧してから確かめる'
+              : '',
+        ),
+      );
+    }
+  }
+
+  results.push(...(await checkTools(execFileImpl, env, platform, fileExists)));
+  return results;
+}
+
+function doctorApiFix(status) {
+  if (status === 401) return 'token が失効しているか値が違う。たま に再発行を頼む';
+  if (status === 403) return 'token に必要な scope が無い。たま に権限を頼む';
+  if (status === 404) return '読み取り機能が無効か、STW_API_BASE が違う';
+  return 'API 側の状態を確認する（時間をおいて再試行）';
+}
+
+function scopeVerdict(status) {
+  if (status === 200) return { status: 'ok', label: 'あり' };
+  if (status === 403) return { status: 'forbidden', label: '権限なし' };
+  return { status: 'unknown', label: '不明' };
+}
+
+/** 周辺ツール（ntn / gog / hub / gh / bun）。 */
+async function checkTools(execFileImpl, env, platform, fileExists) {
+  const results = [];
+
+  const ntn = await probeCommand(execFileImpl, 'ntn', ['doctor']);
+  if (ntn.outcome === 'missing') {
+    results.push(
+      check('ntn', 'ntn（Notion CLI）', 'missing', 'コマンドが無い', 'npm i -g @notionhq/ntn か、Notion コネクタを使う'),
+    );
+  } else if (ntn.outcome === 'error') {
+    results.push(unverifiedByError('ntn', 'ntn（Notion CLI）', 'ntn doctor', ntn));
+  } else {
+    results.push(
+      ntn.code === 0
+        ? check('ntn', 'ntn（Notion CLI）', 'ok', 'ntn doctor 正常')
+        : check('ntn', 'ntn（Notion CLI）', 'unauthenticated', `ntn doctor が exit ${ntn.code}`, 'ntn の認証をやり直す（ntn doctor の指示に従う）'),
+    );
+  }
+
+  const gog = await probeCommand(execFileImpl, 'gog', ['auth', 'list']);
+  if (gog.outcome === 'missing') {
+    results.push(check('gog', 'gog（Google CLI）', 'missing', 'コマンドが無い', 'gog を入れる（brew install gog）'));
+  } else if (gog.outcome === 'error') {
+    results.push(unverifiedByError('gog', 'gog（Google CLI）', 'gog auth list', gog));
+  } else if (gog.code !== 0) {
+    results.push(check('gog', 'gog（Google CLI）', 'unauthenticated', `gog auth list が exit ${gog.code}`, 'gog auth login でアカウントを足す'));
+  } else {
+    const { count, domains } = summarizeGogAccounts(gog.stdout);
+    // **列挙できた ＝ 資格情報が保存されている**、まで。いま使えるかは確かめていない
+    // （R1 codex2 Medium 2）。断定しない言い方にする。
+    results.push(
+      count === 0
+        ? check('gog', 'gog（Google CLI）', 'unauthenticated', 'アカウントが 1 件も無い', 'gog auth login でアカウントを足す')
+        : check('gog', 'gog（Google CLI）', 'ok', `登録 ${count} 件（${domains.join(', ')}）／有効性は未検証`),
+    );
+  }
+
+  // **hub は `--version` を持たない**（未対応サブコマンドでも exit 0 になる）ので、
+  // 終了コードで認証を判定できない。かといって**env の存在だけで「認証済み」とも
+  // 言わない**（secret 欠落・失効・API 未到達を何も見ていない。R1 codex2 Medium 2）。
+  // 設定の有無だけを事実として出し、状態は「未検証」にする。
+  const hub = await probeCommand(execFileImpl, 'hub', []);
+  if (hub.outcome === 'missing') {
+    results.push(check('hub', 'hub（看板 CLI）', 'missing', 'コマンドが無い', 'hub を入れる（tools/hub.mjs か配布物）'));
+  } else if (hub.outcome === 'error') {
+    results.push(unverifiedByError('hub', 'hub（看板 CLI）', 'hub', hub));
+  } else {
+    const hubEnv = path.join(platform.homedir, '.config', 'tamai', 'hub-tasks.env');
+    const verify = 'hub task list --project stw-manage で実際に確認する';
+    if (env.TASKS_CLIENT_ID) {
+      results.push(check('hub', 'hub（看板 CLI）', 'unknown', '認証 env 読込済み・認証未検証', verify));
+    } else if (fileExists(hubEnv)) {
+      results.push(
+        check('hub', 'hub（看板 CLI）', 'unknown', `認証 env あり・未読込（${hubEnv}）`, `set -a && source ${hubEnv} && set +a`),
+      );
+    } else {
+      results.push(check('hub', 'hub（看板 CLI）', 'unauthenticated', '認証設定が見当たらない', `set -a && source ${hubEnv} && set +a`));
+    }
+  }
+
+  const gh = await probeCommand(execFileImpl, 'gh', ['auth', 'status']);
+  if (gh.outcome === 'missing') {
+    results.push(check('gh', 'gh（GitHub CLI）', 'missing', 'コマンドが無い', 'brew install gh'));
+  } else if (gh.outcome === 'error') {
+    results.push(unverifiedByError('gh', 'gh（GitHub CLI）', 'gh auth status', gh));
+  } else {
+    results.push(
+      gh.code === 0
+        ? check('gh', 'gh（GitHub CLI）', 'ok', '認証済み')
+        : check('gh', 'gh（GitHub CLI）', 'unauthenticated', `gh auth status が exit ${gh.code}`, 'gh auth login'),
+    );
+  }
+
+  results.push(await checkBun(execFileImpl, platform, fileExists));
+  return results;
+}
+
+/**
+ * bun の有無と PATH。
+ *
+ * **「入っているのに PATH に無い」を「未導入」と混同しない**（Hermes が踏んだ事故。
+ * `~/.bun/bin` が PATH に無く、bun があるのに使えなかった）。
+ */
+async function checkBun(execFileImpl, platform, fileExists) {
+  const bun = await probeCommand(execFileImpl, 'bun', ['--version']);
+  if (bun.outcome === 'exit' && bun.code === 0) {
+    return check('bun', 'bun', 'ok', `v${bun.stdout.trim()}`);
+  }
+  if (bun.outcome === 'error') return unverifiedByError('bun', 'bun', 'bun --version', bun);
+
+  const homeBun = path.join(platform.homedir, '.bun', 'bin', 'bun');
+  if (fileExists(homeBun)) {
+    return check(
+      'bun',
+      'bun',
+      'missing',
+      `${homeBun} はあるが PATH から呼べない`,
+      `PATH に ${path.dirname(homeBun)} を足す（シェルの rc に export PATH="$HOME/.bun/bin:$PATH"）`,
+    );
+  }
+  if (bun.outcome === 'missing') {
+    return check('bun', 'bun', 'missing', 'コマンドが無い', 'curl -fsSL https://bun.sh/install | bash');
+  }
+  return check('bun', 'bun', 'unknown', `bun --version が exit ${bun.code}`, 'bun の導入を確認する');
+}
+
+/**
+ * 端末での表示幅。**全角を 2 で数える**（日本語のラベルが混ざるので、
+ * `String.length` で桁を揃えると列がずれる）。
+ */
+export function displayWidth(text) {
+  let width = 0;
+  for (const char of String(text)) {
+    const code = char.codePointAt(0);
+    // CJK・かな・全角記号のざっくり判定。厳密な East Asian Width 表は持ち込まない。
+    const wide =
+      (code >= 0x1100 && code <= 0x115f) ||
+      (code >= 0x2e80 && code <= 0xa4cf) ||
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe30 && code <= 0xfe6f) ||
+      (code >= 0xff00 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6);
+    width += wide ? 2 : 1;
+  }
+  return width;
+}
+
+function padDisplay(text, width) {
+  return `${text}${' '.repeat(Math.max(0, width - displayWidth(text)))}`;
+}
+
+/**
+ * 人が読む表。**1 項目 1 行 ＋（要対応なら）直し方 1 行**。
+ *
+ * 先頭の列は状態そのもの（OK / 未導入 / 未認証 / 権限なし / 到達不可 / 不明）にして、
+ * 目で追う対象を 1 つにする。
+ */
+export function formatDoctorLines(results) {
+  const statusWidth = Math.max(...results.map((item) => displayWidth(DOCTOR_LABELS[item.status] ?? item.status)));
+  const labelWidth = Math.max(...results.map((item) => displayWidth(item.label)));
+  const lines = [];
+  for (const item of results) {
+    const status = DOCTOR_LABELS[item.status] ?? item.status;
+    lines.push(`${padDisplay(status, statusWidth)}  ${padDisplay(item.label, labelWidth)}  ${item.detail}`);
+    if (item.fix) lines.push(`${' '.repeat(statusWidth + 2)}${padDisplay('', labelWidth)}  → ${item.fix}`);
+  }
+  const { blocking, unverified } = splitDoctorResults(results);
+  lines.push('');
+  if (blocking.length > 0) {
+    lines.push(`要対応 ${blocking.length} 件: ${blocking.map((item) => item.label).join(' / ')}`);
+  }
+  if (unverified.length > 0) {
+    lines.push(`未検証 ${unverified.length} 件: ${unverified.map((item) => item.label).join(' / ')}`);
+  }
+  if (blocking.length === 0 && unverified.length === 0) lines.push('すべて OK。');
+  return lines.join('\n');
+}
+
+/**
+ * 「直すべきもの」と「確かめられなかったもの」を分ける。
+ *
+ * **`unknown` は失敗ではない。** 判定できなかっただけなので、終了コードにも
+ * 「要対応」の数にも入れない —— これを混ぜると、正常な機械でも doctor が常に
+ * 非 0 になり、`stw-agent doctor && 次の作業` が使えなくなる（R1 codex2 Medium 2 で
+ * hub を「未検証」にした結果、この区別が要るようになった）。
+ */
+export function splitDoctorResults(results) {
+  return {
+    blocking: results.filter((item) => item.status !== 'ok' && item.status !== 'unknown'),
+    unverified: results.filter((item) => item.status === 'unknown'),
+  };
+}
+
 const COMMANDS = {
   'projects list': {
     options: ['q', 'limit', 'cursor'],
@@ -549,6 +1156,35 @@ const COMMANDS = {
    * **cursor を組み立て直さない。** cursor は版・route・並び順・query hash を含む
    * 不透明な値で、手で作ると `400 invalid_cursor` になる（guide §3）。
    */
+  /**
+   * 周辺ツールと認証・閲覧可否の一括確認。
+   *
+   * **token が無くても動く唯一のコマンド。** 「token が無い」こと自体を
+   * 報告するのが仕事なので、`configFromEnv` の例外で止めない（`needsToken: false`）。
+   */
+  doctor: {
+    options: [],
+    needsToken: false,
+    async run({ json, stdout, dependencies }) {
+      const results = await runDoctor({
+        env: dependencies.env,
+        readFileImpl: dependencies.readFileImpl,
+        fetchImpl: dependencies.fetchImpl,
+        sleepImpl: dependencies.sleepImpl,
+        execFileImpl: dependencies.execFileImpl,
+      });
+      stdout.write(
+        json
+          ? `${JSON.stringify({ checks: results }, null, 2)}\n`
+          : `${formatDoctorLines(results)}\n`,
+      );
+      // **要対応があれば非 0 で終わる**（`brew doctor` / `npm doctor` と同じ流儀）。
+      // `stw-agent doctor && 次の作業` と繋げられるようにするため。
+      // **「不明」は数えない**（確かめられなかっただけで、壊れてはいない）。
+      return splitDoctorResults(results).blocking.length > 0 ? 1 : 0;
+    },
+  },
+
   'slack next': {
     options: [],
     async run({ api, positional, json, stdout }) {
@@ -592,25 +1228,40 @@ async function execute(argv, dependencies) {
     group === '-h'
   ) {
     dependencies.stdout.write(USAGE);
-    return;
+    return 0;
   }
 
-  const name = `${group} ${verb ?? ''}`.trim();
-  const command = COMMANDS[name];
+  // **1 語のコマンド（`doctor`）を先に見る。** `${group} ${verb}` だけで引くと、
+  // `doctor --json` の `--json` が動詞として繋がって「未対応」になる。
+  const single = COMMANDS[group];
+  const name = single ? group : `${group} ${verb ?? ''}`.trim();
+  const command = single ?? COMMANDS[name];
   if (!command) throw usageError(`未対応のサブコマンドです: ${name}`);
 
-  const { options, positional, json } = parseArgs(rest, command.options);
-  const config = await configFromEnv(dependencies.env, dependencies.readFileImpl);
-  const api = createAgentApi(config, dependencies.fetchImpl, dependencies.sleepImpl);
-
-  await command.run({
-    api,
-    options,
-    positional,
-    json,
-    stdout: dependencies.stdout,
-    stderr: dependencies.stderr,
-  });
+  const args = single ? [verb, ...rest].filter((value) => value !== undefined) : rest;
+  const { options, positional, json } = parseArgs(args, command.options);
+  // **doctor だけは token を要らない**（無いことを報告するのが仕事）。
+  const api =
+    command.needsToken === false
+      ? null
+      : createAgentApi(
+          await configFromEnv(dependencies.env, dependencies.readFileImpl),
+          dependencies.fetchImpl,
+          dependencies.sleepImpl,
+        );
+
+  // コマンドが終了コードを返したらそれを使う（既定は 0）。
+  return (
+    (await command.run({
+      api,
+      options,
+      positional,
+      json,
+      stdout: dependencies.stdout,
+      stderr: dependencies.stderr,
+      dependencies,
+    })) ?? 0
+  );
 }
 
 export async function runCli(argv, overrides = {}) {
@@ -619,19 +1270,54 @@ export async function runCli(argv, overrides = {}) {
     fetchImpl: overrides.fetchImpl ?? globalThis.fetch,
     readFileImpl: overrides.readFileImpl ?? readFile,
     sleepImpl: overrides.sleepImpl ?? defaultSleep,
+    execFileImpl: overrides.execFileImpl ?? execFileAsync,
     stdout: overrides.stdout ?? process.stdout,
     stderr: overrides.stderr ?? process.stderr,
   };
 
   try {
-    await execute(argv, dependencies);
-    return 0;
+    return await execute(argv, dependencies);
   } catch (error) {
     dependencies.stderr.write(`${formatFailure(error)}\n`);
     return 1;
   }
 }
 
-const isDirectExecution =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectExecution) process.exitCode = await runCli(process.argv.slice(2));
+/**
+ * この実行が「CLI として直接呼ばれた」ものか（ライブラリとして import されたのではなく）。
+ *
+ * ## symlink 経由で無出力になっていた（0.1.0 の不具合）
+ *
+ * `npm i -g` が作る `~/.npm-global/bin/stw-agent` は
+ * `../lib/node_modules/@shimatoworks/stw-agent/bin/stw-agent.mjs` への **symlink** である。
+ * このとき Node が渡す値は 2 つで食い違う。
+ *
+ * ```text
+ * process.argv[1]   /Users/x/.npm-global/bin/stw-agent          ← 呼ばれた名前（symlink）
+ * import.meta.url   file:///Users/x/.npm-global/lib/…/bin/stw-agent.mjs  ← 実体
+ * ```
+ *
+ * Node は既定でモジュールの**実体パス**で `import.meta.url` を作るので、
+ * `argv[1]` をそのまま URL 化して比べると一致しない。判定が false になり、
+ * **何も実行せず exit 0**（無出力）になっていた。
+ *
+ * symlink は bin 自体だけでなく**途中のディレクトリ**にもある（macOS の `/tmp` は
+ * `/private/tmp` への symlink）。だから「realpath に直してから比べる」で両方に効く。
+ *
+ * `--preserve-symlinks-main` を付けて起動した場合は逆に `import.meta.url` が
+ * symlink 側になるので、**素の比較も残して両方を許す**。
+ */
+export function isDirectExecution(argv1, moduleUrl) {
+  if (!argv1) return false;
+  if (pathToFileURL(argv1).href === moduleUrl) return true;
+  try {
+    return pathToFileURL(realpathSync(argv1)).href === moduleUrl;
+  } catch {
+    // argv[1] が実在しない（`node --eval` など）。**ここで落とさない。**
+    return false;
+  }
+}
+
+if (isDirectExecution(process.argv[1], import.meta.url)) {
+  process.exitCode = await runCli(process.argv.slice(2));
+}

package/package.json

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