@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/README.md
CHANGED
|
@@ -66,9 +66,9 @@ hub project help
|
|
|
66
66
|
hub infra help
|
|
67
67
|
```
|
|
68
68
|
|
|
69
|
-
動詞は `task` が `new` / `add` / `claim` / `next` / `show` / `report` / `note` / `list` / `audit`、
|
|
69
|
+
動詞は `task` が `new` / `add` / `claim` / `next` / `show` / `report` / `note` / `list` / `audit` / `brief`、
|
|
70
70
|
`project` が `list` / `show` / `create` / `update` / `move`、
|
|
71
|
-
`infra` が `list` / `show` / `update` / `link` / `unlink`。
|
|
71
|
+
`infra` が `list` / `show` / `update` / `note` / `link` / `unlink`。
|
|
72
72
|
**正確なオプションは常に `--help` を見る**(ここにも、スキルにも写経しない)。
|
|
73
73
|
全動詞が `--json` を受ける。機械が読むときは必ず `--json` を使い、人向けの整形を parse しない。
|
|
74
74
|
|
|
@@ -120,14 +120,47 @@ CLI が送る前に断る。
|
|
|
120
120
|
`parent: <slug>` の行を出す(`kind` と同じく**既定でないときだけ**出す流儀)。`show` は
|
|
121
121
|
配下の案件を `children:` の下に `- <slug> [<status>] <name>` で並べる。`--json` は応答そのまま。
|
|
122
122
|
|
|
123
|
+
### 依頼書(`hub task brief`)
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
hub task brief 180 --role implement --worker opus35
|
|
127
|
+
hub task brief 181 --role review --worker codex1 --commits "4803003 79410c1" --note-file 裁定.md
|
|
128
|
+
hub task brief 183 --role review --worker codex1 --out /tmp/brief-183.md --sandboxed
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
文脈ゼロの AI へ渡す依頼を Markdown 1 枚にまとめる。看板(本文・status・owner・直近の報告)、
|
|
132
|
+
案件(repo・リンク・デプロイ先・台帳)、作業ディレクトリの規約ファイルの場所を 1 コマンドで束ねる。
|
|
133
|
+
既定は stdout、`--out <path>` でファイルへ、`--json` は集めた素材をそのまま返す。
|
|
134
|
+
`--role` は `implement`(既定)/ `review` / `design` で定型部分が変わる。
|
|
135
|
+
|
|
136
|
+
3 つだけ性質を覚えておけばよい。
|
|
137
|
+
|
|
138
|
+
- **定型文は CLI の中にあり、repo の規約は写していない。** 依頼書は作業ディレクトリの
|
|
139
|
+
`AGENTS.md` / `CLAUDE.md` を「最初に読む」と指すだけで、検証コマンドもそちらへ送る。
|
|
140
|
+
- **看板の本文は全文が入る**ので、依頼書は `hub task show` を指さない。API に届かない相手には
|
|
141
|
+
`--out` のファイルだけを渡せばよい(`--sandboxed` を付けると、CLI を使わない・commit できなければ
|
|
142
|
+
ファイルに書くだけ・報告は依頼者が代行、の段落が入り、認証の行が消える)。
|
|
143
|
+
`--sandboxed` は明示するもので、**`--worker` の呼び名から環境を推測しない**。
|
|
144
|
+
- **台帳の口座欄(`account` / `account_ref` / `note` / `payer` / `holder`)は出ない。**
|
|
145
|
+
依頼に要らないので素材の段階で落としてあり、`--json` にも現れない。
|
|
146
|
+
`--out` のファイルの中身も、書く前に認証値の秘匿を通す。
|
|
147
|
+
|
|
148
|
+
`--out` は生成物なので既存ファイルを上書きするが、**git で追跡されているパスには書かない**
|
|
149
|
+
(記録や指示書の上に依頼書を書かないため)。`--commits` は自由文で、`--role review` で省くと
|
|
150
|
+
警告が出て「対象は依頼者から受け取る」と書かれる。案件が引けないときは案件の節を省いて警告し、
|
|
151
|
+
依頼書そのものは出す(看板が引けないときだけ何も出さない)。
|
|
152
|
+
|
|
123
153
|
### インフラ資産を読む・更新する
|
|
124
154
|
|
|
125
155
|
```bash
|
|
126
156
|
hub infra list # 自分で管理する資産だけ(既定)
|
|
127
157
|
hub infra list --management all # 他社管理を含む全件
|
|
128
158
|
hub infra show example.jp
|
|
129
|
-
hub infra update example.jp --status to_cancel --
|
|
159
|
+
hub infra update example.jp --status to_cancel --reason '11/30までに解約と決めた'
|
|
130
160
|
hub infra update example.jp --prod-platform none # 本番の置き場なし(確定値)
|
|
161
|
+
hub infra note example.jp --note 'Xserverのパネルで自動更新onを確認'
|
|
162
|
+
hub infra note example.jp --note-file /tmp/note.md
|
|
163
|
+
hub infra note example.jp --note '…' --operation-id 01M33H236V8MACB2DFR641ATK3 # 送り直し
|
|
131
164
|
hub infra link example.jp --project hub
|
|
132
165
|
hub infra unlink example.jp --project hub
|
|
133
166
|
hub infra unlink example.jp # 紐付けを全部外す
|
|
@@ -138,6 +171,28 @@ hub infra unlink example.jp # 紐付けを全部外す
|
|
|
138
171
|
1回だけ再試行する。`link` は現在の紐付けへ追加、`unlink` は指定分を削除し、APIへはどちらも
|
|
139
172
|
`PUT /:id/projects` の全置換として送る。
|
|
140
173
|
|
|
174
|
+
`note` は台帳の**経緯**を1件足す(`POST /:id/notes`)。資産の `version` を進めないので、
|
|
175
|
+
画面を開いたまま追記しても、そのあとの保存が競合しない。本文は2,000文字までで**分割しない**
|
|
176
|
+
(`hub task note` と違い、長い本文は要点へ縮める。旧メモの原文保管はCLIでは行わない)。
|
|
177
|
+
操作ID(ULID)は**1操作につき1つ**をCLIが作り、送信の前に決める。応答が返る前に通信が
|
|
178
|
+
切れた失敗だけ、**同じ操作IDで1回だけ**送り直す——届いていた場合はAPIがその操作IDを見て
|
|
179
|
+
既存のイベントを返すので、二重に積まれない。応答が返った失敗(400 / 409 など)は
|
|
180
|
+
サーバが答えているので再試行しない。
|
|
181
|
+
|
|
182
|
+
失敗すると `操作ID: <ULID>` を出す。後から送り直すときは、素で打ち直さず
|
|
183
|
+
`--operation-id <ULID>` にその値を渡す(素の打ち直しは別の操作IDになるので、
|
|
184
|
+
1回目が届いていた場合に2件積まれる)。
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
hub infra note example.jp --note '…' --operation-id 01M33H236V8MACB2DFR641ATK3
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`update --reason <text>` は**その更新の理由**(500文字まで)で、列ではなく監査イベントへ入る。
|
|
191
|
+
値の変更と一緒に指定する(理由だけの更新は400。経緯は `hub infra note`)。
|
|
192
|
+
**`--reason` を含む更新は409で自動再送しない**——理由は読んだ状態に依存するので、
|
|
193
|
+
最新を確認して書き直す。`--append-note` は**次の版で外す**(使うと stderr へ予告が出る)。
|
|
194
|
+
「現在の補足」を上書きする `--note` は残り、経緯は `note` 動詞へ分かれる。
|
|
195
|
+
|
|
141
196
|
`--dns-host` / `--mail-host` / `--migration-plan` / `--contract` / `--hosted-on-basis`は
|
|
142
197
|
`none`で未記入(`null`)へ戻せる。`--prod-platform none`だけは「本番の置き場は無い」という
|
|
143
198
|
確定済みのenum値を送り、未記入には戻さない。
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import { ApiError, withGuidance } from "../lib/api.mjs";
|
|
2
|
+
import { requireSinglePositional, usageError } from "../lib/args.mjs";
|
|
3
|
+
import { resolveInfraAssetId } from "../lib/infra.mjs";
|
|
4
|
+
import { newUlid } from "../lib/ulid.mjs";
|
|
5
|
+
|
|
6
|
+
/** APIの上限(`MAX_NOTE_TEXT`)と同じ。**分割しない**ので超えたら送らずに案内する。 */
|
|
7
|
+
export const INFRA_NOTE_LIMIT = 2_000;
|
|
8
|
+
|
|
9
|
+
/** 操作IDの形(`newUlid` が作る26文字のCrockford Base32)。`--operation-id` の受理判定。 */
|
|
10
|
+
const OPERATION_ID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* 通信の結果が**分からない**失敗か(codex2レビュー High 1)。
|
|
14
|
+
*
|
|
15
|
+
* `fetch` が応答を返す前に落ちた失敗は、「届いていない」と「届いたが応答を失った」の
|
|
16
|
+
* 区別が付かない。一方、応答が返った失敗——`ApiError`(4xx / 5xx)と「JSONでない応答」
|
|
17
|
+
* (`cliError` なので `code === "cli_error"`)——はサーバが答えているので、同じ本文を
|
|
18
|
+
* 打ち直しても同じ答えになる。再試行するのは前者だけ。
|
|
19
|
+
*/
|
|
20
|
+
function isUnknownOutcome(error) {
|
|
21
|
+
return !(error instanceof ApiError) && error?.code !== "cli_error";
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
function operationIdFrom(value) {
|
|
25
|
+
const id = String(value ?? "").trim().toUpperCase();
|
|
26
|
+
if (!OPERATION_ID_PATTERN.test(id)) {
|
|
27
|
+
throw usageError(
|
|
28
|
+
"--operation-id にはULID(26文字のCrockford Base32)を指定してください。"
|
|
29
|
+
+ "前回の失敗が出した「操作ID: …」の値をそのまま渡します",
|
|
30
|
+
);
|
|
31
|
+
}
|
|
32
|
+
return id;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* 失敗のときに**操作IDを必ず出す**(codex2レビュー High 1)。
|
|
37
|
+
*
|
|
38
|
+
* 届いたかどうか分からないまま素で打ち直すと別の操作IDになり、届いていた場合に2件積まれる。
|
|
39
|
+
* 人が同じ操作として送り直せるように、idと `--operation-id` の使い方を添える。
|
|
40
|
+
*/
|
|
41
|
+
function operationGuidance(operationId, unknownOutcome) {
|
|
42
|
+
const line = `操作ID: ${operationId}`;
|
|
43
|
+
if (!unknownOutcome) return line;
|
|
44
|
+
return `${line}\n`
|
|
45
|
+
+ "届いたかどうかは分かりません(応答の前に通信が切れ、同じ操作IDでの再送も失敗しました)。\n"
|
|
46
|
+
+ `送り直すときは --operation-id ${operationId} を付けてください(届いていれば二重に積まれません)。`;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* 同じ操作ID・同じbodyで最大2回送る(codex2レビュー High 1)。
|
|
51
|
+
*
|
|
52
|
+
* 2回目を送るのは**結果が不明な失敗**のときだけ。1回目がD1へ届いていた場合は、
|
|
53
|
+
* APIが同じ操作IDを見て200で既存のイベントを返す(`NOT EXISTS` のガード)ので、
|
|
54
|
+
* 2件目は積まれない。
|
|
55
|
+
*/
|
|
56
|
+
async function postNote(api, assetId, init, operationId) {
|
|
57
|
+
const requestPath = `/api/infra/assets/${encodeURIComponent(assetId)}/notes`;
|
|
58
|
+
try {
|
|
59
|
+
return await api(requestPath, init);
|
|
60
|
+
} catch (error) {
|
|
61
|
+
if (!isUnknownOutcome(error)) throw withGuidance(error, operationGuidance(operationId, false));
|
|
62
|
+
try {
|
|
63
|
+
return await api(requestPath, init);
|
|
64
|
+
} catch (retryError) {
|
|
65
|
+
throw withGuidance(retryError, operationGuidance(operationId, isUnknownOutcome(retryError)));
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* 経緯を1件足す(記録188 §3.5)。
|
|
72
|
+
*
|
|
73
|
+
* `hub task note` と違って**分割しない**。看板のnoteは同じタスクに何件積んでも読めるが、
|
|
74
|
+
* 台帳の経緯は「1件=1つの事実」で読むもので、機械的に切ると意味の単位が壊れる。
|
|
75
|
+
* 長すぎるものは人が要点へ縮める(原文の保管は `legacy_note`=便Dの口の仕事)。
|
|
76
|
+
*
|
|
77
|
+
* 操作IDは**1操作につき1回だけ**作り、再試行でも使い回す。同じidの再送はAPIが200で
|
|
78
|
+
* 既存イベントを返すので、通信が切れて結果が分からないときも二重に積まれない。
|
|
79
|
+
* 人が後から送り直すときは `--operation-id <ULID>`(失敗時のメッセージに出る)。
|
|
80
|
+
*/
|
|
81
|
+
export const infraNoteCommand = {
|
|
82
|
+
name: "note",
|
|
83
|
+
options: { allowed: ["note", "note-file", "operation-id"] },
|
|
84
|
+
async run({ options, positional, flags, dependencies, api }) {
|
|
85
|
+
const reference = requireSinglePositional(positional, "資産名またはid");
|
|
86
|
+
if (flags.note && flags["note-file"]) throw usageError("--note と --note-file は同時に指定できません");
|
|
87
|
+
const source = flags["note-file"]
|
|
88
|
+
? await dependencies.readFileImpl(options["note-file"], "utf8")
|
|
89
|
+
: options.note;
|
|
90
|
+
const text = String(source ?? "").trim();
|
|
91
|
+
if (text === "") throw usageError("--note か --note-file を指定してください");
|
|
92
|
+
if (text.length > INFRA_NOTE_LIMIT) {
|
|
93
|
+
throw usageError(
|
|
94
|
+
`経緯は${INFRA_NOTE_LIMIT}文字までです(${text.length}文字)。`
|
|
95
|
+
+ "分割せずに要点へ縮めてください(旧メモの原文保管はCLIでは行いません)",
|
|
96
|
+
);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// 操作IDは**送信の外で1回だけ**決める。POSTの直前で作ると、応答を失った1回目と
|
|
100
|
+
// 2回目が別のidになり、届いていた場合に2件積まれる(codex2レビュー High 1)
|
|
101
|
+
const operationId = flags["operation-id"] ? operationIdFrom(options["operation-id"]) : newUlid();
|
|
102
|
+
|
|
103
|
+
const id = await resolveInfraAssetId(reference, api);
|
|
104
|
+
const payload = await postNote(api, id, {
|
|
105
|
+
method: "POST",
|
|
106
|
+
body: JSON.stringify({ id: operationId, text }),
|
|
107
|
+
}, operationId);
|
|
108
|
+
if (options.json) {
|
|
109
|
+
dependencies.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
|
|
110
|
+
return;
|
|
111
|
+
}
|
|
112
|
+
dependencies.stdout.write(`経緯を1件追加しました(${payload?.event?.id ?? "-"})。\n`);
|
|
113
|
+
},
|
|
114
|
+
};
|
|
@@ -30,7 +30,22 @@ const OPTION_FIELDS = {
|
|
|
30
30
|
"hosted-on-basis": "hosted_on_basis",
|
|
31
31
|
};
|
|
32
32
|
|
|
33
|
-
const ALLOWED_OPTIONS = [...Object.keys(OPTION_FIELDS), "append-note", "hosted-on"];
|
|
33
|
+
const ALLOWED_OPTIONS = [...Object.keys(OPTION_FIELDS), "append-note", "hosted-on", "reason"];
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* `--append-note` は次の版で外す(記録188 §3.5)。既存noteの末尾へ「 / 」で足す作りは、
|
|
37
|
+
* 「現在の補足」と「経緯」を1つの列に混ぜる——経緯は `hub infra note` が別の表へ積む。
|
|
38
|
+
* 打つたびに出す(1回だけの告知だと、使い続けている人には届かない)。
|
|
39
|
+
*/
|
|
40
|
+
const APPEND_NOTE_DEPRECATION =
|
|
41
|
+
"警告: --append-note は次の版で外します。経緯は hub infra note <name|id> --note <text> へ。\n";
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* 理由は**読んだ状態に依存する**ので、409で自動的に取り直して再送しない(所見 Medium 2)。
|
|
45
|
+
* 「A を B にした理由」を書いたあとに他人が A を C へ変えていたら、その理由はもう合わない。
|
|
46
|
+
*/
|
|
47
|
+
const REASON_CONFLICT_GUIDANCE =
|
|
48
|
+
"理由つきの更新は自動で再送しません。最新の内容を確認し、理由を書き直してからもう一度実行してください";
|
|
34
49
|
const NULLABLE_VALUE_OPTIONS = new Set([
|
|
35
50
|
"dns-host",
|
|
36
51
|
"mail-host",
|
|
@@ -47,12 +62,13 @@ function amountValue(value) {
|
|
|
47
62
|
return parsed;
|
|
48
63
|
}
|
|
49
64
|
|
|
50
|
-
function bodyFor(current, prepared, appendNote) {
|
|
65
|
+
function bodyFor(current, prepared, appendNote, reason) {
|
|
51
66
|
const body = { version: requireInfraVersion(current), ...prepared };
|
|
52
67
|
if (appendNote !== null) {
|
|
53
68
|
const note = typeof current.note === "string" ? current.note.trim() : "";
|
|
54
69
|
body.note = note === "" ? appendNote : `${note} / ${appendNote}`;
|
|
55
70
|
}
|
|
71
|
+
if (reason !== null) body.reason = reason;
|
|
56
72
|
return body;
|
|
57
73
|
}
|
|
58
74
|
|
|
@@ -67,6 +83,16 @@ export const infraUpdateCommand = {
|
|
|
67
83
|
if (flags.note && flags["append-note"]) {
|
|
68
84
|
throw usageError("--note と --append-note は同時に指定できません");
|
|
69
85
|
}
|
|
86
|
+
// 理由だけの更新はAPIが400にする(経緯は `hub infra note`)。往復する前にここで案内する
|
|
87
|
+
let reason = null;
|
|
88
|
+
if (flags.reason) {
|
|
89
|
+
if (!ALLOWED_OPTIONS.some((name) => name !== "reason" && flags[name])) {
|
|
90
|
+
throw usageError("--reason は値の変更と一緒に指定してください(経緯だけを足すときは hub infra note)");
|
|
91
|
+
}
|
|
92
|
+
reason = options.reason.trim();
|
|
93
|
+
if (reason === "") throw usageError("--reason に空文字は指定できません");
|
|
94
|
+
}
|
|
95
|
+
if (flags["append-note"]) dependencies.stderr.write(APPEND_NOTE_DEPRECATION);
|
|
70
96
|
|
|
71
97
|
let currentPayload = await getInfraAsset(reference, api);
|
|
72
98
|
let current = currentPayload.item;
|
|
@@ -107,12 +133,15 @@ export const infraUpdateCommand = {
|
|
|
107
133
|
try {
|
|
108
134
|
const payload = await api(`/api/infra/assets/${encodeURIComponent(current.id)}`, {
|
|
109
135
|
method: "PATCH",
|
|
110
|
-
body: JSON.stringify(bodyFor(current, prepared, appendNote)),
|
|
136
|
+
body: JSON.stringify(bodyFor(current, prepared, appendNote, reason)),
|
|
111
137
|
});
|
|
112
138
|
printInfraResult(payload, options.json, dependencies.stdout, "update");
|
|
113
139
|
return;
|
|
114
140
|
} catch (error) {
|
|
115
141
|
if (!isConflictError(error)) throw error;
|
|
142
|
+
// 理由つきは取り直して送り直さない。**書いた理由が古い前提のままになる**ので、
|
|
143
|
+
// 人が最新を読んで理由を書き直す(所見 Medium 2・記録188 §3.5)
|
|
144
|
+
if (reason !== null) throw withGuidance(error, REASON_CONFLICT_GUIDANCE);
|
|
116
145
|
if (attempt === 1) {
|
|
117
146
|
throw withGuidance(error, "再取得後にも競合しました。最新の内容を確認してから、もう一度実行してください");
|
|
118
147
|
}
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
|
|
3
|
+
import { cliError, requireSinglePositional, usageError } from "../lib/args.mjs";
|
|
4
|
+
import {
|
|
5
|
+
BRIEF_ROLES,
|
|
6
|
+
WORKER_PATTERN,
|
|
7
|
+
collectBrief,
|
|
8
|
+
redactAccountIds,
|
|
9
|
+
renderBrief,
|
|
10
|
+
} from "../lib/brief.mjs";
|
|
11
|
+
import { packageVersion } from "../lib/version.mjs";
|
|
12
|
+
import { findRepoRoot } from "../lib/records.mjs";
|
|
13
|
+
import { resolveTaskIdArg } from "../lib/task-ref.mjs";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* 存在する祖先まで遡って `realpath` を当て、無い分を繋ぎ直す。
|
|
17
|
+
*
|
|
18
|
+
* これから作るディレクトリは `realpath` できない(ENOENT)ので、途中で諦めると
|
|
19
|
+
* **symlink を含む祖先が未解決のまま残る**。解決できた実体に未作成分を足せば、
|
|
20
|
+
* 「後で mkdir されるのは実体の下」という書き込みの実態と一致する。
|
|
21
|
+
*/
|
|
22
|
+
async function realDirectory(dir, realpathImpl) {
|
|
23
|
+
const missing = [];
|
|
24
|
+
let current = dir;
|
|
25
|
+
for (;;) {
|
|
26
|
+
try {
|
|
27
|
+
return path.join(await realpathImpl(current), ...missing);
|
|
28
|
+
} catch {
|
|
29
|
+
const parent = path.dirname(current);
|
|
30
|
+
if (parent === current) return dir;
|
|
31
|
+
missing.unshift(path.basename(current));
|
|
32
|
+
current = parent;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* `--out` の書き先を決める(指示書 §7・便1 レビュー High)。
|
|
39
|
+
*
|
|
40
|
+
* 依頼書は生成物なので**既存ファイルは上書きしてよい**。ただし **git で追跡されているパスは
|
|
41
|
+
* 拒否する** ——「依頼書を作る」つもりで記録や指示書を潰すのが一番痛い事故で、追跡の有無は
|
|
42
|
+
* その2つをほぼそのまま言い当てる。git が動かない環境では拒否せず警告に留める
|
|
43
|
+
* (追跡を確かめられないだけで書けなくなる方が困る)。
|
|
44
|
+
*
|
|
45
|
+
* **検査は字面ではなく実体に対して行う。** `stat` と `writeFile` は symlink を追うのに
|
|
46
|
+
* `git ls-files` は渡した綴りしか見ないので、repo 内の未追跡 symlink(や symlink の親)から
|
|
47
|
+
* 追跡中の記録を指せば、追跡検査をすり抜けて実体を上書きできた。そこで
|
|
48
|
+
* **最終要素が symlink なら拒否**し、親は `realpath` で解いてから追跡検査する
|
|
49
|
+
* (repo root も実体側から探し直す。symlink が別の repo を指していることもある)。
|
|
50
|
+
*
|
|
51
|
+
* 検査は**API を呼ぶ前**に済ませる。書けないと分かっているのに看板を引いて依頼書を組むと、
|
|
52
|
+
* 失敗の直前まで走って何も残らない。
|
|
53
|
+
*/
|
|
54
|
+
async function prepareOutPath(out, dependencies) {
|
|
55
|
+
const requested = path.resolve(dependencies.cwd(), out);
|
|
56
|
+
try {
|
|
57
|
+
const entry = await dependencies.lstatImpl(requested);
|
|
58
|
+
if (entry?.isSymbolicLink?.() === true) {
|
|
59
|
+
throw cliError(
|
|
60
|
+
`${requested} は symlink なので依頼書を書けません(リンク先が追跡ファイルでないか確かめて、実体のパスを指定してください)`,
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
if (entry?.isDirectory?.() === true) {
|
|
64
|
+
throw usageError(`--out にはファイル名を指定してください(ディレクトリです): ${requested}`);
|
|
65
|
+
}
|
|
66
|
+
} catch (error) {
|
|
67
|
+
if (error?.code === "cli_error") throw error;
|
|
68
|
+
// 存在しないのは正常(これから書く)
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const absolute = path.join(
|
|
72
|
+
await realDirectory(path.dirname(requested), dependencies.realpathImpl),
|
|
73
|
+
path.basename(requested),
|
|
74
|
+
);
|
|
75
|
+
|
|
76
|
+
const root = await findRepoRoot(path.dirname(absolute), dependencies.statImpl);
|
|
77
|
+
if (root === null) return absolute;
|
|
78
|
+
const relative = path.relative(root, absolute).split(path.sep).join("/");
|
|
79
|
+
if (relative === "" || relative.startsWith("../")) return absolute;
|
|
80
|
+
|
|
81
|
+
// `--error-unmatch` は使わない。終了コードが「追跡されていない」と「git を実行できない」を
|
|
82
|
+
// 区別できず、fail-open(git が無ければ書く)の契約を保てないため、出力の有無で見る。
|
|
83
|
+
const result = await dependencies.runGitImpl(
|
|
84
|
+
["-c", "core.quotepath=false", "ls-files", "-z", "--", relative],
|
|
85
|
+
{ cwd: root },
|
|
86
|
+
);
|
|
87
|
+
if (result?.ok === false) {
|
|
88
|
+
dependencies.stderr.write(`警告: git を実行できないため --out の追跡検査を省きました: ${relative}\n`);
|
|
89
|
+
return absolute;
|
|
90
|
+
}
|
|
91
|
+
if (String(result?.stdout ?? "") !== "") {
|
|
92
|
+
throw cliError(
|
|
93
|
+
`${relative} は git で追跡されているので依頼書を書けません(記録や指示書の上に書かないため)`,
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
return absolute;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
export const taskBriefCommand = {
|
|
100
|
+
name: "brief",
|
|
101
|
+
options: {
|
|
102
|
+
allowed: ["role", "worker", "commits", "note", "note-file", "out", "sandboxed"],
|
|
103
|
+
boolean: ["sandboxed"],
|
|
104
|
+
},
|
|
105
|
+
async run({ options, positional, flags, dependencies, api }) {
|
|
106
|
+
const ref = requireSinglePositional(positional, "タスクID");
|
|
107
|
+
|
|
108
|
+
// 語彙と形の誤りは**APIを呼ぶ前**に落とす(往復してから気づくより速い)
|
|
109
|
+
const role = options.role ?? "implement";
|
|
110
|
+
if (!BRIEF_ROLES.includes(role)) {
|
|
111
|
+
throw usageError(`--role は ${BRIEF_ROLES.join(" / ")} のいずれかです: ${role}`);
|
|
112
|
+
}
|
|
113
|
+
const worker = options.worker ?? null;
|
|
114
|
+
if (worker !== null && !WORKER_PATTERN.test(worker)) {
|
|
115
|
+
throw usageError("--worker は英小文字・数字・ハイフンの呼び名です(HUB_ACTOR と同じ形)");
|
|
116
|
+
}
|
|
117
|
+
// **値ではなく指定の有無で見る**(`--note= --note-file=x.md` も同時指定である)
|
|
118
|
+
if (flags.note && flags["note-file"]) {
|
|
119
|
+
throw usageError("--note と --note-file は同時に指定できません");
|
|
120
|
+
}
|
|
121
|
+
const noteSource = options["note-file"]
|
|
122
|
+
? await dependencies.readFileImpl(options["note-file"], "utf8")
|
|
123
|
+
: options.note;
|
|
124
|
+
if (flags.note || flags["note-file"]) {
|
|
125
|
+
if (!noteSource?.trim()) throw usageError("--note / --note-file が空です");
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const outPath = flags.out ? await prepareOutPath(options.out, dependencies) : null;
|
|
129
|
+
|
|
130
|
+
const id = await resolveTaskIdArg(ref, api, dependencies);
|
|
131
|
+
const material = await collectBrief({
|
|
132
|
+
ref,
|
|
133
|
+
id,
|
|
134
|
+
api,
|
|
135
|
+
dependencies,
|
|
136
|
+
version: await packageVersion(),
|
|
137
|
+
options: {
|
|
138
|
+
role,
|
|
139
|
+
worker,
|
|
140
|
+
commits: options.commits ?? null,
|
|
141
|
+
note: noteSource?.trim() ? noteSource : null,
|
|
142
|
+
noteFile: options["note-file"] ?? null,
|
|
143
|
+
sandboxed: flags.sandboxed === true,
|
|
144
|
+
},
|
|
145
|
+
});
|
|
146
|
+
for (const warning of material.warnings) dependencies.stderr.write(`警告: ${warning}\n`);
|
|
147
|
+
|
|
148
|
+
// **依頼書の出口はこの2行だけ**(Markdown / `--json` / `--out` のどれもここを通る)。
|
|
149
|
+
// アカウント ID の秘匿を経路ごとに書くと、出力を足したときに通し忘れる(資格情報の秘匿を
|
|
150
|
+
// `runCli` の出口1か所に寄せてあるのと同じ理屈)。
|
|
151
|
+
const markdown = redactAccountIds(renderBrief(material));
|
|
152
|
+
const json = options.json ? redactAccountIds(`${JSON.stringify(material, null, 2)}\n`) : null;
|
|
153
|
+
|
|
154
|
+
if (outPath !== null) {
|
|
155
|
+
// `--out` は `runCli` の `redactSecrets` を通らない経路なので、資格情報の秘匿も自分で通す
|
|
156
|
+
await dependencies.mkdirImpl(path.dirname(outPath), { recursive: true });
|
|
157
|
+
await dependencies.writeFileImpl(outPath, dependencies.redact(markdown), "utf8");
|
|
158
|
+
dependencies.stderr.write(`依頼書を書きました: ${outPath}\n`);
|
|
159
|
+
if (json !== null) dependencies.stdout.write(json);
|
|
160
|
+
return;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
dependencies.stdout.write(json ?? markdown);
|
|
164
|
+
},
|
|
165
|
+
};
|
package/lib/args.mjs
CHANGED
|
@@ -49,6 +49,8 @@ export const TASK_USAGE = `使い方:
|
|
|
49
49
|
[--repo-card [<dir>]] [--slug <slug>] [--force] [--json]
|
|
50
50
|
hub task list [--status <s>] [--project <name>] [--owner <name>] [--q <text>] [--json]
|
|
51
51
|
hub task audit [--json]
|
|
52
|
+
hub task brief <id> [--role implement|review|design] [--worker <name>] [--commits <range>]
|
|
53
|
+
[--note <text> | --note-file <path>] [--out <path>] [--sandboxed] [--json]
|
|
52
54
|
|
|
53
55
|
show / claim / report / note の <id> には記録番号(150 / #150)も指定できる(context_ref が docs/records/150-… のタスクを一覧から引く。番号はrepoごとの採番なので、複数一致は作業ツリーに記録ファイルがある1件で割る。0件・それでも割れない複数一致はエラー)。
|
|
54
56
|
hub task new は「D1へ起票 → repoに記録の雛形を作成 → context_ref で紐付け」を1コマンドで行う。
|
|
@@ -57,6 +59,9 @@ hub task new は「D1へ起票 → repoに記録の雛形を作成 → context_r
|
|
|
57
59
|
--repo-card で題名からslugを作れない場合は、3文字以上のkebab-caseで --slug <slug> が必要(例: --slug project-detail-pc-layout)。
|
|
58
60
|
hub task audit は done のタスクの context_ref を git と突き合わせ、記録が未コミット・
|
|
59
61
|
未pushのまま done になっていないかを見る(「doneなのに本番に無い」の検出)。
|
|
62
|
+
hub task brief は文脈ゼロのAIへ渡す依頼書をMarkdownで出す。既定はstdout。
|
|
63
|
+
--out はファイルへ書く(生成物なので上書きするが、gitで追跡されているパスには書かない)。
|
|
64
|
+
--sandboxed はAPIに届かない・commitできない環境向けの段落を足す(--workerの名前からは推測しない)。
|
|
60
65
|
-- 以降はすべて位置引数になる。-- で始まるタイトルは hub task new --project hub -- "--で始まる題" の順で渡す。
|
|
61
66
|
オプションは --name=value の形でも書ける。値が -- で始まるとき(例 --note='--- 見出し')はこの形で渡す。
|
|
62
67
|
report / note の長文は約2000字ごとに分割して送る。途中で失敗すると「n件中m件まで送信済み」と出る。
|
|
@@ -113,7 +118,10 @@ export const INFRA_USAGE = `使い方:
|
|
|
113
118
|
[--account <text>] [--account-ref <text>]
|
|
114
119
|
[--note <text>] [--append-note <text>]
|
|
115
120
|
[--hosted-on <server name|id>|none]
|
|
116
|
-
[--hosted-on-basis <value>|none]
|
|
121
|
+
[--hosted-on-basis <value>|none]
|
|
122
|
+
[--reason <text>] [--json]
|
|
123
|
+
hub infra note <name|id> (--note <text> | --note-file <path>)
|
|
124
|
+
[--operation-id <ULID>] [--json]
|
|
117
125
|
hub infra link <name|id> --project <slug> [--project <slug>]... [--json]
|
|
118
126
|
hub infra unlink <name|id> [--project <slug>]... [--json]
|
|
119
127
|
|
|
@@ -121,7 +129,17 @@ export const INFRA_USAGE = `使い方:
|
|
|
121
129
|
list の --status はカンマ区切りで複数指定できる。
|
|
122
130
|
show / update / link / unlink の資産は名前の完全一致またはidで指定する。
|
|
123
131
|
update は指定した項目だけを更新する。version競合時は最新を取り直して1回だけ再試行する。
|
|
124
|
-
--
|
|
132
|
+
--reason は更新の理由(500文字まで)。値の変更と一緒に指定する(理由だけの更新はできない)。
|
|
133
|
+
**--reason を含む更新は409で自動再送しない**(理由は読んだ状態に依存するため、
|
|
134
|
+
最新を確認して書き直す)。
|
|
135
|
+
--append-note は既存noteの末尾へ「 / 」で追記する。**次の版で外す**(経緯は note へ)。
|
|
136
|
+
note は台帳の経緯を1件足す(2,000文字まで・分割しない)。noteは資産のversionを進めない
|
|
137
|
+
ので、シートを開いたまま追記しても、その後の保存が競合しない。
|
|
138
|
+
--note-file はファイルの中身をそのまま1件として送る(超過分は切らずにエラーにする)。
|
|
139
|
+
note の操作IDは1操作につき1つ。応答の前に通信が切れた失敗だけ、**同じIDで1回だけ**
|
|
140
|
+
送り直す(届いていればAPIが既存のイベントを返すので二重に積まれない)。
|
|
141
|
+
失敗すると「操作ID: …」を出すので、後から送り直すときは --operation-id <ULID> に
|
|
142
|
+
その値を渡す(素で打ち直すと別の操作になり、届いていた場合は2件積まれる)。
|
|
125
143
|
server資産には dns-host / mail-host / migration-plan / hosted-on / hosted-on-basis /
|
|
126
144
|
prod-platform / prod-ref を指定できない。
|
|
127
145
|
link は現在の紐付けへ追加し、unlink は指定分を外す。unlink の --project 省略は全解除。
|
|
@@ -130,11 +148,11 @@ export const INFRA_USAGE = `使い方:
|
|
|
130
148
|
`;
|
|
131
149
|
|
|
132
150
|
export const USAGE = `使い方:
|
|
133
|
-
hub task <verb> ... タスク操作(new / add / claim / next / show / report / note / list)
|
|
151
|
+
hub task <verb> ... タスク操作(new / add / claim / next / show / report / note / list / brief)
|
|
134
152
|
hub task help
|
|
135
153
|
hub project <verb> ... プロジェクト操作(list / show / create / update / move)
|
|
136
154
|
hub project help
|
|
137
|
-
hub infra <verb> ... インフラ資産操作(list / show / update / link / unlink)
|
|
155
|
+
hub infra <verb> ... インフラ資産操作(list / show / update / note / link / unlink)
|
|
138
156
|
hub infra help
|
|
139
157
|
hub --version 入っているCLIの版を出す(hub version も同じ)
|
|
140
158
|
|