@tamai/hub-cli 0.1.7 → 0.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +58 -3
- package/commands/infra-note.mjs +114 -0
- package/commands/infra-update.mjs +32 -3
- package/commands/task-brief.mjs +165 -0
- package/lib/args.mjs +22 -4
- package/lib/brief.mjs +708 -0
- package/lib/cli.mjs +14 -19
- package/lib/format.mjs +42 -3
- package/lib/ulid.mjs +26 -0
- package/lib/version.mjs +24 -0
- package/package.json +1 -1
package/lib/brief.mjs
ADDED
|
@@ -0,0 +1,708 @@
|
|
|
1
|
+
// 依頼書(`hub task brief`)の素材集めと整形(記録183・`docs/notes/2026-09-20 依頼書(hub task brief)の実装指示.md`)。
|
|
2
|
+
//
|
|
3
|
+
// **文脈ゼロのAIへ渡す1枚**を作る。看板の本文は要約せず全文を入れ、`hub task show` を指さない
|
|
4
|
+
// ——依頼先がサンドボックスからAPIに届かないことがあり、その場合は `--out` のファイルだけが
|
|
5
|
+
// 相手の持つ情報のすべてになるからである(受け入れ条件)。
|
|
6
|
+
//
|
|
7
|
+
// **repo固有の規則はここに書かない。** 検証コマンドもディレクトリ名もmigration番号も、正本は
|
|
8
|
+
// 作業ディレクトリの `AGENTS.md` / `CLAUDE.md` と看板の本文で、依頼書はその場所を指すだけにする。
|
|
9
|
+
// 写すと、repoが変わったとき・規約が変わったときに依頼書だけが古い規則を配って回る。
|
|
10
|
+
//
|
|
11
|
+
// **秘密は「出さない」ではなく「持たない」。** 台帳の口座欄(`account` / `account_ref` / `note` /
|
|
12
|
+
// `payer` / `holder`)とデプロイ先の `account_key` は `collectBrief` の写しの時点で落とすので、
|
|
13
|
+
// `renderBrief` にも `--json` にも届かない(指示書 §6)。
|
|
14
|
+
|
|
15
|
+
import path from "node:path";
|
|
16
|
+
|
|
17
|
+
import { cliError } from "./args.mjs";
|
|
18
|
+
import { REDACTED, describeFailure } from "./api.mjs";
|
|
19
|
+
import { findRepoRoot } from "./records.mjs";
|
|
20
|
+
import { recordNumberFromContextRef } from "./task-ref.mjs";
|
|
21
|
+
|
|
22
|
+
/** `--role` の語彙。増やすときは定型文(`ROLE_TEXT`)も同時に足す。 */
|
|
23
|
+
export const BRIEF_ROLES = ["implement", "review", "design"];
|
|
24
|
+
|
|
25
|
+
/** `--worker` の呼び名の形(`HUB_ACTOR` と同じ流儀)。 */
|
|
26
|
+
export const WORKER_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
|
|
27
|
+
|
|
28
|
+
/** 依頼書へ写す看板eventの種類と件数(指示書 §3 の節6)。 */
|
|
29
|
+
const REPORT_KINDS = new Set(["reported", "note"]);
|
|
30
|
+
const RECENT_REPORT_LIMIT = 3;
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* 本文・報告から拾う repo 内の文書(指示書 §4 の正規表現を2本に割ったもの)。
|
|
34
|
+
*
|
|
35
|
+
* **指示書の1本(区切りで始まり空白・閉じ括弧で終わる)では、この repo の文書が1つも拾えない。**
|
|
36
|
+
* `docs/notes/2026-09-20 まとまり(プロジェクトの親子)の実装指示.md` のように、時点記録の名前は
|
|
37
|
+
* **空白も全角括弧も含む**(`docs/notes/` の命名規約が `YYYY-MM-DD タイトル.md` だから)。
|
|
38
|
+
* 拾えないと §8 の見本の「本文が指す文書」が空になり、依頼書の役目が半分消える。
|
|
39
|
+
*
|
|
40
|
+
* そこで書かれ方で分ける。backtick で囲まれていれば**囲みの中を全部**(空白も括弧も名前の一部)、
|
|
41
|
+
* 裸なら空白・閉じ括弧で切る(囲まれていない以上、どこで終わるかは空白でしか分からない)。
|
|
42
|
+
*/
|
|
43
|
+
const DOC_TAIL = "(?:dash\\/)?docs\\/(?:notes|guides|records)\\/";
|
|
44
|
+
const DOC_IN_BACKTICKS = new RegExp(`\`(${DOC_TAIL}[^\`\\n]+\\.md)\``, "g");
|
|
45
|
+
const DOC_BARE = new RegExp(`(?:^|[\\s((「])(${DOC_TAIL}[^\\s\`))」]+\\.md)`, "g");
|
|
46
|
+
|
|
47
|
+
/** 「最初に読むもの」の1行目に指す規約ファイル。両方あれば前者だけを指す。 */
|
|
48
|
+
const READ_FIRST_FILES = ["AGENTS.md", "CLAUDE.md"];
|
|
49
|
+
|
|
50
|
+
/** リンクの並び順(役割ごと)。同じ役割の中は配列順を保つ。 */
|
|
51
|
+
const LINK_ROLE_ORDER = [
|
|
52
|
+
"production", "preview", "admin", "docs", "minutes", "code", "files", "communication", "other",
|
|
53
|
+
];
|
|
54
|
+
|
|
55
|
+
const LINK_ROLE_LABELS = {
|
|
56
|
+
production: "本番",
|
|
57
|
+
preview: "プレビュー",
|
|
58
|
+
admin: "管理画面",
|
|
59
|
+
docs: "資料",
|
|
60
|
+
minutes: "議事録",
|
|
61
|
+
code: "コード",
|
|
62
|
+
files: "ファイル",
|
|
63
|
+
communication: "連絡",
|
|
64
|
+
other: "その他",
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
/** 表示名が分からない値はそのまま出す(語彙が増えてもCLIが先に古びないように)。 */
|
|
68
|
+
const PLATFORM_LABELS = {
|
|
69
|
+
cloudflare_workers: "Workers",
|
|
70
|
+
cloudflare_pages: "Pages",
|
|
71
|
+
vercel: "Vercel",
|
|
72
|
+
netlify: "Netlify",
|
|
73
|
+
xserver: "エックスサーバー",
|
|
74
|
+
other: "その他",
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
const DEPLOY_STATE_LABELS = {
|
|
78
|
+
running: "運用中",
|
|
79
|
+
stopped: "停止中",
|
|
80
|
+
planned: "予定",
|
|
81
|
+
retired: "廃止",
|
|
82
|
+
unknown: "不明",
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
// --------------------------------------------------------------------- 純関数
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* アカウント ID の形(境界つきの32桁hex・大文字小文字は問わない)。
|
|
89
|
+
*
|
|
90
|
+
* Cloudflare のアカウント ID は32桁hexで、看板の本文・報告・リンクの URL(`/accounts/<id>/…`)へ
|
|
91
|
+
* 素のまま現れうる。出口の `redactSecrets` が消すのは**設定中の Access 資格情報だけ**なので、
|
|
92
|
+
* 看板から来たアカウント ID はそのまま依頼書へ載っていた(便1 レビュー High)。
|
|
93
|
+
*
|
|
94
|
+
* **境界を見るのは巻き添えを避けるためである。** 前後にhexが続くものは対象外なので、
|
|
95
|
+
* 40桁のcommitハッシュも `cfast_` 始まりの秘密も欠けずに残る(7桁の短縮ハッシュも短すぎて当たらない)。
|
|
96
|
+
*/
|
|
97
|
+
const ACCOUNT_ID_PATTERN = /(?<![0-9a-f])[0-9a-f]{32}(?![0-9a-f])/gi;
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* 依頼書の出口で**アカウント ID だけ**を消す(`redactSecrets` と同じ置換先を使う)。
|
|
101
|
+
*
|
|
102
|
+
* **効かせるのは `hub task brief` の3経路(Markdown / `--json` / `--out`)だけ**で、
|
|
103
|
+
* `runCli` の出口へは入れない。他のコマンド(`hub infra show` 等)はアカウント ID を
|
|
104
|
+
* **見るための道具**であり、そこまで消すと台帳が読めなくなる。
|
|
105
|
+
*/
|
|
106
|
+
export function redactAccountIds(text) {
|
|
107
|
+
return String(text).replace(ACCOUNT_ID_PATTERN, REDACTED);
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
export function extractDocPaths(text) {
|
|
111
|
+
if (typeof text !== "string" || text === "") return [];
|
|
112
|
+
const found = [];
|
|
113
|
+
for (const pattern of [DOC_IN_BACKTICKS, DOC_BARE]) {
|
|
114
|
+
for (const match of text.matchAll(pattern)) found.push({ at: match.index, path: match[1] });
|
|
115
|
+
}
|
|
116
|
+
// 2本を混ぜるので出現順へ並べ直す(依頼書は本文に出てきた順で並べる)
|
|
117
|
+
found.sort((left, right) => left.at - right.at);
|
|
118
|
+
return uniqueInOrder(found.map((entry) => entry.path));
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function uniqueInOrder(values) {
|
|
122
|
+
const seen = new Set();
|
|
123
|
+
const out = [];
|
|
124
|
+
for (const value of values) {
|
|
125
|
+
if (typeof value !== "string" || value === "" || seen.has(value)) continue;
|
|
126
|
+
seen.add(value);
|
|
127
|
+
out.push(value);
|
|
128
|
+
}
|
|
129
|
+
return out;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
function oneLine(value) {
|
|
133
|
+
return String(value ?? "").replace(/\s+/g, " ").trim();
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function textOrNull(value) {
|
|
137
|
+
const text = typeof value === "string" ? value.trim() : "";
|
|
138
|
+
return text === "" ? null : text;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** 表示用のUTC時刻(ミリ秒は落とす。見本 §8 の `2026-09-20T13:05:00Z`)。 */
|
|
142
|
+
function displayTime(iso) {
|
|
143
|
+
return String(iso ?? "").replace(/\.\d{3}Z$/, "Z");
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
// ----------------------------------------------------------------- 素材の収集
|
|
147
|
+
|
|
148
|
+
async function isPlainFile(absolute, lstatImpl) {
|
|
149
|
+
if (typeof lstatImpl !== "function") return false;
|
|
150
|
+
try {
|
|
151
|
+
const entry = await lstatImpl(absolute);
|
|
152
|
+
if (entry?.isSymbolicLink?.() === true) return false;
|
|
153
|
+
return entry?.isFile?.() === true;
|
|
154
|
+
} catch {
|
|
155
|
+
return false;
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
async function collectRepo(contextRef, dependencies) {
|
|
160
|
+
const root = await findRepoRoot(dependencies.cwd(), dependencies.statImpl);
|
|
161
|
+
if (root === null) return { root: null, read_first: null, record_exists: false };
|
|
162
|
+
|
|
163
|
+
let readFirst = null;
|
|
164
|
+
for (const name of READ_FIRST_FILES) {
|
|
165
|
+
if (await isPlainFile(path.join(root, name), dependencies.lstatImpl)) {
|
|
166
|
+
readFirst = name;
|
|
167
|
+
break;
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
let recordExists = false;
|
|
172
|
+
const ref = typeof contextRef === "string" ? contextRef : "";
|
|
173
|
+
const segments = ref.split("/");
|
|
174
|
+
// APIから来た綴りで作業ツリーの外を触らない(`narrowByRepoRecord` と同じ用心)
|
|
175
|
+
if (ref !== "" && !path.isAbsolute(ref) && !segments.includes("..") && !segments.includes("")) {
|
|
176
|
+
recordExists = await isPlainFile(path.join(root, ...segments), dependencies.lstatImpl);
|
|
177
|
+
}
|
|
178
|
+
return { root, read_first: readFirst, record_exists: recordExists };
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** 台帳の行から**依頼に要る列だけ**を写す(口座欄はここで落とす)。 */
|
|
182
|
+
function pickAsset(asset) {
|
|
183
|
+
return {
|
|
184
|
+
name: oneLine(asset?.name),
|
|
185
|
+
kind: textOrNull(asset?.kind),
|
|
186
|
+
provider: textOrNull(asset?.provider),
|
|
187
|
+
status: textOrNull(asset?.status),
|
|
188
|
+
management: textOrNull(asset?.management),
|
|
189
|
+
auto_renew: textOrNull(asset?.auto_renew),
|
|
190
|
+
expires_on: textOrNull(asset?.expires_on),
|
|
191
|
+
purpose: textOrNull(asset?.purpose),
|
|
192
|
+
hosted_on: asset?.hosted_on ? { name: oneLine(asset.hosted_on.name) } : null,
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** デプロイ先の行。`account_key` は写さない(呼び名 `account_label` で足りる)。 */
|
|
197
|
+
function pickDeployTarget(target) {
|
|
198
|
+
return {
|
|
199
|
+
name: oneLine(target?.name),
|
|
200
|
+
platform: textOrNull(target?.platform),
|
|
201
|
+
account_label: textOrNull(target?.account_label),
|
|
202
|
+
platform_ref: textOrNull(target?.platform_ref),
|
|
203
|
+
target_kind: textOrNull(target?.target_kind),
|
|
204
|
+
state: textOrNull(target?.state),
|
|
205
|
+
url: textOrNull(target?.url),
|
|
206
|
+
repo: textOrNull(target?.repo),
|
|
207
|
+
repo_path: textOrNull(target?.repo_path),
|
|
208
|
+
domain: textOrNull(target?.domain_candidate?.name),
|
|
209
|
+
};
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
function pickLink(link) {
|
|
213
|
+
return {
|
|
214
|
+
label: oneLine(link?.label),
|
|
215
|
+
url: oneLine(link?.url),
|
|
216
|
+
system: textOrNull(link?.system),
|
|
217
|
+
role: textOrNull(link?.role),
|
|
218
|
+
};
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* 案件の素材。**引けなければ null を返して warnings へ積む**(依頼書そのものは出す)。
|
|
223
|
+
* 看板の本文が一番大事なので、周辺の素材の失敗で1枚ごと止めない(`resolveTaskProject` と同じ理屈)。
|
|
224
|
+
*/
|
|
225
|
+
async function collectProject(projectName, api, warnings) {
|
|
226
|
+
if (projectName === null) {
|
|
227
|
+
warnings.push("看板に案件が無いので案件の節を省きました");
|
|
228
|
+
return null;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
let items;
|
|
232
|
+
try {
|
|
233
|
+
const payload = await api("/api/projects");
|
|
234
|
+
if (!Array.isArray(payload?.items)) throw cliError("projects一覧のAPI応答が不正です");
|
|
235
|
+
items = payload.items;
|
|
236
|
+
} catch (error) {
|
|
237
|
+
warnings.push(`案件を引けなかったので案件の節を省きました(${describeFailure(error)})`);
|
|
238
|
+
return null;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
const found = items.find((entry) => entry?.name === projectName);
|
|
242
|
+
if (found === undefined || typeof found?.slug !== "string") {
|
|
243
|
+
warnings.push(`案件「${oneLine(projectName)}」が一覧に無いので案件の節を省きました`);
|
|
244
|
+
return null;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
let detail;
|
|
248
|
+
try {
|
|
249
|
+
detail = await api(`/api/projects/${encodeURIComponent(found.slug)}`);
|
|
250
|
+
} catch (error) {
|
|
251
|
+
warnings.push(`案件の詳細を引けなかったので案件の節を省きました(${describeFailure(error)})`);
|
|
252
|
+
return null;
|
|
253
|
+
}
|
|
254
|
+
const item = detail?.item ?? found;
|
|
255
|
+
|
|
256
|
+
let assets = [];
|
|
257
|
+
try {
|
|
258
|
+
const payload = await api(
|
|
259
|
+
`/api/infra/assets?project=${encodeURIComponent(found.slug)}&management=all`,
|
|
260
|
+
);
|
|
261
|
+
assets = Array.isArray(payload?.items) ? payload.items.map(pickAsset) : [];
|
|
262
|
+
} catch (error) {
|
|
263
|
+
warnings.push(`台帳を引けなかったので台帳の小節を省きました(${describeFailure(error)})`);
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
const parentSlug = textOrNull(item?.parent_slug);
|
|
267
|
+
const parent = parentSlug === null
|
|
268
|
+
? null
|
|
269
|
+
: { slug: parentSlug, name: textOrNull(items.find((entry) => entry?.slug === parentSlug)?.name) };
|
|
270
|
+
|
|
271
|
+
return {
|
|
272
|
+
slug: found.slug,
|
|
273
|
+
name: oneLine(item?.name),
|
|
274
|
+
kind: textOrNull(item?.kind),
|
|
275
|
+
entity_type: textOrNull(item?.entity_type) ?? "project",
|
|
276
|
+
parent,
|
|
277
|
+
repo: textOrNull(item?.repo),
|
|
278
|
+
memory_home: textOrNull(item?.memory_home),
|
|
279
|
+
links: Array.isArray(item?.links) ? item.links.map(pickLink) : [],
|
|
280
|
+
deploy_targets: Array.isArray(detail?.deploy_targets)
|
|
281
|
+
? detail.deploy_targets.map(pickDeployTarget)
|
|
282
|
+
: [],
|
|
283
|
+
assets,
|
|
284
|
+
children: Array.isArray(detail?.children)
|
|
285
|
+
? detail.children.map((child) => ({
|
|
286
|
+
slug: textOrNull(child?.slug),
|
|
287
|
+
name: oneLine(child?.name),
|
|
288
|
+
status: textOrNull(child?.status),
|
|
289
|
+
}))
|
|
290
|
+
: [],
|
|
291
|
+
};
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* 依頼書の素材(指示書 §4)。
|
|
296
|
+
*
|
|
297
|
+
* **看板の取得失敗だけが致命**で、そのまま投げる(依頼書を出さない)。案件・台帳の失敗は
|
|
298
|
+
* `warnings` へ積んで続ける。
|
|
299
|
+
*/
|
|
300
|
+
export async function collectBrief({ ref, id, api, dependencies, options, version, now = new Date() }) {
|
|
301
|
+
const warnings = [];
|
|
302
|
+
const payload = await api(`/api/tasks/${encodeURIComponent(id)}`);
|
|
303
|
+
const item = payload?.item;
|
|
304
|
+
if (item === null || typeof item !== "object" || Array.isArray(item)) {
|
|
305
|
+
throw cliError("タスク詳細のAPI応答が不正です");
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
const status = textOrNull(item.status);
|
|
309
|
+
if (status === "done" || status === "iced") {
|
|
310
|
+
warnings.push(`この看板は ${status} です。依頼者に確かめてから着手してもらってください`);
|
|
311
|
+
}
|
|
312
|
+
if (options.role === "review" && options.commits === null) {
|
|
313
|
+
warnings.push("--commits が無いので対象コミットの節は空です");
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
const events = Array.isArray(payload?.events) ? payload.events : [];
|
|
317
|
+
const reports = events
|
|
318
|
+
.filter((event) => REPORT_KINDS.has(event?.kind) && textOrNull(event?.note) !== null)
|
|
319
|
+
.sort((left, right) => String(right?.at ?? "").localeCompare(String(left?.at ?? "")))
|
|
320
|
+
.slice(0, RECENT_REPORT_LIMIT)
|
|
321
|
+
.map((event) => ({
|
|
322
|
+
at: textOrNull(event?.at),
|
|
323
|
+
actor: textOrNull(event?.actor),
|
|
324
|
+
kind: textOrNull(event?.kind),
|
|
325
|
+
note: String(event.note),
|
|
326
|
+
}));
|
|
327
|
+
|
|
328
|
+
const contextRef = textOrNull(item.context_ref);
|
|
329
|
+
const task = {
|
|
330
|
+
id: String(item.id ?? id),
|
|
331
|
+
title: oneLine(item.title),
|
|
332
|
+
status,
|
|
333
|
+
owner: textOrNull(item.owner),
|
|
334
|
+
due: textOrNull(item.due),
|
|
335
|
+
project: textOrNull(item.project),
|
|
336
|
+
context_ref: contextRef,
|
|
337
|
+
record_number: recordNumberFromContextRef(contextRef),
|
|
338
|
+
body: typeof item.body === "string" ? item.body : "",
|
|
339
|
+
reports,
|
|
340
|
+
};
|
|
341
|
+
|
|
342
|
+
const project = await collectProject(task.project, api, warnings);
|
|
343
|
+
const repo = await collectRepo(contextRef, dependencies);
|
|
344
|
+
|
|
345
|
+
const fromBody = uniqueInOrder(extractDocPaths(task.body));
|
|
346
|
+
const fromReports = uniqueInOrder(reports.flatMap((report) => extractDocPaths(report.note)));
|
|
347
|
+
const docs = uniqueInOrder([...fromBody, ...fromReports]).filter((doc) => doc !== contextRef);
|
|
348
|
+
// 「本文が指す文書」か「本文と報告が指す文書」か(見出しの文言が変わるだけ)
|
|
349
|
+
const docsFromReports = docs.some((doc) => !fromBody.includes(doc));
|
|
350
|
+
|
|
351
|
+
return {
|
|
352
|
+
generated_at: now.toISOString(),
|
|
353
|
+
cli_version: version,
|
|
354
|
+
options: {
|
|
355
|
+
ref: String(ref ?? id),
|
|
356
|
+
role: options.role,
|
|
357
|
+
worker: options.worker,
|
|
358
|
+
commits: options.commits,
|
|
359
|
+
sandboxed: options.sandboxed === true,
|
|
360
|
+
note: options.note,
|
|
361
|
+
note_file: options.noteFile ?? null,
|
|
362
|
+
},
|
|
363
|
+
task,
|
|
364
|
+
project,
|
|
365
|
+
repo,
|
|
366
|
+
docs,
|
|
367
|
+
docs_from_reports: docsFromReports,
|
|
368
|
+
warnings,
|
|
369
|
+
};
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
// ------------------------------------------------------------------- 定型文
|
|
373
|
+
|
|
374
|
+
/** 節8「守ること」の共通(指示書 §5.2)。 */
|
|
375
|
+
const KEEP_COMMON = [
|
|
376
|
+
"- 作業ディレクトリの AGENTS.md / CLAUDE.md が repo の規約の正本です。この依頼書と食い違ったら AGENTS.md を信じ、その旨を報告に書きます。",
|
|
377
|
+
"- 共有ファイルは編集の直前に読み直します(並行作業の上書きを防ぐため)。",
|
|
378
|
+
"- コミットは自分が触ったファイルだけを `git add <path>` し、`git commit -- <path>` でパスを指定します。`git add -A` / `git commit -a` は使いません。コミットメッセージの言語と形式は AGENTS.md に従います。",
|
|
379
|
+
"- 既存の型・作法(テストの書き方・エラーの形・ファイルの置き場)に合わせます。新しい依存を足しません。",
|
|
380
|
+
"- 看板の本文と §2 の補足が指示書と食い違ったら、§2 → 本文 → 指示書 の順で優先します。",
|
|
381
|
+
];
|
|
382
|
+
|
|
383
|
+
/** 節9「やってはいけないこと」の共通(指示書 §5.3)。 */
|
|
384
|
+
const FORBID_COMMON = [
|
|
385
|
+
"- git push・デプロイ・リモートの DB への migration 適用・本番データの変更・タグの作成・パッケージの公開。これらは依頼者だけが行います。",
|
|
386
|
+
"- `hub task report` と done への変更(検収は人が行います。報告は §12 の形で依頼者へ)。",
|
|
387
|
+
"- 秘密(トークン・パスワード・アカウント ID・会員 ID)をコード・コミット・記録・報告に書くこと。",
|
|
388
|
+
"- 指示に無い削除・履歴の改変(git reset・rebase -i・force push)。",
|
|
389
|
+
"- 他の作業者が doing にしている看板への着手。",
|
|
390
|
+
];
|
|
391
|
+
|
|
392
|
+
/** `--sandboxed` のとき節1の末尾に足す段落(指示書 §5.4)。 */
|
|
393
|
+
const SANDBOXED_PARAGRAPH =
|
|
394
|
+
"この環境は hub の API に届かず、commit できないことがあります。hub CLI は使いません"
|
|
395
|
+
+ "(看板の本文はこの依頼書の §5 に入っています)。記録への追記は commit できなければ"
|
|
396
|
+
+ "ファイルに書くだけで構いません(依頼者が代わりにコミットします)。看板への報告(note / report)も"
|
|
397
|
+
+ "依頼者が代行するので、最終報告は §12 の形で依頼者へ返してください。";
|
|
398
|
+
|
|
399
|
+
const ROLE_TEXT = {
|
|
400
|
+
implement: {
|
|
401
|
+
title: "実装担当",
|
|
402
|
+
lead: "あなたは <worker>(実装担当)です。",
|
|
403
|
+
guidance: "設計の正本が本文か §4 の文書にあれば、そのとおりに実装します。迷ったら本文の「決まっていること」を優先し、それでも決められないことは記録に「未確認」と書いて先へ進みます。",
|
|
404
|
+
claim: true,
|
|
405
|
+
keep: [
|
|
406
|
+
"- 依頼の範囲より広げません。迷ったら「やらないこと」へ送り、記録に書きます。",
|
|
407
|
+
"- パッケージの版(version)を上げません(公開は依頼者が行います)。",
|
|
408
|
+
],
|
|
409
|
+
forbid: [],
|
|
410
|
+
verify: true,
|
|
411
|
+
},
|
|
412
|
+
review: {
|
|
413
|
+
title: "最終レビュー担当",
|
|
414
|
+
lead: "あなたは <worker>(最終レビュー担当)です。コードは直しません。",
|
|
415
|
+
guidance: "対象は §3 のコミットです。設計の正本と看板の本文(裁定を含む)に照らして、受け入れ条件が1つずつコードとテストで裏が取れているかを見ます。取れていない条件は「未担保」と書きます。",
|
|
416
|
+
claim: false,
|
|
417
|
+
keep: [
|
|
418
|
+
"- 所見は 重要度(High / Medium / Low)・該当ファイル:行・理由・直し方 の形で書きます。",
|
|
419
|
+
"- 疑わしい変異は1〜2本、自分で当てて再現します(テストが本当に落ちるか)。",
|
|
420
|
+
"- 最後に「approve」か「差し戻し(High の件数)」を1行で明記します。",
|
|
421
|
+
],
|
|
422
|
+
forbid: ["- コードを直すこと(所見を書くだけ。直すのは実装者です)。"],
|
|
423
|
+
verify: true,
|
|
424
|
+
},
|
|
425
|
+
design: {
|
|
426
|
+
title: "設計担当",
|
|
427
|
+
lead: "あなたは <worker>(設計担当)です。コードは書きません。",
|
|
428
|
+
guidance: "成果物は実装指示(docs/notes/ の時点記録)で、実装者が読むだけで着手できる粒度にします。",
|
|
429
|
+
claim: true,
|
|
430
|
+
keep: [
|
|
431
|
+
"- 事実(コードの該当行・実測)と決定を分けて書き、推測は「未確認」と明記します。",
|
|
432
|
+
"- 実装者が迷いそうな点には指示書の中で答えを決めておきます。",
|
|
433
|
+
],
|
|
434
|
+
forbid: [],
|
|
435
|
+
verify: false,
|
|
436
|
+
},
|
|
437
|
+
};
|
|
438
|
+
|
|
439
|
+
/** 節10「検証」(指示書 §5.6)。 */
|
|
440
|
+
function verifyLines(role) {
|
|
441
|
+
return [
|
|
442
|
+
"検証コマンドは AGENTS.md の「検証コマンド」と、本文・指示書の検証節が正です(この依頼書には写しません)。",
|
|
443
|
+
"- 全部通してから報告します。落ちたものは落ちたまま報告し、直したふりをしません。",
|
|
444
|
+
role === "review"
|
|
445
|
+
? "- 依頼者が指す検証コマンドを自分でも回し、件数(pass / fail)を所見に書きます。"
|
|
446
|
+
: "- 本文や指示書に変異表があれば、1つずつ当ててテストが落ちることを確かめ、結果を記録に書きます。",
|
|
447
|
+
];
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/** 節11「記録に書くこと」(指示書 §5.7)。 */
|
|
451
|
+
function recordLine(role, contextRef, worker) {
|
|
452
|
+
if (contextRef === null) {
|
|
453
|
+
return "依頼者が指す記録へ書きます(無ければ `hub task new --repo-card` で作る、と依頼者に確かめてください)。";
|
|
454
|
+
}
|
|
455
|
+
if (role === "implement") {
|
|
456
|
+
return `記録 \`${contextRef}\` に「## 便N 実装(${worker})」の節を足し、変更ファイル・指示書との差分(理由つき)・検証の結果・変異表の結果・やらなかったこと・未計測を書きます。frontmatter の related_commits にコミットのハッシュを足します(記録の書き方は AGENTS.md と docs/records/README.md)。`;
|
|
457
|
+
}
|
|
458
|
+
if (role === "review") {
|
|
459
|
+
return `記録 \`${contextRef}\` の末尾に「## 便N レビュー(${worker})」の節を足し、結論(High / Medium / Low の件数)・所見・受け入れ条件の照合表・検証の件数を書きます。`;
|
|
460
|
+
}
|
|
461
|
+
return `成果物は docs/notes/<日付> <題>.md(時点記録。書いたら更新しない)。記録 \`${contextRef}\` に判断の要点を書きます。`;
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
/** 節12「最終報告」(指示書 §5.8)。 */
|
|
465
|
+
function reportLines(worker) {
|
|
466
|
+
return [
|
|
467
|
+
"依頼者への最終報告は次の形で、行数は 5 行以内:",
|
|
468
|
+
`1行目: 「実作業: ${worker}」と結論(何をしたか・approve / 差し戻し)`,
|
|
469
|
+
"2行目〜: コミットのハッシュ(あれば)、検証の件数、指示書との差分、未確認・未計測、依頼者に聞く点",
|
|
470
|
+
];
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
// ------------------------------------------------------------------- 整形
|
|
474
|
+
|
|
475
|
+
/**
|
|
476
|
+
* claim の行(指示書 §5.5)。
|
|
477
|
+
*
|
|
478
|
+
* `--sandboxed` のときは**行の後ろに代行の一文を足す**。付けないと、sandboxed の依頼書で
|
|
479
|
+
* 「hub CLI は使いません」(§5.4)と「着手前に `hub task claim` で claim します」が同居し、
|
|
480
|
+
* 受け取った相手が打てないコマンドを指示されたまま止まる(便1 レビュー Medium)。
|
|
481
|
+
*/
|
|
482
|
+
function claimLine(task, worker, workerRef, sandboxed) {
|
|
483
|
+
const status = task.status;
|
|
484
|
+
const relay = sandboxed ? "(この環境から claim できなければ依頼者が代行します)" : "";
|
|
485
|
+
if ((status === "doing" || status === "review") && task.owner !== null) {
|
|
486
|
+
return `この看板は ${task.owner} 名義で ${status} です。claim し直しません(claim は doing / review を拒否します)。`
|
|
487
|
+
+ `着手したら看板の note の冒頭に「実作業: ${worker}」と書きます。${relay}`;
|
|
488
|
+
}
|
|
489
|
+
if (status === "inbox" || status === "ready") {
|
|
490
|
+
return `この看板はまだ ${status} です。着手前に \`hub task claim ${task.id} --owner ${workerRef}\` で claim します。${relay}`;
|
|
491
|
+
}
|
|
492
|
+
return "";
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
function invocation(options) {
|
|
496
|
+
const parts = ["hub task brief", options.ref, "--role", options.role];
|
|
497
|
+
if (options.worker !== null) parts.push("--worker", options.worker);
|
|
498
|
+
if (options.commits !== null) parts.push("--commits", JSON.stringify(options.commits));
|
|
499
|
+
if (options.note_file !== null) parts.push("--note-file", options.note_file);
|
|
500
|
+
else if (options.note !== null) parts.push("--note", "…");
|
|
501
|
+
if (options.sandboxed) parts.push("--sandboxed");
|
|
502
|
+
return parts.join(" ");
|
|
503
|
+
}
|
|
504
|
+
|
|
505
|
+
function readFirstLines(material, worker) {
|
|
506
|
+
const lines = [];
|
|
507
|
+
const root = material.repo.root;
|
|
508
|
+
const where = root === null ? "作業ディレクトリ" : `作業ディレクトリ ${root}`;
|
|
509
|
+
if (material.repo.read_first === null) {
|
|
510
|
+
lines.push(`${where} に \`AGENTS.md\` / \`CLAUDE.md\` があれば最初に読みます(repo の規約の正本)`);
|
|
511
|
+
} else {
|
|
512
|
+
lines.push(`\`${material.repo.read_first}\`(${where} の規約の正本。Read Order もここ)`);
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
if (!material.options.sandboxed) {
|
|
516
|
+
const cd = root === null ? "" : `\`cd ${root}\` → `;
|
|
517
|
+
lines.push(
|
|
518
|
+
`認証と名乗り: ${cd}\`set -a && source ~/.config/tamai/hub-tasks.env && set +a\` → \`export HUB_ACTOR=${worker}\``,
|
|
519
|
+
);
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
lines.push("看板の本文は §5(この依頼書に全文があります)");
|
|
523
|
+
|
|
524
|
+
const ref = material.task.context_ref;
|
|
525
|
+
if (ref !== null) {
|
|
526
|
+
if (material.task.record_number === null) {
|
|
527
|
+
lines.push(`参照: ${ref}`);
|
|
528
|
+
} else {
|
|
529
|
+
lines.push(`記録: \`${ref}\`(${material.repo.record_exists ? "手元にあり" : "手元に無ければ pull する"})`);
|
|
530
|
+
}
|
|
531
|
+
}
|
|
532
|
+
|
|
533
|
+
if (material.docs.length > 0) {
|
|
534
|
+
const label = material.docs_from_reports ? "本文と報告が指す文書" : "本文が指す文書";
|
|
535
|
+
lines.push(`${label}: ${material.docs.map((doc) => `\`${doc}\``).join("、")}`);
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
const project = material.project;
|
|
539
|
+
if (project !== null && (project.repo !== null || project.memory_home !== null)) {
|
|
540
|
+
const home = project.repo === null ? "(repo の登録なし)" : `\`${project.repo}\``;
|
|
541
|
+
const where2 = project.memory_home === "vault"
|
|
542
|
+
? "記憶は Vault 側。repo に記録を置きません"
|
|
543
|
+
: "記録はこの repo の `docs/records/`";
|
|
544
|
+
lines.push(`記憶の家: ${home}(${where2})`);
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
return lines.map((line, index) => `${index + 1}. ${line}`);
|
|
548
|
+
}
|
|
549
|
+
|
|
550
|
+
function projectSection(project) {
|
|
551
|
+
const lines = [];
|
|
552
|
+
const kind = project.kind === null ? "" : `・${project.kind}`;
|
|
553
|
+
const shape = project.entity_type === "group" ? "グループ" : "案件";
|
|
554
|
+
const home = project.repo === null
|
|
555
|
+
? (project.memory_home === null ? "" : `・記憶の家 ${project.memory_home}`)
|
|
556
|
+
: `・記憶の家 \`${project.repo}\`(${project.memory_home ?? "?"})`;
|
|
557
|
+
lines.push(`${project.name}(\`${project.slug}\`${kind}・${shape})${home}`);
|
|
558
|
+
if (project.parent !== null) {
|
|
559
|
+
lines.push(`グループ: ${project.parent.name ?? "(名前を引けず)"}(\`${project.parent.slug}\`)`);
|
|
560
|
+
}
|
|
561
|
+
if (project.children.length > 0) {
|
|
562
|
+
lines.push(
|
|
563
|
+
`配下の案件 ${project.children.length} 件: ${project.children.map((child) => `\`${child.slug}\``).join("、")}`,
|
|
564
|
+
);
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
if (project.links.length > 0) {
|
|
568
|
+
const ordered = [...project.links].sort((left, right) => {
|
|
569
|
+
const leftIndex = LINK_ROLE_ORDER.indexOf(left.role ?? "other");
|
|
570
|
+
const rightIndex = LINK_ROLE_ORDER.indexOf(right.role ?? "other");
|
|
571
|
+
return (leftIndex === -1 ? LINK_ROLE_ORDER.length : leftIndex)
|
|
572
|
+
- (rightIndex === -1 ? LINK_ROLE_ORDER.length : rightIndex);
|
|
573
|
+
});
|
|
574
|
+
lines.push("", "リンク(役割ごと):");
|
|
575
|
+
for (const link of ordered) {
|
|
576
|
+
const label = LINK_ROLE_LABELS[link.role ?? "other"] ?? link.role ?? "その他";
|
|
577
|
+
lines.push(`- ${label}: ${link.label} — ${link.url}`);
|
|
578
|
+
}
|
|
579
|
+
}
|
|
580
|
+
|
|
581
|
+
if (project.deploy_targets.length > 0) {
|
|
582
|
+
lines.push("", "デプロイ先:");
|
|
583
|
+
for (const target of project.deploy_targets) {
|
|
584
|
+
const platform = PLATFORM_LABELS[target.platform] ?? target.platform ?? "?";
|
|
585
|
+
const account = target.account_label ?? "?";
|
|
586
|
+
const ref = target.platform_ref === null ? "(未照合)" : `\`${target.platform_ref}\``;
|
|
587
|
+
const state = DEPLOY_STATE_LABELS[target.state] ?? target.state ?? "?";
|
|
588
|
+
const parts = [`- ${target.name} — ${platform} / ${account} / ${ref} / ${state}`];
|
|
589
|
+
if (target.url !== null) parts.push(target.url);
|
|
590
|
+
if (target.repo !== null) {
|
|
591
|
+
parts.push(`コード ${target.repo}${target.repo_path === null ? "" : ` ${target.repo_path}`}`);
|
|
592
|
+
}
|
|
593
|
+
if (target.domain !== null) parts.push(`台帳の候補: ${target.domain}`);
|
|
594
|
+
lines.push(parts.join(" — "));
|
|
595
|
+
}
|
|
596
|
+
}
|
|
597
|
+
|
|
598
|
+
if (project.assets.length > 0) {
|
|
599
|
+
lines.push("", "台帳の資産:");
|
|
600
|
+
for (const asset of project.assets) {
|
|
601
|
+
const meta = [
|
|
602
|
+
asset.kind ?? "?",
|
|
603
|
+
asset.provider ?? "?",
|
|
604
|
+
asset.status ?? "?",
|
|
605
|
+
`自動更新 ${asset.auto_renew ?? "?"}`,
|
|
606
|
+
`期限 ${asset.expires_on ?? "なし"}`,
|
|
607
|
+
].join("・");
|
|
608
|
+
const external = asset.management === "external" ? "(他社管理)" : "";
|
|
609
|
+
const purpose = asset.purpose === null ? "" : ` — ${asset.purpose}`;
|
|
610
|
+
const hosted = asset.hosted_on === null ? "" : ` — ${asset.hosted_on.name} 上`;
|
|
611
|
+
lines.push(`- ${asset.name}(${meta})${external}${purpose}${hosted}`);
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
|
|
615
|
+
return lines;
|
|
616
|
+
}
|
|
617
|
+
|
|
618
|
+
/**
|
|
619
|
+
* 依頼書のMarkdown(純関数。時刻も版も素材に入っている)。
|
|
620
|
+
*
|
|
621
|
+
* **節の番号は固定**(1〜12)で、出ない節はその番号ごと飛ばす。依頼書の中で「§5 の本文」と
|
|
622
|
+
* 指すので、role によって番号がずれると参照が壊れる。
|
|
623
|
+
*/
|
|
624
|
+
export function renderBrief(material) {
|
|
625
|
+
const { task, options } = material;
|
|
626
|
+
const role = ROLE_TEXT[options.role];
|
|
627
|
+
const worker = options.worker ?? "(呼び名は依頼者から受け取ります)";
|
|
628
|
+
// コマンドや引用の中では括弧書きが読めないので、埋める語を分ける
|
|
629
|
+
const workerRef = options.worker ?? "<自分の呼び名>";
|
|
630
|
+
const out = [];
|
|
631
|
+
|
|
632
|
+
const recordLabel = task.record_number === null ? null : `記録 ${task.record_number}`;
|
|
633
|
+
out.push(`# 依頼書: ${task.title}`, "");
|
|
634
|
+
out.push(
|
|
635
|
+
[`看板 ${task.id}`, recordLabel, `生成 \`${invocation(options)}\``]
|
|
636
|
+
.filter((part) => part !== null)
|
|
637
|
+
.join(" ・ ")
|
|
638
|
+
+ `(${displayTime(material.generated_at)}・hub-cli ${material.cli_version})`,
|
|
639
|
+
);
|
|
640
|
+
|
|
641
|
+
if (task.status === "done" || task.status === "iced") {
|
|
642
|
+
out.push("", "## 0. 注意", "");
|
|
643
|
+
out.push(`注意: この看板は ${task.status} です。依頼者に確かめてから着手してください。`);
|
|
644
|
+
}
|
|
645
|
+
|
|
646
|
+
out.push("", "## 1. あなたの役割", "");
|
|
647
|
+
const claim = role.claim ? claimLine(task, worker, workerRef, options.sandboxed) : "";
|
|
648
|
+
// `--worker` が無いときの差し込みは括弧書きなので、前の空白ごと差し替える(「あなたは (…」を避ける)
|
|
649
|
+
const lead = role.lead.replace(" <worker>", options.worker === null ? worker : ` ${worker}`);
|
|
650
|
+
out.push(`${lead}${claim === "" ? "" : claim}`);
|
|
651
|
+
out.push(role.guidance);
|
|
652
|
+
if (options.sandboxed) out.push("", SANDBOXED_PARAGRAPH);
|
|
653
|
+
|
|
654
|
+
if (options.note !== null) {
|
|
655
|
+
out.push("", "## 2. 依頼者の補足(本文・指示書より優先)", "");
|
|
656
|
+
out.push(options.note.replace(/\s+$/, ""));
|
|
657
|
+
}
|
|
658
|
+
|
|
659
|
+
if (options.commits !== null) {
|
|
660
|
+
out.push("", "## 3. 対象コミット", "");
|
|
661
|
+
out.push(`${options.commits}(\`git show\` で差分を読みます)`);
|
|
662
|
+
} else if (options.role === "review") {
|
|
663
|
+
out.push("", "## 3. 対象コミット", "");
|
|
664
|
+
out.push("対象コミットは依頼者から受け取る(`git log --oneline` で確かめる)。");
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
out.push("", "## 4. 最初に読むもの", "");
|
|
668
|
+
out.push(...readFirstLines(material, workerRef));
|
|
669
|
+
|
|
670
|
+
out.push("", "## 5. 看板の本文", "");
|
|
671
|
+
out.push(
|
|
672
|
+
`status: ${task.status ?? "なし"} ・ owner: ${task.owner ?? "なし"}`
|
|
673
|
+
+ ` ・ due: ${task.due ?? "なし"} ・ context_ref: ${task.context_ref ?? "なし"}`,
|
|
674
|
+
);
|
|
675
|
+
out.push("", task.body.replace(/\s+$/, ""));
|
|
676
|
+
|
|
677
|
+
if (task.reports.length > 0) {
|
|
678
|
+
out.push("", "## 6. 看板の直近の報告", "");
|
|
679
|
+
for (const report of task.reports) {
|
|
680
|
+
out.push(`- ${displayTime(report.at) || "?"} ${report.actor ?? "?"}(${report.kind ?? "?"})`);
|
|
681
|
+
for (const line of report.note.replace(/\s+$/, "").split("\n")) out.push(` ${line}`);
|
|
682
|
+
}
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
if (material.project !== null) {
|
|
686
|
+
out.push("", "## 7. 案件", "");
|
|
687
|
+
out.push(...projectSection(material.project));
|
|
688
|
+
}
|
|
689
|
+
|
|
690
|
+
out.push("", "## 8. 守ること", "");
|
|
691
|
+
out.push(...KEEP_COMMON, ...role.keep);
|
|
692
|
+
|
|
693
|
+
out.push("", "## 9. やってはいけないこと", "");
|
|
694
|
+
out.push(...FORBID_COMMON, ...role.forbid);
|
|
695
|
+
|
|
696
|
+
if (role.verify) {
|
|
697
|
+
out.push("", "## 10. 検証", "");
|
|
698
|
+
out.push(...verifyLines(options.role));
|
|
699
|
+
}
|
|
700
|
+
|
|
701
|
+
out.push("", "## 11. 記録に書くこと", "");
|
|
702
|
+
out.push(recordLine(options.role, task.context_ref, workerRef));
|
|
703
|
+
|
|
704
|
+
out.push("", "## 12. 最終報告", "");
|
|
705
|
+
out.push(...reportLines(workerRef));
|
|
706
|
+
|
|
707
|
+
return `${out.join("\n").replace(/\n{3,}/g, "\n\n")}\n`;
|
|
708
|
+
}
|