claude-task-worker 0.116.0 → 0.118.0

package/README.md

@@ -4,6 +4,8 @@ GitHub Issues/PRを定期ポーリングし、Claude Codeに処理を委譲す
 
 同梱の Claude Code プラグイン（`plugin/`）と組み合わせることで、Issue の実装からPRのレビュー対応、Dependabot PR の対応までを自動化する。CLI 本体（npm パッケージ）とプラグイン（Claude Code マーケットプレイス）は同じリポジトリ・同じ名前で提供される。
 
+使い方のマニュアル（ハンズオン形式の導入・カスタムワーカーの作り方・設定のパッケージ化など）は [`docs/`](./docs/README.md) にある。
+
 ## アーキテクチャ
 
 CLI が GitHub ラベルを検知してタスクを起動し、プラグインのスキルが実際の処理を担う。
@@ -99,8 +101,11 @@ claude-task-worker update
 ```bash
 claude-task-worker init           # 既存ファイルは保護
 claude-task-worker init --force   # 強制上書き
+claude-task-worker apply-labels   # ラベルだけを作成（冪等）
 ```
 
+`claude-task-worker.json` のトップレベル `labels`（文字列配列）にカスタムワーカー用のラベル名を書くと、`init` / `apply-labels` がプリセットのラベルに加えて作成する。色は名前から一意に決まり、プリセットと同名ならプリセットの色を使う。
+
 作成されるラベル:
 
 | ラベル | 用途 |
@@ -131,8 +136,10 @@ claude-task-worker <command> [--epic <issue-number>]... [--label <label>]... [--
 | `all` | 通常ワーカー9つ + 定期ワーカー3つ（`triage-created-issue` / `triage-pr` / `check-dependabot` を除く） |
 | `yolo` | 全ワーカーを同時にポーリング |
 | `init` | ラベル・テンプレート・設定ファイルの作成と CodeGraph セットアップ |
+| `apply-labels` | プリセットと `labels` 宣言のラベルだけを作成 |
 | `install` / `update` | 上記「セットアップ」を参照 |
 | `cloud-setup [--force]` | クラウド VM 側の準備（下記「`--cloud`」を参照） |
+| `list-workers` | プリセットとカスタムの全ワーカーを名前・種別・有効/無効・ロード元で表示（`workerFiles` のロード失敗時は exit 1） |
 | `usage` | Claude API 使用状況（5時間/7日間の利用率とリセット時刻）を表示し、Slack にも通知 |
 | `version` | CLI のバージョンを表示（`--version` / `-v` も可） |
 
@@ -165,7 +172,7 @@ claude-task-worker exec-issue --project app-a --epic 100
 
 プロジェクト名・グループ名は `config.json` で定義する（下記「設定ファイル」）。`all` は全プロジェクトを指す予約語。
 
-`--project` と併用できないコマンド: `init` / `install` / `update` / `usage` / `version`
+`--project` と併用できないコマンド: `init` / `apply-labels` / `install` / `update` / `cloud-setup` / `usage` / `version` / `list-workers`
 
 ### `--cloud`
 
@@ -176,7 +183,7 @@ claude-task-worker exec-issue --cloud
 claude-task-worker all --cloud
 ```
 
-**クラウドで実行されるのは `exec-issue` と `fix-review-point` の2ワーカーだけ**で、それ以外は `--cloud` を付けてもローカル実行のまま残る（`all` / `yolo` にそのまま付けられる）。どのワーカーがクラウドで走るかは起動時にログへ出る。
+`--cloud` を付けたプロセスが起動するワーカーはすべてクラウドで実行される。ワーカーごとの向き不向きは [`docs/cloud.md`](./docs/cloud.md) を参照。
 
 前提条件:
 
@@ -205,10 +212,10 @@ npx claude-task-worker cloud-setup
 - クラウド実行のタスクは worktree を作らない（VM が自前でリポジトリを持つため）
 - 完了は `cc-cloud-done` ラベルで検知する。4時間で応答がなければ打ち切り、`cc-need-human-check` を付けて失敗通知する
 - `--project` と併用した場合、`--cloud` は各プロジェクトへそのまま転送される
-- `--cloud` と併用できないコマンド: `init` / `install` / `update` / `usage` / `version`
+- `--cloud` と併用できないコマンド: `init` / `apply-labels` / `install` / `update` / `cloud-setup` / `usage` / `version` / `list-workers`
 - `--cloud` は `mode`（`default` / `herdr`）に依存しない。クラウドセッションの作成は `script` コマンドの疑似 pty で完結し、herdr のペインを使わないため、どちらの `mode` でも同じ経路を通る
 
-詳細は [`docs/prd-cloud-worker-execution.md`](./docs/prd-cloud-worker-execution.md) を参照。
+詳細は [`docs/cloud.md`](./docs/cloud.md) を参照。
 
 ### `--debug`
 
@@ -223,6 +230,25 @@ claude-task-worker exec-issue --cloud --debug
 
 投稿の担当は実行形態で違う。ローカルはワーカーが報告そのもの（`claude -p` の stdout / transcript）を持っているのでワーカーが投稿し、クラウドはワーカーに報告が届かないのでセッション自身に投稿させる（ワーカーはそれを回収して Slack へ載せる）。定期ワーカー（`update-*`）の投稿先は実行記録PR（`ctw-last-run-<ワーカー名>`）。クラウド実行の完了検知（`cc-cloud-done`）はフラグの有無に関わらず従来どおり動く。
 
+### `--inherit-config <path>`
+
+指定した設定ファイルを土台として読み、その上に起動ディレクトリ（cwd）直下の `claude-task-worker.json` → `claude-task-worker.local.json` を重ねる（後が勝つ。マージ規則は下記「ローカル上書き」と同じ）。複数リポジトリで共通の設定を1ファイルにまとめ、リポジトリごとの差分だけを各リポジトリに置く用途。
+
+```bash
+claude-task-worker all --inherit-config ~/ctw/shared.json
+claude-task-worker init --inherit-config ~/ctw/shared.json   # 指定パスへ設定ファイルを生成する
+```
+
+- 未指定時は従来どおり cwd 直下の `claude-task-worker.json` / `claude-task-worker.local.json` だけを読む
+- 値自体の相対パスは起動時の cwd 基準。ファイル内の相対パス（`workerFiles` / `uiDesign.designDir`）は**そのファイルの所在ディレクトリ基準**で解決する
+- 配列（`labels` / `workerFiles` など）は置き換えではなく、cwd 側の値を土台の後ろへ追記する（重複は除く）。cwd の `claude-task-worker.json` と `claude-task-worker.local.json` 同士は従来どおり local が丸ごと置き換え、その結果を土台へ追記する
+- `claude-task-worker.local.json` は常に cwd 直下のものを読む（指定ファイルと同じディレクトリのものは読まない）。cwd 直下の `claude-task-worker.json` は無くてもよい
+- 指定ファイルが存在しなければエラー終了する（既定ファイルへは倒さない）。`--project` では絶対パスにして各プロジェクトへ転送する
+- 定期ワーカーの `lastRun` は指定に関わらずリポジトリ直下の `claude-task-worker.json` で読み書きする。リポジトリ直下に同ファイルが無ければ `lastRun` だけを持つファイルが作られる（他のキーを持たないので土台の設定とは衝突しない）。`init` を `--inherit-config` 付きで実行した場合も、未記録のワーカーの `lastRun` はリポジトリ直下へ記録する（セットアップ直後に定期ワーカーが一斉に走らないようにするため）
+- スキル（`create-ui-design` / `update-design-md` / `triage-created-issue`）はリポジトリ直下の `claude-task-worker.json` を直接読むため、**`uiDesign` の設定は `--inherit-config` のファイルに書いてもスキルには届かない**。`uiDesign` はリポジトリ直下に書くこと
+
+設定・カスタムワーカー・スキルを1つのリポジトリにまとめて配る手順は [`docs/config-package.md`](./docs/config-package.md) を参照。
+
 ### Pen CLI のログイン
 
 `.pen` を扱うスキルは Pen CLI の認証を必要とする。UIデザイン先行ワークフローを使うなら一度ログインしておく。
@@ -273,6 +299,8 @@ CI やクラウド VM など対話ログインできない環境では、環境
 |---|---|---|---|
 | `fixReviewPointCallbackCommentMessage` | string | - | `fix-review-point` 完了時に PR へ投稿するコメント（未設定なら投稿しない） |
 | `remoteEnvId` | string \| null | `null` | クラウド実行（`--cloud`）時に `--environment` へ渡すクラウド環境ID。`null` なら渡さず claude 側の既定解決に任せる（下記） |
+| `labels` | string[] | `[]` | カスタムワーカー用の GitHub ラベル名。`init` / `apply-labels` が作成する（ローカル上書きでは配列ごと置き換え） |
+| `workerFiles` | string[] | `[]` | カスタムワーカーを定義した TS ファイルのパス（下記「カスタムワーカー」。ローカル上書きでは配列ごと置き換え） |
 | `uiDesign` | object | `{ "enabled": false, "designDir": "designs", "yolo": false }` | UIデザイン先行ワークフロー（下記） |
 | `workers` | object | `{}` | ワーカーごとの上書き設定（下記） |
 | `lastRun` | object | `{}` | 定期ワーカーの最終実行時刻。ワーカーが自動更新するため手で編集しない |
@@ -300,21 +328,23 @@ CI やクラウド VM など対話ログインできない環境では、環境
 | `skill` | Claude CLI の `-p` に渡すスラッシュコマンド（`"<skill> <番号>"` の形で起動） |
 | `model` | `--model` の値（`sonnet` / `opus` / `haiku`） |
 | `advisorModel` | `--advisor` の値。空文字なら advisor なし。`config.json` の `advisor: true` のときだけ参照される |
-| `effort` | `--effort` の値（`high` / `medium` / `low`） |
+| `effort` | `--effort` の値（`low` / `medium` / `high` / `xhigh` / `max`）。opus ワーカーの既定は `medium`（Opus 5.5 の既定。`medium` で Opus 5 の `high` 相当）。sonnet ワーカーは手順が確定したものが `medium`、コード変更の判断を伴うもの（`resolve-conflict` / `check-dependabot`）が `high`（Sonnet 5.5 ガイドの推奨） |
 | `pollingIntervalSeconds` | ポーリング間隔（秒） |
 | `cooldownSeconds` | タスク完了後にポーリングを止める時間（秒）。既定 `0` |
 | `maxConcurrentTasks` | 同時実行できるタスクの最大数。既定 `1` |
+| `enabled` | `false` で無効化する。`all` / `yolo` では起動せず除外したワーカー名を1行ログに出し、個別起動（`claude-task-worker <name>`）ではタスクを起動せず exit 1。既定 `true`（`claude-task-worker.local.json` でも上書きできる） |
 
 既定値:
 
 | ワーカー | `model` | `effort` | `pollingIntervalSeconds` |
 |---|---|---|---|
-| `exec-issue` / `fix-review-point` / `answer-issue-questions` / `create-issue` / `create-ui-design` / `triage-pr` | `opus` | `high` | 60 |
-| `update-issue` / `triage-created-issue` / `resolve-conflict` | `sonnet` | `high` | 60 |
+| `exec-issue` / `fix-review-point` / `answer-issue-questions` / `create-issue` / `create-ui-design` / `triage-pr` | `opus` | `medium` | 60 |
+| `update-issue` / `triage-created-issue` | `sonnet` | `medium` | 60 |
+| `resolve-conflict` | `sonnet` | `high` | 60 |
 | `epic-issue` / `apply-ui-design` | `sonnet` | `medium` | 300 |
 | `check-dependabot` | `sonnet` | `high` | 3600 |
-| `update-coding-guidelines` / `update-requirement-rules` / `update-design-md` | `opus` | `high` | 3600 |
-| （未知のワーカー名） | `opus` | `high` | 60 |
+| `update-coding-guidelines` / `update-requirement-rules` / `update-design-md` | `opus` | `medium` | 3600 |
+| （未知のワーカー名） | `opus` | `medium` | 60 |
 
 `advisorModel` の既定は全ワーカー空文字（advisor なし）。
 
@@ -330,6 +360,27 @@ CI やクラウド VM など対話ログインできない環境では、環境
 }
 ```
 
+### カスタムワーカー
+
+`workerFiles` に TS ファイルを列挙すると、起動時にロードしてプリセットと同じ扱いで起動できる（個別コマンド・`all`・`yolo`。`enabled` などの `workers.<name>` 設定も効く）。`--project` 指定時は読み込まない。
+
+- パスは絶対パス、`~` / `~/...`（home 展開）、または設定ファイルのあるディレクトリからの相対パス
+- TS は型を除去して読み込む（Node 22.13 以上。tsconfig・ビルド不要）。ファイル内の相対 import は拡張子付き（`./helper.ts`）で書く
+- `claude-task-worker/lib` は実行中の CLI 自身の `lib` に解決される
+- 1ファイルから複数の定義を export でき、`defineWorker` / `createIssuePollingWorker` / `createPrPollingWorker` / `createScheduledWorker` の戻り値だけが対象（それ以外の export は無視）
+
+```ts
+import { createIssuePollingWorker } from "claude-task-worker/lib";
+
+export const myWorker = createIssuePollingWorker({
+  name: "my-worker",
+  command: "my-skill",
+  triggerLabels: ["cc-my-worker"],
+});
+```
+
+起動時に全件を検証し、次のいずれかがあればタスクを1件も起動せず exit 1 する（メッセージにファイルパスと直し方を含む）: ファイルが存在しない／読み込み・トランスパイルに失敗／定義が1つも export されていない／`name` がプリセットと衝突／`name` がカスタム同士で衝突。`claude-task-worker list-workers` でロード結果を確認できる。作り方の詳しい手順は [`docs/custom-worker.md`](./docs/custom-worker.md) を参照。
+
 ## ワークフロー
 
 ### Epic（親Issue）連携

package/dist/chunk-3RY43CYR.js

@@ -0,0 +1,41 @@
+// src/commands/run-command.ts
+import { spawn } from "node:child_process";
+function npmInstallGlobalLatest(pkg) {
+  return runCommand("npm", ["install", "-g", `${pkg}@latest`, "--prefer-online"]);
+}
+function runCommand(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+    const forwardSignal = (signal) => {
+      child.kill(signal);
+    };
+    const onSigint = () => forwardSignal("SIGINT");
+    const onSigterm = () => forwardSignal("SIGTERM");
+    const cleanup = () => {
+      process.removeListener("SIGINT", onSigint);
+      process.removeListener("SIGTERM", onSigterm);
+    };
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
+    child.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+    child.on("close", (code) => {
+      cleanup();
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+      }
+    });
+  });
+}
+
+export {
+  npmInstallGlobalLatest,
+  runCommand
+};

package/dist/chunk-N42YU3GJ.js

@@ -0,0 +1,184 @@
+// src/table.ts
+import { format } from "node:util";
+function getDisplayWidth(str) {
+  let width = 0;
+  for (const char of str.replace(CONTROL_CHARS, "")) {
+    const code = char.codePointAt(0);
+    if (code >= 4352 && code <= 4447 || code >= 11904 && code <= 12350 || code >= 12352 && code <= 13247 || code >= 13312 && code <= 19903 || code >= 19968 && code <= 42191 || code >= 44032 && code <= 55215 || code >= 63744 && code <= 64255 || code >= 65072 && code <= 65135 || code >= 65281 && code <= 65376 || code >= 65504 && code <= 65510 || code >= 131072 && code <= 196605 || code >= 196608 && code <= 262141) {
+      width += 2;
+    } else {
+      width += 1;
+    }
+  }
+  return width;
+}
+function truncateToWidth(str, maxWidth) {
+  let width = 0;
+  let i = 0;
+  const chars = [...str];
+  while (i < chars.length) {
+    const charWidth = getDisplayWidth(chars[i]);
+    if (width + charWidth > maxWidth - 3) {
+      return chars.slice(0, i).join("") + "...";
+    }
+    width += charWidth;
+    i++;
+  }
+  return str;
+}
+function padToWidth(str, targetWidth) {
+  const currentWidth = getDisplayWidth(str);
+  const padding = targetWidth - currentWidth;
+  return padding > 0 ? str + " ".repeat(padding) : str;
+}
+var CLOUD_WORKTREE_LABEL = "\x1B[36m\u2601 running in cloud\x1B[0m";
+function formatDuration(start, end = /* @__PURE__ */ new Date()) {
+  const diffMs = end.getTime() - start.getTime();
+  const totalSeconds = Math.floor(diffMs / 1e3);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
+function formatTime(date) {
+  const h = String(date.getHours()).padStart(2, "0");
+  const m = String(date.getMinutes()).padStart(2, "0");
+  const s = String(date.getSeconds()).padStart(2, "0");
+  return `${h}:${m}:${s}`;
+}
+function renderBoxTable(headers, groups) {
+  const allRows = groups.flat();
+  const widths = headers.map(
+    (h, i) => Math.max(1, getDisplayWidth(h), ...allRows.map((r) => getDisplayWidth(r[i] ?? "")))
+  );
+  const border = (l, m, r) => `${l}${widths.map((w) => "\u2500".repeat(w + 2)).join(m)}${r}`;
+  const row = (cells) => `\u2502 ${cells.map((c, i) => padToWidth(c ?? "", widths[i])).join(" \u2502 ")} \u2502`;
+  const lines = [];
+  lines.push(border("\u250C", "\u252C", "\u2510"));
+  lines.push(row(headers));
+  lines.push(border("\u251C", "\u253C", "\u2524"));
+  const nonEmpty = groups.filter((g) => g.length > 0);
+  nonEmpty.forEach((group, gi) => {
+    if (gi > 0) lines.push(border("\u251C", "\u253C", "\u2524"));
+    for (const r of group) lines.push(row(r));
+  });
+  lines.push(border("\u2514", "\u2534", "\u2518"));
+  return lines;
+}
+var TASK_DISPLAY_LIMIT = 20;
+var LOG_DISPLAY_LIMIT = 20;
+function taskRecency(t) {
+  return (t.finishedAt ?? t.startedAt).getTime();
+}
+function selectRecentTasks(entries, limit = TASK_DISPLAY_LIMIT) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const e of entries) byId.set(e.id, e);
+  const unique = [...byId.values()];
+  const running = unique.filter((t) => t.status === "running").sort((a, b) => taskRecency(b) - taskRecency(a));
+  const finished = unique.filter((t) => t.status !== "running").sort((a, b) => taskRecency(b) - taskRecency(a));
+  return [...running, ...finished].slice(0, limit);
+}
+function buildTaskTableLines(entries, now = /* @__PURE__ */ new Date()) {
+  if (entries.length === 0) return [];
+  const runningTasks = entries.filter((t) => t.status === "running");
+  const finishedTasks = entries.filter((t) => t.status !== "running");
+  const maxTitleWidth = 40;
+  const maxPathWidth = 40;
+  const truncTitle = (s) => getDisplayWidth(s) > maxTitleWidth ? truncateToWidth(s, maxTitleWidth) : s;
+  const truncPath = (p) => p ? getDisplayWidth(p) > maxPathWidth ? truncateToWidth(p, maxPathWidth) : p : "";
+  const hasPath = entries.some((t) => truncPath(t.path) !== "");
+  const runningRows = runningTasks.map(
+    (t) => taskRow(
+      t,
+      truncTitle(t.title),
+      truncPath(t.path),
+      hasPath,
+      t.agentStatus ? `${t.status}:${t.agentStatus}` : t.status,
+      formatTime(t.startedAt),
+      formatDuration(t.startedAt, now)
+    )
+  );
+  const finishedRows = finishedTasks.map(
+    (t) => taskRow(
+      t,
+      truncTitle(t.title),
+      truncPath(t.path),
+      hasPath,
+      t.status,
+      formatTime(t.finishedAt ?? t.startedAt),
+      formatDuration(t.startedAt, t.finishedAt ?? now)
+    )
+  );
+  const headers = hasPath ? ["#", "Title", "Worker", "Worktree", "Status", "Time", "Duration"] : ["#", "Title", "Worker", "Status", "Time", "Duration"];
+  return renderBoxTable(headers, [runningRows, finishedRows]);
+}
+function taskRow(t, title, path, hasPath, status, time, duration) {
+  return hasPath ? [`#${t.id}`, title, t.workerName, path, status, time, duration] : [`#${t.id}`, title, t.workerName, status, time, duration];
+}
+var logLines = [];
+function pushLogLine(entry) {
+  if (entry.text.trim().length === 0) return;
+  logLines.push(entry);
+  if (logLines.length > LOG_DISPLAY_LIMIT) {
+    logLines.splice(0, logLines.length - LOG_DISPLAY_LIMIT);
+  }
+}
+var rawLog = console.log.bind(console);
+var rawClear = console.clear.bind(console);
+function writeScreen(lines) {
+  rawClear();
+  rawLog(lines.join("\n"));
+}
+var consoleCaptured = false;
+function captureConsole() {
+  if (consoleCaptured) return;
+  consoleCaptured = true;
+  process.on("exit", () => {
+    if (logLines.length > 0) rawLog(buildLogTableLines(logLines).join("\n"));
+  });
+  const streams = { log: "stdout", info: "stdout", warn: "stderr", error: "stderr" };
+  for (const [method, stream] of Object.entries(streams)) {
+    console[method] = (...args) => {
+      for (const line of format(...args).split("\n")) {
+        pushLogLine({ stream, text: line, time: /* @__PURE__ */ new Date() });
+      }
+    };
+  }
+}
+var CONTROL_CHARS = (
+  // eslint-disable-next-line no-control-regex -- ANSI/制御文字を意図的に対象にする
+  /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\[[0-9;?]*[ -/]*[@-~]|[\x00-\x08\x0b-\x1f\x7f]/g
+);
+function sanitizeLogText(text) {
+  return text.replace(CONTROL_CHARS, " ").replace(/\t/g, " ");
+}
+function buildLogTableLines(entries) {
+  if (entries.length === 0) return [];
+  const maxTextWidth = 100;
+  const rows = [...entries].reverse().map((e) => {
+    const text = sanitizeLogText(e.text);
+    return [
+      formatTime(e.time),
+      e.id === void 0 ? "-" : `#${e.id}`,
+      e.stream,
+      getDisplayWidth(text) > maxTextWidth ? truncateToWidth(text, maxTextWidth) : text
+    ];
+  });
+  return renderBoxTable(["Time", "#", "Stream", "Log"], [rows]);
+}
+
+export {
+  getDisplayWidth,
+  truncateToWidth,
+  padToWidth,
+  CLOUD_WORKTREE_LABEL,
+  TASK_DISPLAY_LIMIT,
+  LOG_DISPLAY_LIMIT,
+  selectRecentTasks,
+  buildTaskTableLines,
+  logLines,
+  pushLogLine,
+  writeScreen,
+  captureConsole,
+  CONTROL_CHARS,
+  buildLogTableLines
+};