@pecot/workflow-mcp 5.0.0 → 6.0.0

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.
Files changed (176) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +80 -22
  3. package/cli/dist/cli.js +6 -1
  4. package/cli/dist/commands/board-add.d.ts +3 -0
  5. package/cli/dist/commands/board-add.js +59 -0
  6. package/cli/dist/commands/board-judgment.d.ts +60 -0
  7. package/cli/dist/commands/board-judgment.js +144 -0
  8. package/cli/dist/commands/board-move.d.ts +3 -0
  9. package/cli/dist/commands/board-move.js +57 -0
  10. package/cli/dist/commands/board-readiness.d.ts +34 -0
  11. package/cli/dist/commands/board-readiness.js +108 -0
  12. package/cli/dist/commands/board-show.d.ts +3 -0
  13. package/cli/dist/commands/board-show.js +72 -0
  14. package/cli/dist/commands/board-sync.d.ts +3 -0
  15. package/cli/dist/commands/board-sync.js +111 -0
  16. package/cli/dist/commands/{project-info.d.ts → board-view.d.ts} +21 -7
  17. package/cli/dist/commands/{project-info.js → board-view.js} +22 -12
  18. package/cli/dist/commands/board.d.ts +3 -0
  19. package/cli/dist/commands/board.js +12 -0
  20. package/cli/dist/commands/branch.d.ts +3 -0
  21. package/cli/dist/commands/branch.js +100 -0
  22. package/cli/dist/commands/command-binding.js +4 -0
  23. package/cli/dist/commands/command-definition.d.ts +20 -6
  24. package/cli/dist/commands/command-definition.js +11 -7
  25. package/cli/dist/commands/command-help.js +2 -2
  26. package/cli/dist/commands/command-hint.d.ts +5 -0
  27. package/cli/dist/commands/command-hint.js +13 -0
  28. package/cli/dist/commands/command-stop.d.ts +5 -3
  29. package/cli/dist/commands/command-stop.js +7 -6
  30. package/cli/dist/commands/failure-kind.d.ts +3 -0
  31. package/cli/dist/commands/failure-kind.js +34 -0
  32. package/cli/dist/commands/failure.d.ts +6 -0
  33. package/cli/dist/commands/failure.js +29 -3
  34. package/cli/dist/commands/github-client.d.ts +6 -2
  35. package/cli/dist/commands/github-client.js +13 -3
  36. package/cli/dist/commands/help.js +8 -13
  37. package/cli/dist/commands/issue-board.d.ts +33 -0
  38. package/cli/dist/commands/issue-board.js +61 -1
  39. package/cli/dist/commands/issue-comment.js +47 -28
  40. package/cli/dist/commands/issue-create.js +548 -91
  41. package/cli/dist/commands/issue-dependency.d.ts +3 -0
  42. package/cli/dist/commands/issue-dependency.js +282 -0
  43. package/cli/dist/commands/issue-readiness.d.ts +94 -0
  44. package/cli/dist/commands/issue-readiness.js +218 -0
  45. package/cli/dist/commands/issue-reopen.d.ts +3 -0
  46. package/cli/dist/commands/issue-reopen.js +115 -0
  47. package/cli/dist/commands/issue-shared.d.ts +32 -19
  48. package/cli/dist/commands/issue-shared.js +82 -75
  49. package/cli/dist/commands/issue-show.d.ts +3 -0
  50. package/cli/dist/commands/issue-show.js +169 -0
  51. package/cli/dist/commands/issue.d.ts +0 -1
  52. package/cli/dist/commands/issue.js +6 -8
  53. package/cli/dist/commands/names.d.ts +33 -0
  54. package/cli/dist/commands/names.js +62 -0
  55. package/cli/dist/commands/output.d.ts +14 -2
  56. package/cli/dist/commands/output.js +14 -7
  57. package/cli/dist/commands/pr-waiting.d.ts +20 -0
  58. package/cli/dist/commands/pr-waiting.js +106 -0
  59. package/cli/dist/commands/pr.d.ts +19 -0
  60. package/cli/dist/commands/pr.js +242 -323
  61. package/cli/dist/commands/project-sync.d.ts +2 -1
  62. package/cli/dist/commands/project-sync.js +18 -9
  63. package/cli/dist/commands/project.d.ts +3 -2
  64. package/cli/dist/commands/project.js +212 -175
  65. package/cli/dist/commands/registry.js +13 -10
  66. package/cli/dist/commands/release.d.ts +2 -2
  67. package/cli/dist/commands/release.js +53 -114
  68. package/cli/dist/commands/renamed-commands.d.ts +26 -0
  69. package/cli/dist/commands/renamed-commands.js +53 -0
  70. package/cli/dist/commands/repository-match.js +3 -2
  71. package/cli/dist/commands/session-finish.d.ts +3 -0
  72. package/cli/dist/commands/session-finish.js +267 -0
  73. package/cli/dist/commands/session-start.d.ts +3 -0
  74. package/cli/dist/commands/{repository.js → session-start.js} +99 -128
  75. package/cli/dist/commands/session.d.ts +3 -0
  76. package/cli/dist/commands/session.js +82 -29
  77. package/cli/dist/commands/tracker-sync-dependabot.d.ts +7 -0
  78. package/cli/dist/commands/{dependabot.js → tracker-sync-dependabot.js} +57 -66
  79. package/cli/dist/commands/tracker-sync-security.d.ts +7 -0
  80. package/cli/dist/commands/{security.js → tracker-sync-security.js} +50 -61
  81. package/cli/dist/commands/tracker-sync.d.ts +7 -0
  82. package/cli/dist/commands/tracker-sync.js +3 -6
  83. package/cli/dist/commands/tracker.d.ts +3 -0
  84. package/cli/dist/commands/tracker.js +18 -0
  85. package/cli/dist/commands/usage-error.d.ts +4 -0
  86. package/cli/dist/commands/usage-error.js +6 -0
  87. package/cli/dist/commands/work-target.d.ts +12 -3
  88. package/cli/dist/commands/work-target.js +46 -5
  89. package/cli/dist/commands/worktree.js +32 -28
  90. package/cli/dist/domain/batch-plan.d.ts +73 -0
  91. package/cli/dist/domain/batch-plan.js +114 -0
  92. package/cli/dist/domain/blocked-by-change.d.ts +99 -0
  93. package/cli/dist/domain/blocked-by-change.js +101 -0
  94. package/cli/dist/domain/board-move.d.ts +90 -0
  95. package/cli/dist/domain/board-move.js +92 -0
  96. package/cli/dist/domain/branch-name.js +1 -1
  97. package/cli/dist/domain/command-hint.d.ts +85 -0
  98. package/cli/dist/domain/command-hint.js +148 -0
  99. package/cli/dist/domain/config.d.ts +4 -0
  100. package/cli/dist/domain/config.js +11 -1
  101. package/cli/dist/domain/dependabot.js +1 -1
  102. package/cli/dist/domain/errors.d.ts +5 -0
  103. package/cli/dist/domain/errors.js +5 -0
  104. package/cli/dist/domain/format.d.ts +51 -4
  105. package/cli/dist/domain/format.js +72 -6
  106. package/cli/dist/domain/frontmatter.d.ts +18 -3
  107. package/cli/dist/domain/frontmatter.js +38 -12
  108. package/cli/dist/domain/issue-order.d.ts +55 -0
  109. package/cli/dist/domain/issue-order.js +65 -0
  110. package/cli/dist/domain/issue-readout.d.ts +36 -0
  111. package/cli/dist/domain/pull-request.d.ts +71 -4
  112. package/cli/dist/domain/pull-request.js +59 -10
  113. package/cli/dist/domain/readiness.d.ts +27 -0
  114. package/cli/dist/domain/readiness.js +114 -3
  115. package/cli/dist/domain/reference-parser.d.ts +3 -1
  116. package/cli/dist/domain/reference-parser.js +6 -2
  117. package/cli/dist/domain/release.d.ts +7 -3
  118. package/cli/dist/domain/release.js +5 -12
  119. package/cli/dist/domain/repository-policy.d.ts +9 -3
  120. package/cli/dist/domain/repository-policy.js +8 -7
  121. package/cli/dist/domain/repository-resolver.js +4 -1
  122. package/cli/dist/domain/security-alerts.js +1 -1
  123. package/cli/dist/domain/state.d.ts +30 -0
  124. package/cli/dist/domain/state.js +39 -0
  125. package/cli/dist/domain/work-start.d.ts +34 -0
  126. package/cli/dist/domain/work-start.js +49 -0
  127. package/cli/dist/infra/authored-notes.d.ts +1 -1
  128. package/cli/dist/infra/authored-notes.js +10 -4
  129. package/cli/dist/infra/config-store.d.ts +4 -0
  130. package/cli/dist/infra/config-store.js +13 -0
  131. package/cli/dist/infra/git.d.ts +12 -0
  132. package/cli/dist/infra/git.js +13 -1
  133. package/cli/dist/infra/github/client.d.ts +5 -0
  134. package/cli/dist/infra/github/client.js +10 -7
  135. package/cli/dist/infra/github/errors.d.ts +18 -0
  136. package/cli/dist/infra/github/errors.js +22 -0
  137. package/cli/dist/infra/github/issues.d.ts +39 -3
  138. package/cli/dist/infra/github/issues.js +178 -23
  139. package/cli/dist/infra/github/projects.d.ts +35 -0
  140. package/cli/dist/infra/github/projects.js +89 -8
  141. package/cli/dist/infra/github/pulls.d.ts +24 -0
  142. package/cli/dist/infra/github/pulls.js +56 -0
  143. package/cli/dist/infra/github/queries.d.ts +12 -4
  144. package/cli/dist/infra/github/queries.js +156 -8
  145. package/cli/dist/infra/github/readout.d.ts +5 -1
  146. package/cli/dist/infra/github/readout.js +11 -0
  147. package/cli/dist/infra/github/repos.d.ts +18 -0
  148. package/cli/dist/infra/github/repos.js +31 -0
  149. package/cli/dist/infra/nx-scope.d.ts +1 -1
  150. package/cli/dist/infra/nx-scope.js +1 -1
  151. package/cli/dist/infra/state-store.d.ts +10 -1
  152. package/cli/dist/infra/state-store.js +14 -2
  153. package/cli/dist/infra/worktree-links.d.ts +3 -0
  154. package/cli/dist/infra/worktree-links.js +8 -1
  155. package/cli/dist/infra/worktree.d.ts +12 -1
  156. package/cli/dist/infra/worktree.js +40 -23
  157. package/cli/dist/mcp/result.d.ts +34 -6
  158. package/cli/dist/mcp/result.js +62 -18
  159. package/cli/dist/mcp/server.d.ts +2 -2
  160. package/cli/dist/mcp/server.js +24 -10
  161. package/cli/templates/comment/plan.md +14 -0
  162. package/cli/templates/issue/bug.md +1 -1
  163. package/cli/templates/issue/task-implement.md +13 -6
  164. package/cli/templates/issue/task.md +1 -1
  165. package/cli/templates/workflow/pecot-board-sync.yml +84 -0
  166. package/npm-shrinkwrap.json +2 -2
  167. package/package.json +1 -1
  168. package/cli/dist/commands/dependabot.d.ts +0 -3
  169. package/cli/dist/commands/issue-project.d.ts +0 -3
  170. package/cli/dist/commands/issue-project.js +0 -176
  171. package/cli/dist/commands/issue-quick.d.ts +0 -3
  172. package/cli/dist/commands/issue-quick.js +0 -126
  173. package/cli/dist/commands/issue-read.d.ts +0 -3
  174. package/cli/dist/commands/issue-read.js +0 -80
  175. package/cli/dist/commands/repository.d.ts +0 -5
  176. package/cli/dist/commands/security.d.ts +0 -3
@@ -153,4 +153,15 @@ export function readBlockedBy(target, projectId, fieldNames, errorMessages = [])
153
153
  const [gap] = [target, ...nodes].flatMap(issue => connectionShortfalls(issue));
154
154
  return gap === undefined ? { kind: 'ok', issues: nodes.map(node => readIssue(node, projectId, fieldNames)) } : { kind: 'read-failed', reason: gap };
155
155
  }
156
+ /**
157
+ 前提 1 件の参照(node ID・番号・リポ・状態)。node は BlockedByReferenceFields の形
158
+ */
159
+ export function readIssueReference(node) {
160
+ return {
161
+ id: requireString(jsonField(node, 'id'), 'blockedBy.nodes.id'),
162
+ repository: readRepository(node, 'blockedBy.nodes'),
163
+ number: requireNumber(jsonField(node, 'number'), 'blockedBy.nodes.number'),
164
+ state: readState(node, ['OPEN', 'CLOSED'], 'blockedBy.nodes'),
165
+ };
166
+ }
156
167
  //# sourceMappingURL=readout.js.map
@@ -9,12 +9,25 @@ export interface CreateReleaseOptions {
9
9
  readonly draft?: boolean | undefined;
10
10
  readonly prerelease?: boolean | undefined;
11
11
  }
12
+ export interface GraphqlRateLimit {
13
+ readonly limit: number;
14
+ readonly used: number;
15
+ readonly remaining: number;
16
+ /**
17
+ 窓が切り替わる時刻(UNIX 秒)
18
+ */
19
+ readonly reset: number;
20
+ }
12
21
  export declare class ReposApi extends GitHubClientBase {
13
22
  /**
14
23
  Link ヘッダの next を最後まで辿る。2 ページ目以降は next の絶対 URL を使い、params を再送すると cursor と二重になる
15
24
  */
16
25
  protected listAll(path: string, firstParameters: Readonly<Record<string, number | string>>): Promise<readonly JsonValue[]>;
17
26
  /**
27
+ GraphQL の点数の上限・使用量・残り・窓の切り替わり(REST の /rate_limit。点数を使わない)。読めない・形が違うときは undefined
28
+ */
29
+ getGraphqlRateLimit(): Promise<GraphqlRateLimit | undefined>;
30
+ /**
18
31
  リポジトリの GraphQL Node ID。見つからなければ GitHubNotFoundError
19
32
  */
20
33
  getRepositoryId(owner: string, name: string): Promise<string>;
@@ -23,6 +36,11 @@ export declare class ReposApi extends GitHubClientBase {
23
36
  */
24
37
  getBranchSha(owner: string, repository: string, branch: string): Promise<string>;
25
38
  /**
39
+ head が base より進んでいる commit の数(REST の compare の ahead_by)。手元の git を使わない。
40
+ per_page=1 で commit の一覧を削っても、ahead_by は変わらない
41
+ */
42
+ countCommitsAhead(owner: string, repository: string, base: string, head: string): Promise<number>;
43
+ /**
26
44
  Issue に紐づいたブランチを作り、その名前を返す(gh issue develop と同等)。
27
45
  repositoryId を省くと、Issue と同じリポジトリになる
28
46
  */
@@ -29,6 +29,26 @@ export class ReposApi extends GitHubClientBase {
29
29
  }
30
30
  }
31
31
  /**
32
+ GraphQL の点数の上限・使用量・残り・窓の切り替わり(REST の /rate_limit。点数を使わない)。読めない・形が違うときは undefined
33
+ */
34
+ async getGraphqlRateLimit() {
35
+ let body;
36
+ try {
37
+ body = await this.restJson('GET', '/rate_limit');
38
+ }
39
+ catch (error) {
40
+ if (error instanceof GitHubAPIError)
41
+ return undefined;
42
+ throw error;
43
+ }
44
+ const graphql = jsonField(jsonField(body, 'resources'), 'graphql');
45
+ const limit = jsonField(graphql, 'limit');
46
+ const used = jsonField(graphql, 'used');
47
+ const remaining = jsonField(graphql, 'remaining');
48
+ const reset = jsonField(graphql, 'reset');
49
+ return typeof limit === 'number' && typeof used === 'number' && typeof remaining === 'number' && typeof reset === 'number' ? { limit, used, remaining, reset } : undefined;
50
+ }
51
+ /**
32
52
  リポジトリの GraphQL Node ID。見つからなければ GitHubNotFoundError
33
53
  */
34
54
  async getRepositoryId(owner, name) {
@@ -46,6 +66,17 @@ export class ReposApi extends GitHubClientBase {
46
66
  return requireString(jsonField(reference, 'sha'), 'object.sha');
47
67
  }
48
68
  /**
69
+ head が base より進んでいる commit の数(REST の compare の ahead_by)。手元の git を使わない。
70
+ per_page=1 で commit の一覧を削っても、ahead_by は変わらない
71
+ */
72
+ async countCommitsAhead(owner, repository, base, head) {
73
+ const comparison = await this.restJson('GET', `${repositoryPath(owner, repository)}/compare/${encodePath(base)}...${encodePath(head)}`, { params: { per_page: 1 } });
74
+ const ahead = jsonField(comparison, 'ahead_by');
75
+ if (typeof ahead !== 'number' || !Number.isSafeInteger(ahead))
76
+ throw new GitHubAPIError('could not read ahead_by from the compare response');
77
+ return ahead;
78
+ }
79
+ /**
49
80
  Issue に紐づいたブランチを作り、その名前を返す(gh issue develop と同等)。
50
81
  repositoryId を省くと、Issue と同じリポジトリになる
51
82
  */
@@ -33,7 +33,7 @@ nx が無い・実行失敗・部分 graph・JSON の解析失敗なら undefine
33
33
  */
34
34
  export declare function nxProjects(toplevel: string, options?: Readonly<NxGraphOptions>): ReadonlyMap<string, NxProject> | undefined;
35
35
  /**
36
- `baseReference...head` の変更ファイル(リポジトリ root からの相対パス)を返す。
36
+ `baseReference...head` の変更ファイル(リポジトリ root からの相対パス)を返す。baseReference は、ブランチのほか、コミットの SHA(base の記録の位置)も受ける。
37
37
  rename 検出だと移動元のプロジェクトが漏れ、`core.quotePath` だと非 ASCII パスが一致しなくなるため、`--no-renames` と NUL 区切りで取る。
38
38
  baseReference / head が解決できない・git 失敗・git が無いなら undefined
39
39
  */
@@ -131,7 +131,7 @@ export function nxProjects(toplevel, options = {}) {
131
131
  }
132
132
  }
133
133
  /**
134
- `baseReference...head` の変更ファイル(リポジトリ root からの相対パス)を返す。
134
+ `baseReference...head` の変更ファイル(リポジトリ root からの相対パス)を返す。baseReference は、ブランチのほか、コミットの SHA(base の記録の位置)も受ける。
135
135
  rename 検出だと移動元のプロジェクトが漏れ、`core.quotePath` だと非 ASCII パスが一致しなくなるため、`--no-renames` と NUL 区切りで取る。
136
136
  baseReference / head が解決できない・git 失敗・git が無いなら undefined
137
137
  */
@@ -1,3 +1,4 @@
1
+ import type { BaseReading, BaseRecord } from '../domain/state.js';
1
2
  export interface StateDirectoryOptions {
2
3
  /**
3
4
  true なら、無ければ作る
@@ -10,7 +11,7 @@ export interface StateDirectoryOptions {
10
11
  export declare function getStateDirectory(options?: Readonly<StateDirectoryOptions>): string;
11
12
  /**
12
13
  作業ディレクトリ `.pecot/work/<Issue番号>/` を作って返す。
13
- .pecot-active へ作業対象を記録するタイミング(create-branch / issue quick / session restore)で呼ぶ。
14
+ .pecot-active へ作業対象を記録するタイミング(session start / session restore)で呼ぶ。
14
15
  作れないとき(プロジェクトルート不明・OS のエラー)は undefined。作業フロー自体は止めない
15
16
  */
16
17
  export declare function ensureWorkDirectory(issueReference: string): string | undefined;
@@ -38,6 +39,14 @@ export declare function writeFlag(flagName: string, content: string): void;
38
39
  */
39
40
  export declare function readFlag(flagName: string): string | undefined;
40
41
  /**
42
+ 着手のときに選んだ base を .pecot-base に 1 行で書く
43
+ */
44
+ export declare function writeBaseRecord(record: Readonly<BaseRecord>): void;
45
+ /**
46
+ .pecot-base を読む。無ければ開発ブランチから着手したものとして返す
47
+ */
48
+ export declare function readBaseRecord(): BaseReading;
49
+ /**
41
50
  作業対象を記録する(.pecot-active と .pecot-session-title を同時に書く)。
42
51
  issueReference の末尾が整数でなければ InvalidValueError で、何も書かない
43
52
  */
@@ -4,7 +4,7 @@ import { closeSync, mkdirSync, openSync, statSync, unlinkSync, utimesSync, write
4
4
  import path from 'node:path';
5
5
  import { ProjectRootNotFoundError } from '../domain/errors.js';
6
6
  import { pythonStrip } from '../domain/python-format.js';
7
- import { FLAG_PECOT_ACTIVE, FLAG_PECOT_SESSION_TITLE, planWorkTarget, workDirectoryName } from '../domain/state.js';
7
+ import { FLAG_PECOT_ACTIVE, FLAG_PECOT_BASE, FLAG_PECOT_SESSION_TITLE, formatBaseRecord, interpretBaseRecord, planWorkTarget, workDirectoryName } from '../domain/state.js';
8
8
  import { OsError, hasErrorCode, isFileNotFound, isSystemCallError } from './os-error.js';
9
9
  import { projectRoot, STATE_DIR, WORK_DIR } from './paths.js';
10
10
  import { readTextFile } from './text-file.js';
@@ -19,7 +19,7 @@ export function getStateDirectory(options = {}) {
19
19
  }
20
20
  /**
21
21
  作業ディレクトリ `.pecot/work/<Issue番号>/` を作って返す。
22
- .pecot-active へ作業対象を記録するタイミング(create-branch / issue quick / session restore)で呼ぶ。
22
+ .pecot-active へ作業対象を記録するタイミング(session start / session restore)で呼ぶ。
23
23
  作れないとき(プロジェクトルート不明・OS のエラー)は undefined。作業フロー自体は止めない
24
24
  */
25
25
  export function ensureWorkDirectory(issueReference) {
@@ -107,6 +107,18 @@ export function readFlag(flagName) {
107
107
  }
108
108
  }
109
109
  /**
110
+ 着手のときに選んだ base を .pecot-base に 1 行で書く
111
+ */
112
+ export function writeBaseRecord(record) {
113
+ writeFlag(FLAG_PECOT_BASE, formatBaseRecord(record));
114
+ }
115
+ /**
116
+ .pecot-base を読む。無ければ開発ブランチから着手したものとして返す
117
+ */
118
+ export function readBaseRecord() {
119
+ return interpretBaseRecord(readFlag(FLAG_PECOT_BASE));
120
+ }
121
+ /**
110
122
  作業対象を記録する(.pecot-active と .pecot-session-title を同時に書く)。
111
123
  issueReference の末尾が整数でなければ InvalidValueError で、何も書かない
112
124
  */
@@ -1,3 +1,4 @@
1
+ import type { HintedText } from '../domain/command-hint.js';
1
2
  import { PecotError } from '../domain/errors.js';
2
3
  import type { JsonValue } from '../domain/python-format.js';
3
4
  import type { Diagnostics } from './diagnostics.js';
@@ -22,6 +23,8 @@ export interface SymlinkResult {
22
23
  ワークツリー設定の操作に失敗した
23
24
  */
24
25
  export declare class WorktreeConfigError extends PecotError {
26
+ readonly hintedText: HintedText | undefined;
27
+ constructor(message: string | HintedText, options?: Readonly<ErrorOptions>);
25
28
  }
26
29
  /**
27
30
  個別リンク定義。キーは設定ファイルの JSON と同じ
@@ -13,6 +13,7 @@
13
13
  import { spawnSync } from 'node:child_process';
14
14
  import { existsSync, lstatSync, mkdirSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
15
15
  import path from 'node:path';
16
+ import { commandHint, formatHinted, hinted } from '../domain/command-hint.js';
16
17
  import { PecotError, InvalidValueError } from '../domain/errors.js';
17
18
  import { isJsonObject, jsonField, parseJsonText } from '../domain/json.js';
18
19
  import { isJsonArray, pythonStrip, ValidationFailure } from '../domain/python-format.js';
@@ -68,6 +69,12 @@ const PECOT_GITIGNORE_ENSURE_RELATIVE = 'hooks/lib/core/pecot-gitignore-ensure.s
68
69
  ワークツリー設定の操作に失敗した
69
70
  */
70
71
  export class WorktreeConfigError extends PecotError {
72
+ hintedText;
73
+ // message は CLI の形。MCP では最上位が hintedText から描き直す
74
+ constructor(message, options) {
75
+ super(formatHinted(message, 'cli'), options);
76
+ this.hintedText = typeof message === 'string' ? undefined : message;
77
+ }
71
78
  }
72
79
  // 検証(pydantic の WorktreeConfig と同じ文を作る)
73
80
  function issueOf(type, location, message, input) {
@@ -245,7 +252,7 @@ function splitLines(text) {
245
252
  export function loadCopyExcludeSpec(mainWorktree, diagnostics) {
246
253
  const file = path.join(mainWorktree, WORKTREE_IGNORE_FILENAME);
247
254
  if (!existsSync(file)) {
248
- throw new WorktreeConfigError(`copy exclude config not found: ${WORKTREE_IGNORE_FILENAME}\n run pecot worktree init to generate the template`);
255
+ throw new WorktreeConfigError(hinted `copy exclude config not found: ${WORKTREE_IGNORE_FILENAME}\n run ${commandHint(['worktree', 'init'])} to generate the template`);
249
256
  }
250
257
  const rawLines = splitLines(readTextFile(file));
251
258
  const effectiveLines = rawLines.filter(line => pythonStrip(line) !== '' && !pythonStrip(line).startsWith('#'));
@@ -1,13 +1,23 @@
1
1
  import { BaseError } from '../domain/errors.js';
2
+ import type { HintedText } from '../domain/command-hint.js';
2
3
  import type { Diagnostics } from './diagnostics.js';
3
4
  import type { GitIgnoreSpec } from './gitignore-spec.js';
4
5
  import type { SymlinkResult } from './worktree-links.js';
5
6
  import type { CopyResult } from './worktree-copy.js';
6
7
  import type { SetupResult } from './worktree-setup.js';
7
8
  /**
9
+ WorktreeRuntimeError の原因の名前。commands の FailureKind の一部
10
+ */
11
+ export type WorktreeFailure = 'config-invalid' | 'no-active-project' | 'not-initialized' | 'other' | 'repo-not-in-project' | 'repo-setting-missing';
12
+ /**
8
13
  ワークツリー操作に失敗した(Python の RuntimeError に当たる)。メッセージは利用者に見せる文
9
14
  */
10
15
  export declare class WorktreeRuntimeError extends BaseError {
16
+ readonly hintedText: HintedText | undefined;
17
+ readonly failure: WorktreeFailure;
18
+ constructor(message: string | HintedText, options?: Readonly<ErrorOptions & {
19
+ readonly failure?: WorktreeFailure;
20
+ }>);
11
21
  }
12
22
  /**
13
23
  pecot worktree 系コマンドが devcontainer 内で実行されていることを確認する。
@@ -165,10 +175,11 @@ export declare function createWorktree(cwd: string, diagnostics: Diagnostics, op
165
175
  /**
166
176
  ワークツリーを削除する。name は worktree add が付けた名前(wtN)か、checkout しているブランチ名。
167
177
  WT が見つからない・削除に失敗した場合は WorktreeRuntimeError。
168
- ローカルブランチを消せなかったときは、その理由を返す。成功時と shouldKeepBranch は undefined
178
+ ローカルブランチを消せなかったときは、その理由を返す。成功時と shouldKeepBranch は undefined。isDryRun は WT を探すだけで何も消さない
169
179
  */
170
180
  export declare function removeWorktree(cwd: string, name: string, diagnostics: Diagnostics, options?: Readonly<{
171
181
  readonly isForced?: boolean | undefined;
172
182
  readonly shouldKeepBranch?: boolean | undefined;
183
+ readonly isDryRun?: boolean | undefined;
173
184
  }>): string | undefined;
174
185
  //# sourceMappingURL=worktree.d.ts.map
@@ -11,6 +11,7 @@
11
11
  import { BaseError } from '../domain/errors.js';
12
12
  import { existsSync, readdirSync, readFileSync, rmdirSync, writeFileSync } from 'node:fs';
13
13
  import path from 'node:path';
14
+ import { commandHint, formatHinted, hinted, inputHint, inputNameHint, placeholder } from '../domain/command-hint.js';
14
15
  import { findRepository, getDevelopBranch } from '../domain/config.js';
15
16
  import { pythonStrip, ValidationFailure } from '../domain/python-format.js';
16
17
  import { createRepositoryReference } from '../domain/repository-resolver.js';
@@ -22,10 +23,19 @@ import { normalizePath, resolveRealPath, WORKTREE_CONFIG_FILENAME } from './path
22
23
  import { createSymlinks, loadConfig, loadCopyExcludeSpec, WorktreeConfigError, } from './worktree-links.js';
23
24
  import { copyFiles } from './worktree-copy.js';
24
25
  import { runSetupCommand } from './worktree-setup.js';
26
+ const WORKTREE_ADD_PATH = ['worktree', 'add'];
25
27
  /**
26
28
  ワークツリー操作に失敗した(Python の RuntimeError に当たる)。メッセージは利用者に見せる文
27
29
  */
28
30
  export class WorktreeRuntimeError extends BaseError {
31
+ hintedText;
32
+ failure;
33
+ // message は CLI の形。MCP では最上位が hintedText から描き直す
34
+ constructor(message, options = {}) {
35
+ super(formatHinted(message, 'cli'), options.cause === undefined ? undefined : { cause: options.cause });
36
+ this.hintedText = typeof message === 'string' ? undefined : message;
37
+ this.failure = options.failure ?? 'other';
38
+ }
29
39
  }
30
40
  // 環境ガード
31
41
  function isSet(value = '') {
@@ -312,14 +322,15 @@ function readRemoteCandidates(cwd) {
312
322
  function loadCopyExcludeSpecOrRaise(mainWorktree, diagnostics) {
313
323
  const configPath = path.join(mainWorktree, WORKTREE_CONFIG_FILENAME);
314
324
  if (!existsSync(configPath)) {
315
- throw new WorktreeRuntimeError(`worktree config not found: ${WORKTREE_CONFIG_FILENAME}\n run pecot worktree init to generate the template`);
325
+ throw new WorktreeRuntimeError(hinted `worktree config not found: ${WORKTREE_CONFIG_FILENAME}\n run ${commandHint(['worktree', 'init'])} to generate the template`, { failure: 'not-initialized' });
316
326
  }
317
327
  try {
318
328
  return { configPath, spec: loadCopyExcludeSpec(mainWorktree, diagnostics) };
319
329
  }
320
330
  catch (error) {
331
+ // loadCopyExcludeSpec の WorktreeConfigError は、.worktreeignore が無いときだけ
321
332
  if (error instanceof WorktreeConfigError)
322
- throw new WorktreeRuntimeError(error.message, { cause: error });
333
+ throw new WorktreeRuntimeError(error.hintedText ?? error.message, { cause: error, failure: 'not-initialized' });
323
334
  throw error;
324
335
  }
325
336
  }
@@ -330,7 +341,7 @@ function requireRegisteredRepository(cwd) {
330
341
  throw new WorktreeRuntimeError(NO_REMOTE_MESSAGE);
331
342
  const config = loadActiveConfig();
332
343
  if (config === undefined) {
333
- throw new WorktreeRuntimeError('project config not found\n hint: run pecot project activate <PROJECT> to set the project');
344
+ throw new WorktreeRuntimeError(hinted `project config not found\n hint: run ${commandHint(['project', 'activate'], { project: placeholder('PROJECT') })} to set the project`, { failure: 'no-active-project' });
334
345
  }
335
346
  for (const candidate of candidates) {
336
347
  if (candidate.repository !== undefined && findRepository(config, candidate.repository.owner, candidate.repository.repository) !== undefined) {
@@ -343,25 +354,24 @@ function requireRegisteredRepository(cwd) {
343
354
  const registered = config.repositories.length > 0
344
355
  ? config.repositories.map(item => ` - ${item.owner}/${item.name}`).join('\n')
345
356
  : ' (none registered)';
346
- throw new WorktreeRuntimeError(`repository ${repository.owner}/${repository.repository} is not registered in the `
347
- + 'active pecot project\n'
348
- + '\n'
349
- + 'registered repositories:\n'
350
- + `${registered}\n`
351
- + '\n'
352
- + 'to add this repository to the pecot project:\n'
353
- + ` pecot project set-repo ${repository.owner}/${repository.repository}\n`
354
- + '\n'
355
- + 'to switch to another project:\n'
356
- + ' pecot project activate <PROJECT>');
357
+ throw new WorktreeRuntimeError(hinted `repository ${repository.owner}/${repository.repository} is not registered in the active pecot project
358
+
359
+ registered repositories:
360
+ ${registered}
361
+
362
+ to add this repository to the pecot project:
363
+ ${commandHint(['project', 'link'], { repo: `${repository.owner}/${repository.repository}` })}
364
+
365
+ to switch to another project:
366
+ ${commandHint(['project', 'activate'], { project: placeholder('PROJECT') })}`, { failure: 'repo-not-in-project' });
357
367
  }
358
368
  // ベースブランチ決定(プロジェクト設定の develop_branch を使用)
359
369
  function defaultBaseBranch(config, repository) {
360
370
  const developBranch = getDevelopBranch(config, repository.owner, repository.repository);
361
371
  if (developBranch === undefined || developBranch === '') {
362
- throw new WorktreeRuntimeError(`develop_branch is not set for repository ${repository.owner}/${repository.repository}\n`
363
- + ' add develop_branch to repositories in the project config file\n'
364
- + ' or pass --base explicitly');
372
+ throw new WorktreeRuntimeError(hinted `develop_branch is not set for repository ${repository.owner}/${repository.repository}
373
+ add develop_branch to repositories in the project config file
374
+ or pass ${inputNameHint(WORKTREE_ADD_PATH, 'base')} explicitly`, { failure: 'repo-setting-missing' });
365
375
  }
366
376
  return developBranch;
367
377
  }
@@ -372,7 +382,7 @@ function loadWorktreeConfigOrRaise(configPath) {
372
382
  }
373
383
  catch (error) {
374
384
  if (error instanceof WorktreeConfigError) {
375
- throw new WorktreeRuntimeError(`failed to load the worktree config: ${normalizePath(configPath)}: ${error.message}\n fix the config file and run it again`, { cause: error });
385
+ throw new WorktreeRuntimeError(`failed to load the worktree config: ${normalizePath(configPath)}: ${error.message}\n fix the config file and run it again`, { cause: error, failure: 'config-invalid' });
376
386
  }
377
387
  throw error;
378
388
  }
@@ -466,9 +476,8 @@ function addGitWorktree(cwd, worktreePath, name, base, isExistingBranchAllowed)
466
476
  const currentUpstream = pythonStrip(runGit(['for-each-ref', '--format=%(upstream:short)', `refs/heads/${name}`], { cwd }).stdout);
467
477
  const expectedUpstream = baseBranch === '' ? undefined : `${remote}/${baseBranch}`;
468
478
  if ((currentUpstream === '' ? undefined : currentUpstream) !== expectedUpstream) {
469
- throw new WorktreeRuntimeError(`branch '${name}' already exists and its upstream differs from the expected one `
470
- + `(current: ${currentUpstream === '' ? '(unset)' : currentUpstream}, expected: ${expectedUpstream ?? 'None'}): `
471
- + 'pass --allow-existing-branch to reuse it');
479
+ const current = currentUpstream === '' ? '(unset)' : currentUpstream;
480
+ throw new WorktreeRuntimeError(hinted `branch '${name}' already exists and its upstream differs from the expected one (current: ${current}, expected: ${expectedUpstream ?? 'None'}): pass ${inputHint(WORKTREE_ADD_PATH, 'allow_existing_branch')} to reuse it`);
472
481
  }
473
482
  // upstream 一致かつ bind なし → prune に取り残された孤児ブランチとみなし除去
474
483
  const worktreeOfBranch = runGit(['for-each-ref', '--format=%(worktreepath)', `refs/heads/${name}`], { cwd });
@@ -518,20 +527,28 @@ function findWorktreePathByName(cwd, name) {
518
527
  /**
519
528
  ワークツリーを削除する。name は worktree add が付けた名前(wtN)か、checkout しているブランチ名。
520
529
  WT が見つからない・削除に失敗した場合は WorktreeRuntimeError。
521
- ローカルブランチを消せなかったときは、その理由を返す。成功時と shouldKeepBranch は undefined
530
+ ローカルブランチを消せなかったときは、その理由を返す。成功時と shouldKeepBranch は undefined。isDryRun は WT を探すだけで何も消さない
522
531
  */
523
532
  export function removeWorktree(cwd, name, diagnostics, options = {}) {
524
533
  // 1. WTパスを特定
525
534
  const worktreePath = findWorktreePathByName(cwd, name);
526
535
  if (worktreePath === undefined)
527
536
  throw new WorktreeRuntimeError(`worktree not found: ${name}`);
537
+ if (options.isDryRun === true)
538
+ return undefined;
528
539
  // 2. git worktree remove
529
540
  const gitArguments = ['worktree', 'remove', worktreePath];
530
541
  if (options.isForced === true)
531
542
  gitArguments.push('--force');
532
543
  const removed = runGit(gitArguments, { cwd });
533
- if (removed.exitCode !== 0)
544
+ if (removed.exitCode !== 0) {
545
+ const reason = pythonStrip(removed.stderr);
546
+ // git の文は CLI の `--force` を案内するので、MCP でも打てる形の案内を添える
547
+ if (options.isForced !== true && reason.includes('contains modified or untracked files')) {
548
+ throw new WorktreeRuntimeError(hinted `failed to remove the worktree: ${reason}\nhint: to remove it with its changes, pass ${inputHint(['worktree', 'remove'], 'force')}`);
549
+ }
534
550
  throw new WorktreeRuntimeError(`failed to remove the worktree: ${removed.stderr}`);
551
+ }
535
552
  // 3. ブランチ削除(ローカルブランチ)
536
553
  let branchError;
537
554
  if (options.shouldKeepBranch !== true) {
@@ -1,9 +1,23 @@
1
1
  import type { CallToolResult } from '@modelcontextprotocol/server';
2
+ import { z } from 'zod';
3
+ import type { FailureKind } from '../commands/failure-kind.js';
2
4
  import type { CommandIo } from '../commands/registry.js';
3
5
  export interface CommandOutcome {
4
6
  readonly exitCode: number;
5
7
  readonly stdout: string;
6
8
  readonly stderr: string;
9
+ /**
10
+ 失敗の原因の名前。終了コードが 0 でないのに無ければ other
11
+ */
12
+ readonly kind?: FailureKind | undefined;
13
+ /**
14
+ 失敗の message に使う文。無ければ stderr の行から決める
15
+ */
16
+ readonly message?: string | undefined;
17
+ /**
18
+ 成功の message に使う結果の行(片付けの行を除いた最初のもの)。無ければ stdout の最初の空でない行
19
+ */
20
+ readonly resultLine?: string | undefined;
7
21
  }
8
22
  export interface CollectedIo {
9
23
  /**
@@ -12,22 +26,36 @@ export interface CollectedIo {
12
26
  readonly io: CommandIo;
13
27
  readonly stdout: () => string;
14
28
  readonly stderr: () => string;
29
+ readonly kind: () => FailureKind | undefined;
30
+ readonly resultLine: () => string | undefined;
15
31
  }
16
32
  /**
17
- stdout・stderr に書かれた文字列を集める io
33
+ stdout・stderr に書かれた文字列と、失敗の原因の名前、最初の結果の行を集める io
18
34
  */
19
35
  export declare function collectIo(): CollectedIo;
20
36
  /**
21
- 結果の _meta で、終了コードと stdout・stderr を載せるキー。モデルには届かず、SDK のクライアントには届く
37
+ 全ツールが共有する outputSchema。pecot-tools・pecot-visual と項目の名前をそろえる
22
38
  */
23
- export declare const OUTCOME_META_KEY = "io.github.pecotcraft/outcome";
39
+ export declare const TOOL_OUTPUT_SCHEMA: z.ZodObject<{
40
+ ok: z.ZodBoolean;
41
+ exitCode: z.ZodNumber;
42
+ kind: z.ZodOptional<z.ZodString>;
43
+ artifacts: z.ZodArray<z.ZodString>;
44
+ data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
45
+ message: z.ZodString;
46
+ stdout: z.ZodOptional<z.ZodString>;
47
+ stderr: z.ZodOptional<z.ZodString>;
48
+ }, z.core.$strip>;
24
49
  /**
25
- content は stdout、続けて stderr(あれば)。stdout・stderr が空で終了コード 0 なら空。
26
- structuredContent は付けない(Claude Code が content を落とし、Copilot CLI は二重に渡すため)。終了コードと 2 つの出力は _meta に入れる
50
+ structuredContent と、同じ JSON を本文にした content の両方で返す。ホストがどちらを渡しても同じ中身が届く
27
51
  */
28
52
  export declare function toToolResult(outcome: Readonly<CommandOutcome>): CallToolResult;
29
53
  /**
30
- コマンドを呼ぶ前に入力を断った結果。終了コードが無いので _meta は付けない
54
+ コマンドを呼ぶ前に入力を断った結果。終了コードは使い方の誤りと同じ 2
31
55
  */
32
56
  export declare function toRejectedResult(message: string): CallToolResult;
57
+ /**
58
+ 中断(notifications/cancelled か接続の切断)で本体を呼ばなかった結果。応答はクライアントに届かない
59
+ */
60
+ export declare function toAbortedResult(): CallToolResult;
33
61
  //# sourceMappingURL=result.d.ts.map
@@ -1,9 +1,13 @@
1
+ import { z } from 'zod';
2
+ import { USAGE_EXIT_CODE } from '../commands/usage-error.js';
1
3
  /**
2
- stdout・stderr に書かれた文字列を集める io
4
+ stdout・stderr に書かれた文字列と、失敗の原因の名前、最初の結果の行を集める io
3
5
  */
4
6
  export function collectIo() {
5
7
  const out = [];
6
8
  const error = [];
9
+ let failureKind;
10
+ let firstResult;
7
11
  return {
8
12
  io: {
9
13
  stdout: (text) => {
@@ -12,41 +16,81 @@ export function collectIo() {
12
16
  stderr: (text) => {
13
17
  error.push(text);
14
18
  },
19
+ surface: 'mcp',
20
+ failureKind: (kind) => {
21
+ failureKind ??= kind;
22
+ },
23
+ resultLine: (line) => {
24
+ firstResult ??= line;
25
+ },
15
26
  },
16
27
  stdout: () => out.join(''),
17
28
  stderr: () => error.join(''),
29
+ kind: () => failureKind,
30
+ resultLine: () => firstResult,
18
31
  };
19
32
  }
20
33
  /**
21
- 結果の _meta で、終了コードと stdout・stderr を載せるキー。モデルには届かず、SDK のクライアントには届く
34
+ 全ツールが共有する outputSchema。pecot-tools・pecot-visual と項目の名前をそろえる
22
35
  */
23
- export const OUTCOME_META_KEY = 'io.github.pecotcraft/outcome';
24
- function textBlock(text) {
25
- return { type: 'text', text };
36
+ export const TOOL_OUTPUT_SCHEMA = z.object({
37
+ ok: z.boolean().describe('Whether the tool completed its intended run'),
38
+ exitCode: z.number().describe('Exit code (0 = success)'),
39
+ kind: z.string().optional().describe('Failure kind (omitted on success)'),
40
+ artifacts: z.array(z.string()).describe('Absolute paths of files and directories created or updated'),
41
+ data: z.record(z.string(), z.unknown()).describe('Object with the details of the run'),
42
+ message: z.string().describe('One-line summary for the calling agent. On success, the first result line or else the first stdout line; empty when there is neither'),
43
+ stdout: z.string().optional().describe('Captured stdout (omitted when empty)'),
44
+ stderr: z.string().optional().describe('Captured stderr (omitted when empty)'),
45
+ });
46
+ const ERROR_PREFIX = 'error: ';
47
+ function linesOf(text) {
48
+ return text.split('\n').filter(line => line.trim() !== '');
26
49
  }
27
- // 2 個目の本文。stderr に、終了コードが 0 でなければ `exit code: <n>` の行を足す
28
- function diagnosticText(outcome) {
50
+ // 失敗は最初の error の行の文、無ければ stderr の最初の行。成功は結果の行、無ければ stdout の最初の行
51
+ function messageOf(outcome) {
29
52
  if (outcome.exitCode === 0)
30
- return outcome.stderr;
31
- const separator = outcome.stderr === '' || outcome.stderr.endsWith('\n') ? '' : '\n';
32
- return `${outcome.stderr}${separator}exit code: ${String(outcome.exitCode)}\n`;
53
+ return outcome.resultLine ?? linesOf(outcome.stdout).at(0)?.trim() ?? '';
54
+ const lines = linesOf(outcome.stderr);
55
+ if (outcome.message !== undefined)
56
+ return outcome.message;
57
+ const errorLine = lines.find(line => line.startsWith(ERROR_PREFIX));
58
+ return errorLine === undefined ? (lines.at(0)?.trim() ?? '') : errorLine.slice(ERROR_PREFIX.length);
59
+ }
60
+ function toOutput(outcome) {
61
+ const isOk = outcome.exitCode === 0;
62
+ return {
63
+ ok: isOk,
64
+ exitCode: outcome.exitCode,
65
+ ...!isOk && { kind: outcome.kind ?? 'other' },
66
+ artifacts: [],
67
+ data: {},
68
+ message: messageOf(outcome),
69
+ ...outcome.stdout !== '' && { stdout: outcome.stdout },
70
+ ...outcome.stderr !== '' && { stderr: outcome.stderr },
71
+ };
33
72
  }
34
73
  /**
35
- content は stdout、続けて stderr(あれば)。stdout・stderr が空で終了コード 0 なら空。
36
- structuredContent は付けない(Claude Code が content を落とし、Copilot CLI は二重に渡すため)。終了コードと 2 つの出力は _meta に入れる
74
+ structuredContent と、同じ JSON を本文にした content の両方で返す。ホストがどちらを渡しても同じ中身が届く
37
75
  */
38
76
  export function toToolResult(outcome) {
39
- const diagnostic = diagnosticText(outcome);
77
+ const output = toOutput(outcome);
40
78
  return {
41
- content: [...outcome.stdout === '' ? [] : [textBlock(outcome.stdout)], ...diagnostic === '' ? [] : [textBlock(diagnostic)]],
42
- ...outcome.exitCode !== 0 && { isError: true },
43
- _meta: { [OUTCOME_META_KEY]: { exitCode: outcome.exitCode, stdout: outcome.stdout, stderr: outcome.stderr } },
79
+ content: [{ type: 'text', text: JSON.stringify(output) }],
80
+ structuredContent: { ...output },
81
+ ...!output.ok && { isError: true },
44
82
  };
45
83
  }
46
84
  /**
47
- コマンドを呼ぶ前に入力を断った結果。終了コードが無いので _meta は付けない
85
+ コマンドを呼ぶ前に入力を断った結果。終了コードは使い方の誤りと同じ 2
48
86
  */
49
87
  export function toRejectedResult(message) {
50
- return { content: [{ type: 'text', text: message }], isError: true };
88
+ return toToolResult({ exitCode: USAGE_EXIT_CODE, stdout: '', stderr: '', kind: 'invalid-input', message });
89
+ }
90
+ /**
91
+ 中断(notifications/cancelled か接続の切断)で本体を呼ばなかった結果。応答はクライアントに届かない
92
+ */
93
+ export function toAbortedResult() {
94
+ return toToolResult({ exitCode: 1, stdout: '', stderr: '', kind: 'aborted', message: 'cancelled' });
51
95
  }
52
96
  //# sourceMappingURL=result.js.map
@@ -3,11 +3,11 @@ import type { CommandDefinition } from '../commands/registry.js';
3
3
  export declare const MCP_SERVER_NAME = "pecot-workflow";
4
4
  export interface McpServerOptions {
5
5
  /**
6
- 対象のリポを決められなかった理由。あるとき、どのツールの呼び出しもコマンドを呼ばず、この理由を失敗(exit code 1)で返す。tools/list は変わらない
6
+ 対象のリポを決められなかった理由。あるとき、どのツールの呼び出しもコマンドを呼ばず、この理由を失敗(終了コード 1、kind は session-directory-unresolved)で返す。tools/list は変わらない
7
7
  */
8
8
  readonly unavailableReason?: string | undefined;
9
9
  /**
10
- プログラムの誤り(報告できる失敗でも使い方の誤りでもない例外)と、それまでに集めた出力を、切り分けのために伝える先。SDK は message だけの結果にする
10
+ プログラムの誤り(報告できる失敗でも使い方の誤りでもない例外)と、それまでに集めた出力を、切り分けのために伝える先。結果は kind が other の失敗にする
11
11
  */
12
12
  readonly reportUnexpected?: (error: unknown, collected: {
13
13
  readonly stdout: string;