@shimatoworks/stw-agent 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @shimatoworks/stw-agent
+
+CLI for the Shimatoworks project-context read API. It fetches a project's registry
+entries (Notion / Drive / Slack / repo) and the Slack discussion attached to them, so an
+agent or a person can get the background of a project in one command instead of
+assembling `curl` calls by hand. It has no dependencies and needs a read token issued by
+Shimatoworks; without one it does nothing. The API contract, the permission model and the
+error semantics live in the `stw-manage` repository, not here.
+
+## インストール
+
+```bash
+npm i -g @shimatoworks/stw-agent
+```
+
+`stw-agent` コマンドが PATH に入る。Node 20 以上が要る。
+
+## token
+
+読み取り token（`STW_AGENT_TOKEN`）が要る。**発行と配布は たま**が行う。
+自分で作らない。無ければ人に頼む。
+
+```bash
+set -a && source ~/.config/tamai/stw-agent.env && set +a
+```
+
+`~/.config/tamai/stw-agent.env` に置いてあれば CLI が自動で読むので、
+上の `source` は毎回は要らない。接続先を変えるときだけ `STW_API_BASE` を指定する。
+
+**token は CLI のどの出力にも出ない**（stdout / stderr / エラー文のいずれにも）。
+
+## 使い方
+
+```bash
+stw-agent --help
+```
+
+動詞は `projects list` / `projects context` / `slack channels` / `slack messages` /
+`slack next` の 5 つ。正確なオプションは常に `--help` を見る（ここに写経しない）。
+
+既定の出力は 1 行要約で、メッセージの本文は先頭だけを出す。
+会社の内部のやり取りが端末のログや transcript へ機械的に積み上がるのを避けるため。
+**全文が要るときだけ `--json`** を付ける。
+
+## 契約と権限
+
+読める範囲（案件との紐付き・`visibility`・チャンネルの種別）はサーバ側の SQL が決める。
+期間や検索語の妥当性もサーバが判定する。CLI は要求を組み立てて表示するだけである。
+
+- 契約・権限・エラーの意味・読むときの約束:
+  `stw-manage` の `docs/guides/案件コンテキストの集め方.md`
+- なぜこの形なのか・過去の判断: `stw-manage` の `docs/records/235-agent-read-api.md`
+
+## ライセンス
+
+`UNLICENSED`（社内利用）。npm の scope は公開だが、利用許諾を与えるものではない。

package/bin/stw-agent.mjs

@@ -0,0 +1,637 @@
+#!/usr/bin/env node
+
+// stw-agent — AI 向け読み取り API の CLI（看板 01M1V38MP4XBB5JJ866869KQ81）。
+//
+// **CLI が唯一の実装**（hub の `tools/hub.mjs` と同じ流儀）。skill や MCP を足す場合も
+// ここを呼ぶだけの薄いラッパにし、ロジックを二重に持たない。
+//
+//   stw-agent projects list [--q <text>] [--limit <n>] [--cursor <c>] [--json]
+//   stw-agent projects context <slug> [--include-slack <true|false>] [--from --to --q --limit] [--json]
+//   stw-agent slack channels [--project <slug>] [--limit <n>] [--cursor <c>] [--json]
+//   stw-agent slack messages (--project <slug> | --channel <id>) [--from --to --q --limit --thread <ts>] [--cursor <c>] [--json]
+//   stw-agent slack next <continuationQuery> [--json]
+//
+// ## 何を出すか
+//
+// 既定は**人と AI が読める 1 行形式**で、メッセージは「時刻・投稿者・本文の先頭・sourceUrl」。
+// 本文を丸ごと出さないのは、会社の内部のやり取りが端末のログや transcript へ機械的に
+// 積み上がるのを避けるため（guide §4「読むときの約束」）。**全文が要るときは `--json`** で、
+// そのとき初めて本文がそのまま出る。
+//
+// ## 出してはいけないもの
+//
+// - **token はどこにも出さない**（stdout / stderr / エラーメッセージ / URL の再掲）
+// - **cursor は stdout にだけ出す。** 次のページを取るには値を渡すしかないので隠せないが、
+//   エラー経路（stderr）には URL ごと出さない。cursor は手で作らず、返ってきた値を渡す
+//
+// ## 契約はサーバが持つ
+//
+// 期間の妥当性・`q` の長さ・`threadTs` の組み合わせなどはサーバの zod が判定する
+// （`packages/shared/src/schemas/agent-read.ts`）。CLI 側で先回りして検証すると、
+// 契約が 2 か所に増えて食い違う。**CLI が自分で断るのは「使い方」だけ**
+// （`--project` と `--channel` の排他など、要求を組み立てられない場合）。
+
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** 接続先の既定。看板の仕様値。別環境は `STW_API_BASE` で上書きする。 */
+export const DEFAULT_API_BASE = 'https://api.shimatoworks.jp';
+
+/** 429 を受けたときに待つ上限（秒）。これを超える `Retry-After` は待たずに諦める。 */
+const MAX_RETRY_AFTER_SECONDS = 60;
+
+/** テキスト表示で出す本文の長さ。全文は `--json`。 */
+const TEXT_PREVIEW_CHARS = 120;
+
+export const USAGE = `使い方:
+  stw-agent projects list [--q <text>] [--limit <n>] [--cursor <c>] [--json]
+  stw-agent projects context <slug> [--include-slack <true|false>]
+                                    [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>]
+                                    [--q <text>] [--limit <n>] [--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_TOKEN   読み取り token（必須）。~/.config/tamai/stw-agent.env から自動で読む
+  STW_API_BASE      接続先（既定 ${DEFAULT_API_BASE}）
+
+  set -a && source ~/.config/tamai/stw-agent.env && set +a
+
+読み方の約束・許可の範囲・エラーの意味は stw-manage の
+docs/guides/案件コンテキストの集め方.md を見る。
+既定の出力は 1 行要約（本文は先頭だけ）。全文が要るときだけ --json を付ける。
+期間を省略すると当日を含む直近 30 日。続きは continuationQuery を slack next へそのまま渡す。
+`;
+
+// ---------------------------------------------------------------------------
+// 引数
+// ---------------------------------------------------------------------------
+
+export function cliError(message, code = 'cli_error') {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function usageError(message) {
+  return cliError(`${message}\n\n${USAGE.trimEnd()}`, 'usage_error');
+}
+
+/**
+ * `--name value` / `--name=value` / `--json` を解釈する。
+ *
+ * `--` の後ろはすべて位置引数（`--` で始まる slug や検索語を渡せるようにする）。
+ * 知らないオプションは**黙って捨てずに落とす** —— 綴り違いが「絞ったつもりで全件」になる。
+ */
+export function parseArgs(args, allowed = []) {
+  const options = {};
+  const positional = [];
+  let json = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === '--') {
+      positional.push(...args.slice(index + 1));
+      break;
+    }
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+
+    const at = token.indexOf('=');
+    const name = at === -1 ? token.slice(2) : token.slice(2, at);
+    const inline = at === -1 ? undefined : token.slice(at + 1);
+
+    if (name === 'json') {
+      if (inline !== undefined) throw usageError('--json は値を取りません');
+      json = true;
+      continue;
+    }
+    if (!allowed.includes(name)) throw usageError(`未対応のオプションです: --${name}`);
+
+    let value = inline;
+    if (value === undefined) {
+      value = args[index + 1];
+      if (value === undefined || value.startsWith('--')) {
+        // `--q --json` のような取り違えを黙って通さない（`--q=--foo` の形なら渡せる）。
+        throw usageError(`--${name} には値が必要です`);
+      }
+      index += 1;
+    }
+    options[name] = value;
+  }
+
+  return { options, positional, json };
+}
+
+/** `--include-slack` のような真偽値。`true` / `false` 以外は落とす。 */
+export function parseBooleanOption(name, value) {
+  if (value === undefined) return undefined;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw usageError(`--${name} は true か false で指定してください`);
+}
+
+// ---------------------------------------------------------------------------
+// 設定
+// ---------------------------------------------------------------------------
+
+export function defaultEnvFilePath(homedir = os.homedir()) {
+  return path.join(homedir, '.config', 'tamai', 'stw-agent.env');
+}
+
+/** `KEY=value`（`export` 付き・引用符・行末コメントに耐える）。hub の env 読みと同じ形。 */
+export function parseEnvFile(text) {
+  const values = {};
+  for (const rawLine of String(text).split('\n')) {
+    const line = rawLine.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!match) continue;
+    const raw = match[2].trim();
+    const quoted = /^(['"])([\s\S]*)\1\s*(?:#.*)?$/.exec(raw);
+    values[match[1]] = quoted === null ? raw.replace(/\s+#.*$/, '').trim() : quoted[2];
+  }
+  return values;
+}
+
+/**
+ * token と接続先を決める。env が優先で、無ければ設定ファイルを読む。
+ *
+ * **token が無ければここで止める。** 未設定のまま叩くと 401 が返るだけで、
+ * 「配布されていない」のか「読み込み忘れ」なのかが分からない。
+ */
+export async function configFromEnv(env, readFileImpl = readFile) {
+  let token = env.STW_AGENT_TOKEN?.trim();
+  let baseUrl = env.STW_API_BASE?.trim();
+
+  const envFile = env.STW_AGENT_ENV_FILE || defaultEnvFilePath();
+  if (!token) {
+    try {
+      const fromFile = parseEnvFile(await readFileImpl(envFile, 'utf8'));
+      token ||= fromFile.STW_AGENT_TOKEN?.trim();
+      baseUrl ||= fromFile.STW_API_BASE?.trim();
+    } catch {
+      // 読めない場合は下の未設定エラーで期待パスを案内する。
+    }
+  }
+
+  if (!token) {
+    throw cliError(
+      'STW_AGENT_TOKEN を設定してください。\n' +
+        `認証ファイル ${envFile} があれば自動で読み込みます。\n` +
+        '手動で設定する場合: set -a && source ~/.config/tamai/stw-agent.env && set +a\n' +
+        'token の配布は たま（1Password の stw-manage / PJ開設 service token）。',
+      'token_missing',
+    );
+  }
+
+  return { token, baseUrl: (baseUrl || DEFAULT_API_BASE).replace(/\/+$/, '') };
+}
+
+// ---------------------------------------------------------------------------
+// API
+// ---------------------------------------------------------------------------
+
+export class ApiError extends Error {
+  constructor(status, payload, requestPath) {
+    super(`agent API returned ${status}`);
+    this.status = status;
+    this.payload = payload;
+    // **query は持たない**（cursor が stderr へ出る経路を作らない）。
+    this.requestPath = requestPath;
+  }
+}
+
+/** `Retry-After`（秒 or HTTP date）をミリ秒へ。読めない・長すぎるなら `null`。 */
+export function retryAfterMs(header, nowMs = Date.now()) {
+  if (typeof header !== 'string' || header.trim() === '') return null;
+  const seconds = Number(header.trim());
+  if (Number.isFinite(seconds)) {
+    if (seconds < 0 || seconds > MAX_RETRY_AFTER_SECONDS) return null;
+    return Math.ceil(seconds * 1000);
+  }
+  const at = Date.parse(header);
+  if (Number.isNaN(at)) return null;
+  const waitMs = at - nowMs;
+  if (waitMs <= 0) return 0;
+  if (waitMs > MAX_RETRY_AFTER_SECONDS * 1000) return null;
+  return waitMs;
+}
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * GET を 1 本投げる。
+ *
+ * **429 は `Retry-After` を尊重して 1 回だけ待って再試行する。** 枠は token ごとに
+ * 60 回/分・1,000 回/時で、複数のワーカーが同じ token を共有する（guide §2）。
+ * 何度も粘ると相手の枠を食うだけなので、1 回で駄目なら人へ返す。
+ */
+export function createAgentApi(config, fetchImpl = globalThis.fetch, sleepImpl = defaultSleep) {
+  return async function request(requestPath, query = {}) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== '') search.set(key, String(value));
+    }
+    const suffix = search.toString();
+    const url = `${config.baseUrl}${requestPath}${suffix ? `?${suffix}` : ''}`;
+
+    const send = () =>
+      fetchImpl(url, {
+        method: 'GET',
+        headers: {
+          // token はここだけに載せる。ログにも例外にも持ち出さない。
+          authorization: `Bearer ${config.token}`,
+          accept: 'application/json',
+        },
+      });
+
+    let response = await send();
+    if (response.status === 429) {
+      const waitMs = retryAfterMs(response.headers?.get?.('retry-after'));
+      if (waitMs !== null) {
+        await sleepImpl(waitMs);
+        response = await send();
+      }
+    }
+
+    const text = await response.text();
+    let payload = null;
+    if (text !== '') {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        throw cliError(`API から JSON ではない応答を受信しました (${response.status})`);
+      }
+    }
+    // **query を落としてから**エラーへ載せる（cursor が stderr へ出る経路を作らない）。
+    if (!response.ok) throw new ApiError(response.status, payload, requestPath.split('?')[0]);
+    return payload;
+  };
+}
+
+/** 人が読む 1 行 + 手がかり。**token も cursor も入れない**。 */
+export function formatFailure(error) {
+  if (!(error instanceof ApiError)) {
+    return `error: ${error instanceof Error ? error.message : String(error)}`;
+  }
+  const code = typeof error.payload?.code === 'string' ? error.payload.code : 'unknown';
+  const message =
+    typeof error.payload?.error === 'string' && error.payload.error !== ''
+      ? error.payload.error
+      : `agent API returned ${error.status}`;
+  const requestId = typeof error.payload?.requestId === 'string' ? error.payload.requestId : '-';
+
+  const lines = [
+    `error: ${message}`,
+    `  HTTP ${error.status} ${code} / requestId ${requestId} / ${error.requestPath}`,
+  ];
+  if (error.status === 401) {
+    lines.push('  token が無効か失効しています（STW_AGENT_TOKEN）。配布は たま。');
+  }
+  if (error.status === 403) {
+    lines.push('  token に scope がありません（projects:read / slack:read）。');
+  }
+  if (error.status === 404) {
+    lines.push('  対象が無いか、この token の許可範囲外です。403 との違いは guide §3 を見る。');
+  }
+  if (error.status === 429) {
+    lines.push('  枠（60 回/分・1,000 回/時）を超えました。token は他のワーカーと共有です。');
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// 表示
+// ---------------------------------------------------------------------------
+
+/** 改行と連続空白を潰して 1 行にし、長ければ切る。**全文は `--json`**。 */
+export function previewText(text, limit = TEXT_PREVIEW_CHARS) {
+  const flat = String(text ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (flat.length <= limit) return flat;
+  return `${flat.slice(0, limit)}…`;
+}
+
+/** ISO 8601 → JST の `MM/DD HH:MM`。並べたときに縦が揃う長さにする。 */
+export function formatJst(iso) {
+  const at = Date.parse(iso ?? '');
+  if (Number.isNaN(at)) return '----/-- --:--';
+  const jst = new Date(at + 9 * 60 * 60 * 1000);
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${pad(jst.getUTCMonth() + 1)}/${pad(jst.getUTCDate())} ${pad(jst.getUTCHours())}:${pad(jst.getUTCMinutes())}`;
+}
+
+export function formatProjectLines(response) {
+  const lines = (response.items ?? []).map((project) => {
+    const parent = project.parentSlug ? ` 親=${project.parentSlug}` : '';
+    const aliases = project.aliases?.length ? ` 別名=${project.aliases.join(',')}` : '';
+    return `${project.slug}  ${project.displayName}  [${project.lifecycle}/${project.kind}]  入口${project.resourceCount}件${parent}${aliases}`;
+  });
+  if (lines.length === 0) lines.push('（該当なし）');
+  if (response.nextCursor) lines.push(`次: --cursor '${response.nextCursor}'`);
+  return lines.join('\n');
+}
+
+/**
+ * 取り込みの状態を短く 1 語で。
+ *
+ * **既定の出力に必ず入れる。** これが無いと「空だった」と「読めていない」を画面から
+ * 区別できず、同期の止まったチャンネルを「議論が無かった」と読んでしまう
+ * （guide §5）。読み手が判断できる最小限として、最終同期の時刻・失敗の有無・
+ * さかのぼりの途中かを出す。
+ */
+export function formatSyncState(channel) {
+  if (channel.syncHealth === 'never_synced') return '同期 まだ（未取り込み）';
+  const at = channel.lastSyncAt ? formatJst(channel.lastSyncAt) : '不明';
+  const failed = channel.syncHealth === 'error' ? '・失敗あり' : '';
+  // 古い側を読み切っていない ＝ 過去の発言がまだ揃っていない。
+  const backfill = channel.backfillDone === false ? '・さかのぼり中' : '';
+  return `同期 ${at}${failed}${backfill}`;
+}
+
+export function formatChannelLines(response) {
+  const lines = (response.items ?? []).map((channel) => {
+    const projects = channel.projectSlugs?.length ? channel.projectSlugs.join(',') : '-';
+    const shared = channel.sharedChannel ? ' 共有' : '';
+    const archived = channel.isArchived ? ' アーカイブ済み' : '';
+    // bot が居ないチャンネルは本文が 1 件も取れない。件数 0 の理由を先に言う。
+    const member = channel.isMember === false ? ' bot未参加' : '';
+    return `${channel.channelId}  #${channel.name}  案件=${projects}${shared}${archived}${member}  ${formatSyncState(channel)}`;
+  });
+  if (lines.length === 0) lines.push('（該当なし）');
+  if (response.nextCursor) lines.push(`次: --cursor '${response.nextCursor}'`);
+  return lines.join('\n');
+}
+
+/**
+ * メッセージ 1 件 1 行。**本文は先頭だけ**（全文は `--json`）。
+ *
+ * `sourceUrl` を必ず添えるのは、guide §4 が「各判断に URL を付ける」を求めているため。
+ * 生成できていない（`sourceUrlKind: 'unavailable'`）ときは `-` を出して、
+ * **出典を書けないことを黙らせない**。
+ */
+export function formatMessageLines(response, { showChannel = true } = {}) {
+  const lines = [];
+  const effective = response.effectiveQuery;
+  if (effective) {
+    lines.push(`期間 ${effective.from}〜${effective.to}${effective.q ? ` / q=${effective.q}` : ''}`);
+  }
+  const thread = response.thread;
+  if (thread) {
+    lines.push(`スレッド ${thread.rootTs}（親: ${thread.parentState}）`);
+  }
+
+  for (const item of response.items ?? []) {
+    const where = showChannel ? `#${item.channelName} ` : '';
+    const reply = item.thread?.isReply ? '↳' : ' ';
+    const source = item.sourceUrl ?? '-';
+    lines.push(
+      `${formatJst(item.postedAt)} ${reply}${where}${item.author?.displayName ?? '不明'}: ${previewText(item.text)}  ${source}`,
+    );
+  }
+  if ((response.items ?? []).length === 0) lines.push('（該当なし）');
+
+  if (response.continuationQuery) {
+    lines.push(`次: stw-agent slack next '${response.continuationQuery}'`);
+  } else if (response.nextCursor) {
+    lines.push(`次: --cursor '${response.nextCursor}'`);
+  }
+  return lines.join('\n');
+}
+
+export function formatContextLines(response) {
+  const project = response.project;
+  const lines = [
+    `${project.slug}  ${project.displayName}  [${project.lifecycle}/${project.kind}]`,
+  ];
+  if (response.parent) lines.push(`親: ${response.parent.slug}（${response.parent.displayName}）`);
+  if (response.children?.length) {
+    lines.push(`子: ${response.children.map((child) => child.slug).join(', ')}`);
+  }
+
+  lines.push('', '入口:');
+  for (const resource of response.resources ?? []) {
+    const canonical = resource.isCanonical ? '正本 ' : '';
+    const pending = resource.idPending ? ' ID未確認' : '';
+    const shared = resource.sharedWith?.length
+      ? ` 共有=${resource.sharedWith.map((other) => other.slug).join(',')}`
+      : '';
+    lines.push(
+      `  ${canonical}${resource.system}/${resource.role}  ${resource.label}  ${resource.url ?? '-'}${pending}${shared}`,
+    );
+  }
+  if ((response.resources ?? []).length === 0) lines.push('  （company の入口なし）');
+
+  if (!response.slack) {
+    lines.push('', 'Slack: 取得していません（--include-slack false）');
+    return lines.join('\n');
+  }
+
+  lines.push('', `Slack チャンネル（${response.slack.channels.length} 件）:`);
+  lines.push(formatChannelLines({ items: response.slack.channels, nextCursor: null }));
+  lines.push('', 'Slack 直近:');
+  lines.push(
+    formatMessageLines({
+      items: response.slack.messages.items,
+      nextCursor: response.slack.messages.nextCursor,
+      continuationQuery: response.slack.messages.continuationQuery,
+      effectiveQuery: response.slack.effectiveQuery,
+    }),
+  );
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// サブコマンド
+// ---------------------------------------------------------------------------
+
+/**
+ * `GET /api/agent/projects` は `q` を受け付けない（`.strict()`）ので、
+ * **`--q` は手元で絞る**。guide §4 の手順 1「名称と `aliases` を照合する」を
+ * CLI 側で肩代わりするもので、サーバへ未対応の query を送らない。
+ */
+export function filterProjects(items, q) {
+  if (!q) return items;
+  const needle = q.toLowerCase();
+  return items.filter((project) =>
+    [project.slug, project.displayName, ...(project.aliases ?? [])]
+      .filter((value) => typeof value === 'string')
+      .some((value) => value.toLowerCase().includes(needle)),
+  );
+}
+
+const COMMANDS = {
+  'projects list': {
+    options: ['q', 'limit', 'cursor'],
+    async run({ api, options, json, stdout }) {
+      const response = await api('/api/agent/projects', {
+        limit: options.limit,
+        cursor: options.cursor,
+      });
+      const filtered = filterProjects(response.items ?? [], options.q);
+      if (json) {
+        stdout.write(`${JSON.stringify({ ...response, items: filtered }, null, 2)}\n`);
+        return;
+      }
+      stdout.write(`${formatProjectLines({ ...response, items: filtered })}\n`);
+    },
+  },
+
+  'projects context': {
+    options: ['include-slack', 'from', 'to', 'q', 'limit'],
+    async run({ api, options, positional, json, stdout }) {
+      const slug = positional[0];
+      if (!slug) throw usageError('案件 slug を指定してください');
+      const includeSlack = parseBooleanOption('include-slack', options['include-slack']);
+      const response = await api(`/api/agent/projects/${encodeURIComponent(slug)}/context`, {
+        includeSlack: includeSlack === undefined ? undefined : String(includeSlack),
+        from: options.from,
+        to: options.to,
+        q: options.q,
+        limit: options.limit,
+      });
+      stdout.write(
+        json ? `${JSON.stringify(response, null, 2)}\n` : `${formatContextLines(response)}\n`,
+      );
+    },
+  },
+
+  'slack channels': {
+    options: ['project', 'limit', 'cursor'],
+    async run({ api, options, json, stdout }) {
+      const response = await api('/api/agent/slack/channels', {
+        project: options.project,
+        limit: options.limit,
+        cursor: options.cursor,
+      });
+      stdout.write(
+        json ? `${JSON.stringify(response, null, 2)}\n` : `${formatChannelLines(response)}\n`,
+      );
+    },
+  },
+
+  'slack messages': {
+    options: ['project', 'channel', 'from', 'to', 'q', 'limit', 'thread', 'cursor'],
+    async run({ api, options, json, stdout }) {
+      // **要求を組み立てられない**のは使い方の誤りなので、CLI が断る。
+      // 期間や `q` の妥当性はサーバの契約なので、こちらでは判定しない。
+      if (Boolean(options.project) === Boolean(options.channel)) {
+        throw usageError('--project か --channel のどちらか一方を指定してください');
+      }
+      const response = await api('/api/agent/slack/messages', {
+        project: options.project,
+        channel: options.channel,
+        threadTs: options.thread,
+        from: options.from,
+        to: options.to,
+        q: options.q,
+        limit: options.limit,
+        cursor: options.cursor,
+      });
+      stdout.write(
+        json ? `${JSON.stringify(response, null, 2)}\n` : `${formatMessageLines(response)}\n`,
+      );
+    },
+  },
+
+  /**
+   * 返ってきた `continuationQuery` をそのまま次の要求にする。
+   *
+   * **cursor を組み立て直さない。** cursor は版・route・並び順・query hash を含む
+   * 不透明な値で、手で作ると `400 invalid_cursor` になる（guide §3）。
+   */
+  'slack next': {
+    options: [],
+    async run({ api, positional, json, stdout }) {
+      const query = positional[0];
+      if (!query) {
+        throw usageError('continuationQuery をそのまま渡してください（前回の出力の「次:」行）');
+      }
+      const response = await requestRawQuery(api, '/api/agent/slack/messages', query);
+      stdout.write(
+        json ? `${JSON.stringify(response, null, 2)}\n` : `${formatMessageLines(response)}\n`,
+      );
+    },
+  },
+};
+
+/**
+ * `continuationQuery` を**そのまま**（再エンコードせずに）付けて投げる。
+ *
+ * `URLSearchParams` を通すと `%2B` などの表現が変わり、cursor の署名と食い違いうる。
+ * サーバが返した文字列は既に query として正しいので、触らずに繋ぐ。
+ */
+export async function requestRawQuery(api, requestPath, rawQuery) {
+  const query = rawQuery.startsWith('?') ? rawQuery.slice(1) : rawQuery;
+  // 形の検査だけ行い（query として読めること）、送るのは元の文字列。
+  if (Object.keys(Object.fromEntries(new URLSearchParams(query))).length === 0) {
+    throw usageError('continuationQuery が空です（前回の出力の「次:」行をそのまま渡す）');
+  }
+  return api(`${requestPath}?${query}`, {});
+}
+
+// ---------------------------------------------------------------------------
+// 入口
+// ---------------------------------------------------------------------------
+
+async function execute(argv, dependencies) {
+  const [group, verb, ...rest] = argv;
+  if (
+    group === undefined ||
+    group === 'help' ||
+    group === '--help' ||
+    group === '-h'
+  ) {
+    dependencies.stdout.write(USAGE);
+    return;
+  }
+
+  const name = `${group} ${verb ?? ''}`.trim();
+  const command = 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,
+  });
+}
+
+export async function runCli(argv, overrides = {}) {
+  const dependencies = {
+    env: overrides.env ?? process.env,
+    fetchImpl: overrides.fetchImpl ?? globalThis.fetch,
+    readFileImpl: overrides.readFileImpl ?? readFile,
+    sleepImpl: overrides.sleepImpl ?? defaultSleep,
+    stdout: overrides.stdout ?? process.stdout,
+    stderr: overrides.stderr ?? process.stderr,
+  };
+
+  try {
+    await execute(argv, dependencies);
+    return 0;
+  } 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));

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@shimatoworks/stw-agent",
+  "version": "0.1.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"
+  },
+  "files": [
+    "bin/stw-agent.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shimatoworks-jp/stw-manage.git",
+    "directory": "packages/stw-agent"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint"
+  }
+}