@pecot/workflow-mcp 5.0.0 → 7.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 (188) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +27 -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 +69 -0
  6. package/cli/dist/commands/board-judgment.d.ts +69 -0
  7. package/cli/dist/commands/board-judgment.js +150 -0
  8. package/cli/dist/commands/board-move.d.ts +3 -0
  9. package/cli/dist/commands/board-move.js +65 -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 +75 -0
  14. package/cli/dist/commands/board-sync.d.ts +3 -0
  15. package/cli/dist/commands/board-sync.js +120 -0
  16. package/cli/dist/commands/board-view.d.ts +151 -0
  17. package/cli/dist/commands/board-view.js +293 -0
  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 +111 -0
  22. package/cli/dist/commands/command-binding.js +4 -0
  23. package/cli/dist/commands/command-definition.d.ts +39 -8
  24. package/cli/dist/commands/command-definition.js +20 -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 +35 -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 +61 -0
  38. package/cli/dist/commands/issue-board.js +85 -1
  39. package/cli/dist/commands/issue-comment.js +66 -30
  40. package/cli/dist/commands/issue-create.js +632 -92
  41. package/cli/dist/commands/issue-dependency.d.ts +3 -0
  42. package/cli/dist/commands/issue-dependency.js +310 -0
  43. package/cli/dist/commands/issue-readiness.d.ts +122 -0
  44. package/cli/dist/commands/issue-readiness.js +253 -0
  45. package/cli/dist/commands/issue-reopen.d.ts +3 -0
  46. package/cli/dist/commands/issue-reopen.js +130 -0
  47. package/cli/dist/commands/issue-shared.d.ts +33 -20
  48. package/cli/dist/commands/issue-shared.js +84 -76
  49. package/cli/dist/commands/issue-show.d.ts +3 -0
  50. package/cli/dist/commands/issue-show.js +239 -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 +63 -0
  55. package/cli/dist/commands/output.d.ts +32 -4
  56. package/cli/dist/commands/output.js +28 -8
  57. package/cli/dist/commands/pr-merge.d.ts +3 -0
  58. package/cli/dist/commands/pr-merge.js +230 -0
  59. package/cli/dist/commands/pr-reference.d.ts +8 -0
  60. package/cli/dist/commands/pr-reference.js +30 -0
  61. package/cli/dist/commands/pr-restack.d.ts +6 -0
  62. package/cli/dist/commands/pr-restack.js +233 -0
  63. package/cli/dist/commands/pr-waiting.d.ts +59 -0
  64. package/cli/dist/commands/pr-waiting.js +143 -0
  65. package/cli/dist/commands/pr.d.ts +23 -0
  66. package/cli/dist/commands/pr.js +378 -366
  67. package/cli/dist/commands/project-sync.d.ts +12 -3
  68. package/cli/dist/commands/project-sync.js +23 -13
  69. package/cli/dist/commands/project.d.ts +3 -2
  70. package/cli/dist/commands/project.js +371 -177
  71. package/cli/dist/commands/registry.js +15 -10
  72. package/cli/dist/commands/release.d.ts +2 -2
  73. package/cli/dist/commands/release.js +118 -130
  74. package/cli/dist/commands/renamed-commands.d.ts +26 -0
  75. package/cli/dist/commands/renamed-commands.js +53 -0
  76. package/cli/dist/commands/repository-match.js +9 -3
  77. package/cli/dist/commands/session-finish.d.ts +3 -0
  78. package/cli/dist/commands/session-finish.js +383 -0
  79. package/cli/dist/commands/session-start.d.ts +3 -0
  80. package/cli/dist/commands/session-start.js +252 -0
  81. package/cli/dist/commands/session.d.ts +3 -0
  82. package/cli/dist/commands/session.js +186 -32
  83. package/cli/dist/commands/tracker-sync-dependabot.d.ts +7 -0
  84. package/cli/dist/commands/{dependabot.js → tracker-sync-dependabot.js} +76 -68
  85. package/cli/dist/commands/tracker-sync-security.d.ts +7 -0
  86. package/cli/dist/commands/{security.js → tracker-sync-security.js} +71 -64
  87. package/cli/dist/commands/tracker-sync.d.ts +37 -0
  88. package/cli/dist/commands/tracker-sync.js +18 -6
  89. package/cli/dist/commands/tracker.d.ts +3 -0
  90. package/cli/dist/commands/tracker.js +20 -0
  91. package/cli/dist/commands/usage-error.d.ts +4 -0
  92. package/cli/dist/commands/usage-error.js +6 -0
  93. package/cli/dist/commands/work-target.d.ts +20 -3
  94. package/cli/dist/commands/work-target.js +49 -6
  95. package/cli/dist/commands/worktree.js +103 -33
  96. package/cli/dist/domain/batch-plan.d.ts +73 -0
  97. package/cli/dist/domain/batch-plan.js +114 -0
  98. package/cli/dist/domain/blocked-by-change.d.ts +99 -0
  99. package/cli/dist/domain/blocked-by-change.js +101 -0
  100. package/cli/dist/domain/board-move.d.ts +90 -0
  101. package/cli/dist/domain/board-move.js +92 -0
  102. package/cli/dist/domain/branch-name.js +1 -1
  103. package/cli/dist/domain/command-hint.d.ts +85 -0
  104. package/cli/dist/domain/command-hint.js +148 -0
  105. package/cli/dist/domain/config.d.ts +4 -0
  106. package/cli/dist/domain/config.js +11 -1
  107. package/cli/dist/domain/dependabot.js +1 -1
  108. package/cli/dist/domain/errors.d.ts +5 -0
  109. package/cli/dist/domain/errors.js +5 -0
  110. package/cli/dist/domain/format.d.ts +51 -4
  111. package/cli/dist/domain/format.js +72 -6
  112. package/cli/dist/domain/frontmatter.d.ts +18 -3
  113. package/cli/dist/domain/frontmatter.js +38 -12
  114. package/cli/dist/domain/issue-order.d.ts +55 -0
  115. package/cli/dist/domain/issue-order.js +65 -0
  116. package/cli/dist/domain/issue-readout.d.ts +36 -4
  117. package/cli/dist/domain/pull-request.d.ts +71 -4
  118. package/cli/dist/domain/pull-request.js +59 -10
  119. package/cli/dist/domain/readiness.d.ts +44 -0
  120. package/cli/dist/domain/readiness.js +153 -5
  121. package/cli/dist/domain/reference-parser.d.ts +3 -1
  122. package/cli/dist/domain/reference-parser.js +6 -2
  123. package/cli/dist/domain/release.d.ts +7 -3
  124. package/cli/dist/domain/release.js +5 -12
  125. package/cli/dist/domain/repository-policy.d.ts +9 -3
  126. package/cli/dist/domain/repository-policy.js +8 -7
  127. package/cli/dist/domain/repository-resolver.js +4 -1
  128. package/cli/dist/domain/restack.d.ts +62 -0
  129. package/cli/dist/domain/restack.js +53 -0
  130. package/cli/dist/domain/security-alerts.js +1 -1
  131. package/cli/dist/domain/state.d.ts +69 -0
  132. package/cli/dist/domain/state.js +67 -1
  133. package/cli/dist/domain/work-start.d.ts +30 -0
  134. package/cli/dist/domain/work-start.js +42 -0
  135. package/cli/dist/infra/authored-notes.d.ts +1 -1
  136. package/cli/dist/infra/authored-notes.js +10 -4
  137. package/cli/dist/infra/config-store.d.ts +4 -0
  138. package/cli/dist/infra/config-store.js +13 -0
  139. package/cli/dist/infra/git.d.ts +76 -0
  140. package/cli/dist/infra/git.js +123 -1
  141. package/cli/dist/infra/github/client.d.ts +5 -0
  142. package/cli/dist/infra/github/client.js +10 -7
  143. package/cli/dist/infra/github/errors.d.ts +18 -0
  144. package/cli/dist/infra/github/errors.js +22 -0
  145. package/cli/dist/infra/github/issues.d.ts +39 -3
  146. package/cli/dist/infra/github/issues.js +178 -23
  147. package/cli/dist/infra/github/projects.d.ts +35 -0
  148. package/cli/dist/infra/github/projects.js +89 -8
  149. package/cli/dist/infra/github/pulls.d.ts +105 -2
  150. package/cli/dist/infra/github/pulls.js +172 -5
  151. package/cli/dist/infra/github/queries.d.ts +15 -4
  152. package/cli/dist/infra/github/queries.js +203 -40
  153. package/cli/dist/infra/github/readout.d.ts +5 -1
  154. package/cli/dist/infra/github/readout.js +11 -33
  155. package/cli/dist/infra/github/repos.d.ts +18 -0
  156. package/cli/dist/infra/github/repos.js +31 -0
  157. package/cli/dist/infra/nx-scope.d.ts +1 -1
  158. package/cli/dist/infra/nx-scope.js +1 -1
  159. package/cli/dist/infra/state-store.d.ts +10 -1
  160. package/cli/dist/infra/state-store.js +14 -2
  161. package/cli/dist/infra/worktree-links.d.ts +3 -0
  162. package/cli/dist/infra/worktree-links.js +8 -1
  163. package/cli/dist/infra/worktree.d.ts +12 -1
  164. package/cli/dist/infra/worktree.js +40 -23
  165. package/cli/dist/mcp/result.d.ts +82 -7
  166. package/cli/dist/mcp/result.js +139 -19
  167. package/cli/dist/mcp/server.d.ts +2 -2
  168. package/cli/dist/mcp/server.js +57 -10
  169. package/cli/templates/comment/plan.md +14 -0
  170. package/cli/templates/comment/review-findings.md +3 -2
  171. package/cli/templates/issue/bug.md +13 -4
  172. package/cli/templates/issue/task-implement.md +13 -6
  173. package/cli/templates/issue/task.md +13 -4
  174. package/cli/templates/workflow/pecot-board-sync.yml +84 -0
  175. package/npm-shrinkwrap.json +2 -2
  176. package/package.json +1 -1
  177. package/cli/dist/commands/dependabot.d.ts +0 -3
  178. package/cli/dist/commands/issue-project.d.ts +0 -3
  179. package/cli/dist/commands/issue-project.js +0 -176
  180. package/cli/dist/commands/issue-quick.d.ts +0 -3
  181. package/cli/dist/commands/issue-quick.js +0 -126
  182. package/cli/dist/commands/issue-read.d.ts +0 -3
  183. package/cli/dist/commands/issue-read.js +0 -80
  184. package/cli/dist/commands/project-info.d.ts +0 -48
  185. package/cli/dist/commands/project-info.js +0 -181
  186. package/cli/dist/commands/repository.d.ts +0 -5
  187. package/cli/dist/commands/repository.js +0 -265
  188. package/cli/dist/commands/security.d.ts +0 -3
@@ -0,0 +1,111 @@
1
+ // branch delete。Python の cli/commands/repo.py の delete_branch の移植。
2
+ import { z } from 'zod';
3
+ import { describeApiError } from '../domain/api-error-detail.js';
4
+ import { findRepository } from '../domain/config.js';
5
+ import { compareStrings } from '../domain/python-format.js';
6
+ import { ReferenceParseError, parseRepositoryReference } from '../domain/reference-parser.js';
7
+ import { GitHubAPIError, isMissingReferenceError } from '../infra/github/errors.js';
8
+ import { defineCommand } from './command-definition.js';
9
+ import { requireActiveConfig, stopWith } from './command-stop.js';
10
+ import { kindOfFailure } from './failure.js';
11
+ import { createGitHubClient } from './github-client.js';
12
+ import { createOutput, DRY_RUN_FIELD } from './output.js';
13
+ import { requireRepositoryMatch } from './repository-match.js';
14
+ import { USAGE_EXIT_CODE } from './usage-error.js';
15
+ const BRANCH_DELETE_OUTPUT = z.strictObject({
16
+ branch: z.string().describe('Name of the remote branch'),
17
+ repository: z.string().describe('Repository of the branch (owner/repo)'),
18
+ deleted: z.boolean().describe('Whether the remote branch was deleted (false on dry_run)'),
19
+ wipBranch: z.string().optional().describe('Name of the wip branch that was deleted along with it (omitted when there was none or it could not be deleted)'),
20
+ dryRun: DRY_RUN_FIELD,
21
+ });
22
+ const branchDeleteCommand = defineCommand({
23
+ path: ['branch', 'delete'],
24
+ hasOwnRepo: true,
25
+ ignoresGlobalRepo: true,
26
+ description: 'Delete a remote branch (a protected branch is never deleted)',
27
+ input: z.strictObject({
28
+ repo: z.string().describe('Repository reference (owner/repo)'),
29
+ branch: z.string().describe('Name of the branch to delete'),
30
+ dry_run: z.boolean().default(false).describe('Show what would be deleted without deleting anything'),
31
+ }),
32
+ output: BRANCH_DELETE_OUTPUT,
33
+ positional: ['repo', 'branch'],
34
+ shortFlags: { dry_run: '-n' },
35
+ interactive: false,
36
+ run: async (input, io) => {
37
+ // 位置引数の repo は対象のリポで、cwd と比べる明示値ではない
38
+ requireRepositoryMatch('reject', undefined, io, process.cwd());
39
+ const out = createOutput(input.dry_run, io);
40
+ // 1. repo をパース
41
+ let target;
42
+ try {
43
+ target = parseRepositoryReference(input.repo);
44
+ }
45
+ catch (error) {
46
+ if (!(error instanceof ReferenceParseError))
47
+ throw error;
48
+ return stopWith(out, error.message, 'invalid-input', USAGE_EXIT_CODE);
49
+ }
50
+ const { owner, repository } = target;
51
+ // 2. 設定取得
52
+ const config = requireActiveConfig(out);
53
+ // 3. 保護ブランチ収集(設定の develop_branch・release_branch と、API の既定ブランチ)
54
+ const protectedBranches = new Set();
55
+ const repositoryConfig = findRepository(config, owner, repository);
56
+ for (const branch of [repositoryConfig?.develop_branch, repositoryConfig?.release_branch]) {
57
+ if (branch !== undefined && branch !== '')
58
+ protectedBranches.add(branch);
59
+ }
60
+ let client;
61
+ try {
62
+ client = createGitHubClient(out, config.host);
63
+ protectedBranches.add(await client.getRepositoryDefaultBranch(owner, repository));
64
+ }
65
+ catch (error) {
66
+ if (!(error instanceof GitHubAPIError))
67
+ throw error;
68
+ return stopWith(out, `could not read the default branch of ${owner}/${repository}: ${error.message}`, kindOfFailure(error));
69
+ }
70
+ // 4. 保護ブランチチェック
71
+ if (protectedBranches.has(input.branch)) {
72
+ return stopWith(out, `${input.branch} is a protected branch\nprotected: ${[...protectedBranches].toSorted(compareStrings).join(', ')}`, 'guard-blocked');
73
+ }
74
+ // 5. dry-run
75
+ const operation = { verb: 'delete', target: `remote branch ${input.branch} in ${owner}/${repository}` };
76
+ if (input.dry_run) {
77
+ out.planned(operation);
78
+ out.result({ branch: input.branch, repository: `${owner}/${repository}`, deleted: false });
79
+ return 0;
80
+ }
81
+ // 6. 削除実行
82
+ try {
83
+ await client.deleteBranch(owner, repository, input.branch);
84
+ }
85
+ catch (error) {
86
+ if (!(error instanceof GitHubAPIError))
87
+ throw error;
88
+ return stopWith(out, `could not delete remote branch ${input.branch} in ${owner}/${repository}: ${error.message}`, kindOfFailure(error));
89
+ }
90
+ out.done(operation);
91
+ out.result({ branch: input.branch, repository: `${owner}/${repository}`, deleted: true });
92
+ // wip ブランチも連動削除
93
+ const wipBranch = `wip/${input.branch}`;
94
+ try {
95
+ await client.deleteBranch(owner, repository, wipBranch);
96
+ }
97
+ catch (error) {
98
+ if (!(error instanceof GitHubAPIError))
99
+ throw error;
100
+ // wip ブランチの削除の失敗だけは、API の応答の本文の詳細も見せる(Python の describe_api_error と同じ)。存在しない場合は何も出さない
101
+ if (!isMissingReferenceError(error))
102
+ out.warning(`could not delete remote branch ${wipBranch} in ${owner}/${repository}: ${describeApiError(error)}`);
103
+ return 0;
104
+ }
105
+ out.done({ verb: 'delete', target: `remote branch ${wipBranch} in ${owner}/${repository}` });
106
+ out.result({ wipBranch });
107
+ return 0;
108
+ },
109
+ });
110
+ export const BRANCH_COMMANDS = [branchDeleteCommand];
111
+ //# sourceMappingURL=branch.js.map
@@ -5,6 +5,7 @@ import { Command, CommanderError, Option } from 'commander';
5
5
  import { z } from 'zod';
6
6
  import { closeMatches } from './fuzzy.js';
7
7
  import { flagOf } from './names.js';
8
+ import { findRenamedInput, renamedInputNote } from './renamed-commands.js';
8
9
  import { invalidValueMessage, missingArgumentMessage, missingOptionMessage, noSuchOptionMessage, optionRequiresArgumentMessage, optionTakesNoValueMessage, UsageError, } from './usage-error.js';
9
10
  import { convertValue, flagKindOf, valueTypeOf } from './value-types.js';
10
11
  function fieldSchemaOf(definition, name) {
@@ -113,6 +114,9 @@ function toUsageError(error, argv, bound, usage) {
113
114
  const booleanNames = ['--help', ...bound.flatMap(entry => entry.kind === 'boolean' ? [entry.names[0], entry.negation] : [])];
114
115
  if (typedName !== quoted && booleanNames.includes(typedName))
115
116
  return new UsageError(optionTakesNoValueMessage(typedName));
117
+ const renamed = typedName.startsWith('--') ? findRenamedInput(usage.commandPath, typedName.slice(2).replaceAll('-', '_')) : undefined;
118
+ if (renamed !== undefined)
119
+ return new UsageError(`${noSuchOptionMessage(typedName)}${renamedInputNote(typedName, flagOf(renamed))}`, usage);
116
120
  const longNames = ['--help', ...bound.flatMap(entry => [...entry.names.filter(name => name.startsWith('--')), ...entry.negation === undefined ? [] : [entry.negation]])];
117
121
  const possibilities = typedName.startsWith('--') ? closeMatches(typedName, longNames) : [];
118
122
  return new UsageError(noSuchOptionMessage(typedName, possibilities), usage);
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { BaseError } from '../domain/errors.js';
3
+ import type { FailureKind } from './failure-kind.js';
3
4
  /**
4
5
  コマンドが出力を書く先。CLI は process の stdout・stderr、MCP は結果の文字列に集める
5
6
  */
@@ -10,6 +11,26 @@ export interface CommandIo {
10
11
  標準入力から 1 行読む(末尾の改行は含めない)。終端は undefined。渡されない io(MCP)は、入力の終端と同じ扱い
11
12
  */
12
13
  readonly readLine?: () => string | undefined;
14
+ /**
15
+ 案内の出し先。MCP の io(collectIo)だけが mcp を入れる。無ければ CLI の形
16
+ */
17
+ readonly surface?: 'cli' | 'mcp';
18
+ /**
19
+ 失敗の原因の名前を受け取る。MCP だけが渡す
20
+ */
21
+ readonly failureKind?: (kind: FailureKind) => void;
22
+ /**
23
+ 結果の行(created: など。改行を含まない)を受け取る。片付けの行は渡さない。MCP だけが渡す
24
+ */
25
+ readonly resultLine?: (line: string) => void;
26
+ /**
27
+ 成功の data の項目を受け取る。何度も渡されたら浅く重ねる(後の値が勝つ)。MCP だけが渡す
28
+ */
29
+ readonly data?: (fields: Readonly<Record<string, unknown>>) => void;
30
+ /**
31
+ warning の文(`warning: ` の前置きと字下げを除いたもの)を受け取る。MCP だけが渡す
32
+ */
33
+ readonly warning?: (text: string) => void;
13
34
  }
14
35
  /**
15
36
  コマンドの途中で、決めた終了コードで止めるための例外。defineCommand が包む run の 1 か所で捕まえて、戻り値の終了コードにする。
@@ -17,15 +38,16 @@ Python の `typer.Exit(n)` に当たる。`error:` の行や使い方の枠は
17
38
  */
18
39
  export declare class CommandExit extends BaseError {
19
40
  readonly exitCode: number;
20
- constructor(exitCode: number);
41
+ readonly kind: FailureKind;
42
+ constructor(exitCode: number, kind: FailureKind);
21
43
  }
22
44
  declare const GLOBAL_SCHEMA: z.ZodObject<{
23
45
  repo: z.ZodOptional<z.ZodString>;
24
46
  }, z.core.$strip>;
25
47
  export type GlobalInput = z.output<typeof GLOBAL_SCHEMA>;
26
- export interface CommandSpec<Input extends z.ZodObject> {
48
+ export interface CommandSpec<Input extends z.ZodObject, Output extends z.ZodObject> {
27
49
  /**
28
- `['issue', 'create']`、`['add-to-project']`
50
+ `['issue', 'create']`、`['board', 'add']`。決まりは `<対象> <動詞>` の 2 語で、どちらも英小文字だけ(names.ts の commandNameViolations)
29
51
  */
30
52
  readonly path: readonly string[];
31
53
  /**
@@ -38,6 +60,11 @@ export interface CommandSpec<Input extends z.ZodObject> {
38
60
  */
39
61
  readonly input: Input;
40
62
  /**
63
+ MCP の成功の data の型(z.strictObject)。run は createOutput<z.input<typeof output>>() の result で項目を渡す。
64
+ `.default()`・transform・z.date() は使わない(定義書への書き出しで形が変わるか、例外になる)
65
+ */
66
+ readonly output: Output;
67
+ /**
41
68
  自分の `--repo` を持つ印。真なら input に `repo` を書ける(説明は `.describe()`、形の検証は input の refine)。
42
69
  実行時の `repo` は、サブコマンドの値を先に使い、無ければグローバルの値になる
43
70
  */
@@ -64,9 +91,9 @@ export interface CommandSpec<Input extends z.ZodObject> {
64
91
  */
65
92
  readonly negations?: Readonly<Partial<Record<keyof Input['shape'] & string, string>>>;
66
93
  /**
67
- 実行して終了コードを返す。出力は io に書く
94
+ 実行して 0 を返す。出力は io に書く。失敗は CommandExit で止め、原因の名前を運ぶ
68
95
  */
69
- readonly run: (input: z.output<Input> & GlobalInput, io: CommandIo) => Promise<number>;
96
+ readonly run: (input: z.output<Input> & GlobalInput, io: CommandIo) => Promise<0>;
70
97
  /**
71
98
  CLI でだけ利用者に問うか
72
99
  */
@@ -89,6 +116,10 @@ export interface CommandDefinition {
89
116
  グローバルの repo を足した入力
90
117
  */
91
118
  readonly input: z.ZodObject;
119
+ /**
120
+ MCP の成功の data の型
121
+ */
122
+ readonly output: z.ZodObject;
92
123
  readonly positional: readonly string[];
93
124
  /**
94
125
  自分の `--repo` を持つか。真のとき、input の repo はコマンド自身の引数
@@ -121,16 +152,16 @@ export interface CommandDefinition {
121
152
  readonly run: (input: Readonly<Record<string, unknown>>, io: CommandIo) => Promise<number>;
122
153
  }
123
154
  /**
124
- path から MCP のツール名を作る。`['issue', 'create']` は issue_create、`['add-to-project']` は add_to_project
155
+ path から MCP のツール名を作る。`['issue', 'create']` は issue_create、`['board', 'add']` は board_add
125
156
  */
126
157
  export declare function toolNameOf(path: readonly string[]): string;
127
158
  /**
128
- path から定義書(interface/)の項目の ID を作る。`['create-branch']` は PW-CREATE-BRANCH、`['issue', 'create']` は PW-ISSUE-CREATE
159
+ path から定義書(interface/)の項目の ID を作る。`['session', 'start']` は PW-SESSION-START、`['issue', 'create']` は PW-ISSUE-CREATE
129
160
  */
130
161
  export declare function interfaceIdOf(path: readonly string[]): string;
131
162
  /**
132
163
  型付きの仕様から、型を消した定義を作る。parse が input で検証してから本体を呼ぶので、型を消しても安全に呼べる
133
164
  */
134
- export declare function defineCommand<Input extends z.ZodObject>(spec: Readonly<CommandSpec<Input>>): CommandDefinition;
165
+ export declare function defineCommand<Input extends z.ZodObject, Output extends z.ZodObject>(spec: Readonly<CommandSpec<Input, Output>>): CommandDefinition;
135
166
  export {};
136
167
  //# sourceMappingURL=command-definition.d.ts.map
@@ -10,24 +10,27 @@ Python の `typer.Exit(n)` に当たる。`error:` の行や使い方の枠は
10
10
  */
11
11
  export class CommandExit extends BaseError {
12
12
  exitCode;
13
- constructor(exitCode) {
13
+ kind;
14
+ constructor(exitCode, kind) {
14
15
  super(`exit ${String(exitCode)}`);
15
16
  this.exitCode = exitCode;
17
+ this.kind = kind;
16
18
  }
17
19
  }
18
20
  /**
19
21
  グローバルの --repo を入力にしたもの。全コマンドの入力に足される
20
22
  */
21
23
  const GLOBAL_SHAPE = { repo: z.string().optional() };
24
+ const RESERVED_OUTPUT_KEYS = ['reason', 'detail', 'warnings', 'log'];
22
25
  const GLOBAL_SCHEMA = z.object(GLOBAL_SHAPE);
23
26
  /**
24
- path から MCP のツール名を作る。`['issue', 'create']` は issue_create、`['add-to-project']` は add_to_project
27
+ path から MCP のツール名を作る。`['issue', 'create']` は issue_create、`['board', 'add']` は board_add
25
28
  */
26
29
  export function toolNameOf(path) {
27
- return path.join('_').replaceAll('-', '_');
30
+ return path.join('_');
28
31
  }
29
32
  /**
30
- path から定義書(interface/)の項目の ID を作る。`['create-branch']` は PW-CREATE-BRANCH、`['issue', 'create']` は PW-ISSUE-CREATE
33
+ path から定義書(interface/)の項目の ID を作る。`['session', 'start']` は PW-SESSION-START、`['issue', 'create']` は PW-ISSUE-CREATE
31
34
  */
32
35
  export function interfaceIdOf(path) {
33
36
  return `PW-${path.join(' ').toUpperCase().replaceAll(/[ _]/g, '-')}`;
@@ -50,9 +53,10 @@ async function runToExitCode(run, input, io) {
50
53
  return await run(input, io);
51
54
  }
52
55
  catch (error) {
53
- if (error instanceof CommandExit)
54
- return error.exitCode;
55
- throw error;
56
+ if (!(error instanceof CommandExit))
57
+ throw error;
58
+ io.failureKind?.(error.kind);
59
+ return error.exitCode;
56
60
  }
57
61
  }
58
62
  /**
@@ -63,10 +67,18 @@ export function defineCommand(spec) {
63
67
  throw new TypeError('コマンドの path が空です');
64
68
  const hasOwnRepository = spec.hasOwnRepo === true;
65
69
  const hasRepositoryField = Object.hasOwn(spec.input.shape, 'repo');
70
+ // eslint-disable-next-line no-restricted-syntax -- コマンドの定義の誤りで、利用者には出ない
66
71
  if (hasRepositoryField && !hasOwnRepository)
67
72
  throw new TypeError('input の repo はグローバルの --repo 用の予約名です');
68
73
  if (hasOwnRepository && !hasRepositoryField)
69
74
  throw new TypeError('hasOwnRepo のコマンドは input に repo が要ります');
75
+ // 定義書の data の成功の側を閉じた型(additionalProperties: false)にするため
76
+ if (!(spec.output.def.catchall instanceof z.ZodNever))
77
+ throw new TypeError('output は z.strictObject で書きます');
78
+ // MCP の結果の data は共通の項目を extend で重ねるので、同じ名前は知らせなしに上書きされる
79
+ const reserved = RESERVED_OUTPUT_KEYS.filter(key => Object.hasOwn(spec.output.shape, key));
80
+ if (reserved.length > 0)
81
+ throw new TypeError(`output の ${reserved.join('・')} は MCP の結果の共通の項目の予約名です`);
70
82
  assertDistinctFlags(Object.keys(spec.input.shape), spec.positional, flagMap(spec.negations));
71
83
  const aliased = Object.keys(spec.aliases ?? {});
72
84
  for (const name of aliased) {
@@ -87,6 +99,7 @@ export function defineCommand(spec) {
87
99
  toolName: toolNameOf(spec.path),
88
100
  description: spec.description,
89
101
  input,
102
+ output: spec.output,
90
103
  positional: spec.positional,
91
104
  hasOwnRepo: hasOwnRepository,
92
105
  ignoresGlobalRepo: spec.ignoresGlobalRepo === true,
@@ -81,10 +81,10 @@ function propertyOf(input, name) {
81
81
  return Object.entries(input.properties).find(([key]) => key === name)?.[1] ?? {};
82
82
  }
83
83
  /**
84
- グローバルの --repo でも満たせるので、自分の `--repo` を持つコマンドの repo は必須として出さない
84
+ グローバルの --repo でも満たせるので、自分の `--repo` を持つコマンドの repo は必須として出さない。位置引数の repo は必須と出す
85
85
  */
86
86
  function isRequiredField(definition, input, name) {
87
- return input.required.includes(name) && !(name === 'repo' && definition.hasOwnRepo);
87
+ return input.required.includes(name) && (name !== 'repo' || !definition.hasOwnRepo || definition.positional.includes('repo'));
88
88
  }
89
89
  function positionalName(name, input, isRequired) {
90
90
  const shown = isRequired ? `<${name}>` : `[${name}]`;
@@ -0,0 +1,5 @@
1
+ import type { CommandDefinition } from './command-definition.js';
2
+ export { commandHint, globalRepositoryHint, hinted, hintedTextOf, inputHint, inputNameHint, joinHinted, placeholder } from '../domain/command-hint.js';
3
+ export type { CommandHint, HintedText } from '../domain/command-hint.js';
4
+ export declare function registerCommandHints(definitions: readonly CommandDefinition[]): void;
5
+ //# sourceMappingURL=command-hint.d.ts.map
@@ -0,0 +1,13 @@
1
+ // 案内(domain/command-hint.ts)の再 export と、定義の登録。出し先は CommandIo の surface で決まり、無ければ CLI の形。
2
+ import { registerHintCommands } from '../domain/command-hint.js';
3
+ export { commandHint, globalRepositoryHint, hinted, hintedTextOf, inputHint, inputNameHint, joinHinted, placeholder } from '../domain/command-hint.js';
4
+ // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- zod の型
5
+ export function registerCommandHints(definitions) {
6
+ registerHintCommands(definitions.map(definition => ({
7
+ path: definition.path,
8
+ positional: definition.positional,
9
+ inputs: Object.keys(definition.input.shape),
10
+ hasOwnRepo: definition.hasOwnRepo,
11
+ })));
12
+ }
13
+ //# sourceMappingURL=command-hint.js.map
@@ -1,13 +1,15 @@
1
1
  import type { ProjectConfig } from '../domain/config.js';
2
+ import type { HintedText } from './command-hint.js';
3
+ import type { FailureKind } from './failure-kind.js';
2
4
  import type { Output } from './output.js';
3
5
  /**
4
6
  アクティブなプロジェクトが無いときの案内
5
7
  */
6
- export declare const NO_ACTIVE_PROJECT = "no active project\nrun: pecot project activate <PROJECT>";
8
+ export declare const NO_ACTIVE_PROJECT: HintedText;
7
9
  /**
8
- error の行を出して、指定の終了コード(既定は 1)で止める
10
+ error の行を出して、原因の名前と指定の終了コード(既定は 1)で止める
9
11
  */
10
- export declare function stopWith(out: Readonly<Output>, message: string, code?: number): never;
12
+ export declare function stopWith(out: Readonly<Output>, message: string | HintedText, kind: FailureKind, code?: number): never;
11
13
  /**
12
14
  アクティブなプロジェクトの設定を読む。無ければ案内付きの NO_ACTIVE_PROJECT を error の行にして止める
13
15
  */
@@ -1,5 +1,6 @@
1
1
  import { loadActiveConfig } from '../infra/config-store.js';
2
2
  import { CommandExit } from './command-definition.js';
3
+ import { commandHint, hinted, placeholder } from './command-hint.js';
3
4
  /**
4
5
  アクティブなプロジェクトが無いときの、案内を添えない文
5
6
  */
@@ -7,24 +8,24 @@ const NO_ACTIVE_PROJECT_PLAIN = 'no active project';
7
8
  /**
8
9
  アクティブなプロジェクトが無いときの案内
9
10
  */
10
- export const NO_ACTIVE_PROJECT = 'no active project\nrun: pecot project activate <PROJECT>';
11
+ export const NO_ACTIVE_PROJECT = hinted `no active project\nrun: ${commandHint(['project', 'activate'], { project: placeholder('PROJECT') })}`;
11
12
  /**
12
- error の行を出して、指定の終了コード(既定は 1)で止める
13
+ error の行を出して、原因の名前と指定の終了コード(既定は 1)で止める
13
14
  */
14
- export function stopWith(out, message, code = 1) {
15
+ export function stopWith(out, message, kind, code = 1) {
15
16
  out.error(message);
16
- throw new CommandExit(code);
17
+ throw new CommandExit(code, kind);
17
18
  }
18
19
  /**
19
20
  アクティブなプロジェクトの設定を読む。無ければ案内付きの NO_ACTIVE_PROJECT を error の行にして止める
20
21
  */
21
22
  export function requireActiveConfig(out) {
22
- return loadActiveConfig() ?? stopWith(out, NO_ACTIVE_PROJECT);
23
+ return loadActiveConfig() ?? stopWith(out, NO_ACTIVE_PROJECT, 'no-active-project');
23
24
  }
24
25
  /**
25
26
  requireActiveConfig の、案内を添えない形。無ければ NO_ACTIVE_PROJECT_PLAIN を error の行にして止める
26
27
  */
27
28
  export function requireActiveConfigPlain(out) {
28
- return loadActiveConfig() ?? stopWith(out, NO_ACTIVE_PROJECT_PLAIN);
29
+ return loadActiveConfig() ?? stopWith(out, NO_ACTIVE_PROJECT_PLAIN, 'no-active-project');
29
30
  }
30
31
  //# sourceMappingURL=command-stop.js.map
@@ -0,0 +1,3 @@
1
+ export declare const FAILURE_KINDS: readonly ['invalid-input', 'aborted', 'github-auth', 'github-not-found', 'github-rate-limit', 'github-api', 'config-invalid', 'project-root-not-found', 'session-directory-unresolved', 'no-active-project', 'project-not-found', 'not-initialized', 'already-exists', 'repo-not-in-project', 'repo-setting-missing', 'repo-mismatch', 'git-unresolved', 'not-on-board', 'status-not-configured', 'guard-blocked', 'not-ready', 'dependency-rejected', 'dependency-unreadable', 'order-conflict', 'content-invalid', 'preflight-failed', 'pr-state', 'git-conflict', 'partial-failure', 'other'];
2
+ export type FailureKind = typeof FAILURE_KINDS[number];
3
+ //# sourceMappingURL=failure-kind.d.ts.map
@@ -0,0 +1,35 @@
1
+ // 失敗の原因の名前。MCP の結果の kind に入る。定義書の exit_status[].kind の集合と一致させる(tests/failure-kinds-definition.test.ts)。
2
+ // eslint-disable-next-line no-restricted-syntax -- 配列から型を作るための as const
3
+ export const FAILURE_KINDS = [
4
+ 'invalid-input',
5
+ 'aborted',
6
+ 'github-auth',
7
+ 'github-not-found',
8
+ 'github-rate-limit',
9
+ 'github-api',
10
+ 'config-invalid',
11
+ 'project-root-not-found',
12
+ 'session-directory-unresolved',
13
+ 'no-active-project',
14
+ 'project-not-found',
15
+ 'not-initialized',
16
+ 'already-exists',
17
+ 'repo-not-in-project',
18
+ 'repo-setting-missing',
19
+ 'repo-mismatch',
20
+ 'git-unresolved',
21
+ 'not-on-board',
22
+ 'status-not-configured',
23
+ 'guard-blocked',
24
+ 'not-ready',
25
+ 'dependency-rejected',
26
+ 'dependency-unreadable',
27
+ 'order-conflict',
28
+ 'content-invalid',
29
+ 'preflight-failed',
30
+ 'pr-state',
31
+ 'git-conflict',
32
+ 'partial-failure',
33
+ 'other',
34
+ ];
35
+ //# sourceMappingURL=failure-kind.js.map
@@ -1,3 +1,4 @@
1
+ import type { FailureKind } from './failure-kind.js';
1
2
  import type { CommandIo } from './registry.js';
2
3
  export declare const FAILURE_EXIT_CODE = 1;
3
4
  /**
@@ -5,6 +6,11 @@ export declare const FAILURE_EXIT_CODE = 1;
5
6
  */
6
7
  export declare function isReportableFailure(error: unknown): error is Error;
7
8
  export declare function reportFailure(error: Readonly<Error>, io: CommandIo): void;
9
+ export declare const KIND_BY_CLASS: readonly (readonly [abstract new (...arguments_: never[]) => unknown, FailureKind])[];
10
+ /**
11
+ 例外のクラスから失敗の原因の名前を決める。表に無いものは other
12
+ */
13
+ export declare function kindOfFailure(error: unknown): FailureKind;
8
14
  /**
9
15
  コマンドの実行で捕まえた例外を、終了コードにする。CLI の runCli と MCP のツールの呼び出しが共有する。
10
16
  使い方の誤りは枠付きで stderr に出して 2。確認の中止は Aborted. で 1。報告できる失敗は error の行で 1。それ以外は伝える
@@ -1,7 +1,10 @@
1
1
  // コマンドが捕まえなかった例外を、最上位で `error: <message>` の行と終了コード 1 にする(Python の PecotError の網と同じ)。
2
2
  // 値の誤り(InvalidValueError)と OS のエラーも同じ行にする。上のどれでもない例外はプログラムの誤りなので、伝える。
3
- import { PecotError, InvalidValueError } from '../domain/errors.js';
3
+ import { ConfigError } from '../domain/config.js';
4
+ import { PecotError, InvalidValueError, ProjectRootNotFoundError } from '../domain/errors.js';
5
+ import { DependenciesUnsupportedError, GitHubAPIError, GitHubAuthError, GitHubNotFoundError, GitHubRateLimitError } from '../infra/github/errors.js';
4
6
  import { OsError } from '../infra/os-error.js';
7
+ import { hintedTextOf } from './command-hint.js';
5
8
  import { AbortedError, createOutput, reportAborted } from './output.js';
6
9
  import { formatUsageError, USAGE_EXIT_CODE, UsageError } from './usage-error.js';
7
10
  export const FAILURE_EXIT_CODE = 1;
@@ -12,7 +15,26 @@ export function isReportableFailure(error) {
12
15
  return error instanceof PecotError || error instanceof InvalidValueError || error instanceof OsError;
13
16
  }
14
17
  export function reportFailure(error, io) {
15
- createOutput(false, io).error(error.message);
18
+ createOutput(false, io).error(hintedTextOf(error) ?? error.message);
19
+ }
20
+ // 子クラスを親より先に並べる
21
+ export const KIND_BY_CLASS = [
22
+ [UsageError, 'invalid-input'],
23
+ [InvalidValueError, 'invalid-input'],
24
+ [AbortedError, 'aborted'],
25
+ [GitHubAuthError, 'github-auth'],
26
+ [GitHubNotFoundError, 'github-not-found'],
27
+ [GitHubRateLimitError, 'github-rate-limit'],
28
+ [DependenciesUnsupportedError, 'dependency-rejected'],
29
+ [GitHubAPIError, 'github-api'],
30
+ [ConfigError, 'config-invalid'],
31
+ [ProjectRootNotFoundError, 'project-root-not-found'],
32
+ ];
33
+ /**
34
+ 例外のクラスから失敗の原因の名前を決める。表に無いものは other
35
+ */
36
+ export function kindOfFailure(error) {
37
+ return KIND_BY_CLASS.find(([type]) => error instanceof type)?.[1] ?? 'other';
16
38
  }
17
39
  /**
18
40
  コマンドの実行で捕まえた例外を、終了コードにする。CLI の runCli と MCP のツールの呼び出しが共有する。
@@ -20,13 +42,17 @@ export function reportFailure(error, io) {
20
42
  */
21
43
  export function exitCodeOfFailure(error, io, width) {
22
44
  if (error instanceof UsageError) {
45
+ io.failureKind?.(kindOfFailure(error));
23
46
  io.stderr(formatUsageError(error, width));
24
47
  return USAGE_EXIT_CODE;
25
48
  }
26
- if (error instanceof AbortedError)
49
+ if (error instanceof AbortedError) {
50
+ io.failureKind?.(kindOfFailure(error));
27
51
  return reportAborted(io);
52
+ }
28
53
  if (!isReportableFailure(error))
29
54
  throw error;
55
+ io.failureKind?.(kindOfFailure(error));
30
56
  reportFailure(error, io);
31
57
  return FAILURE_EXIT_CODE;
32
58
  }
@@ -6,7 +6,11 @@ host 向けのクライアントを作る。host が undefined なら既定の
6
6
  */
7
7
  export declare function createGitHubClient(out: Readonly<Output>, host: string | undefined): GitHubClient;
8
8
  /**
9
- クライアントを作る。認証などの失敗は error の行にして undefined を返すので、呼び出し側は終了コード 1 で終わる
9
+ GitHub の失敗(GitHubAPIError と、接続の失敗の TransportFailure)なら、その文を返す。それ以外は投げ直す
10
10
  */
11
- export declare function makeClient(out: Readonly<Output>, config: Readonly<ProjectConfig>): GitHubClient | undefined;
11
+ export declare function apiFailureMessage(error: unknown): string;
12
+ /**
13
+ クライアントを作る。認証などの失敗は error の行にして終了コード 1 で止める
14
+ */
15
+ export declare function makeClient(out: Readonly<Output>, config: Readonly<ProjectConfig>): GitHubClient;
12
16
  //# sourceMappingURL=github-client.d.ts.map
@@ -1,5 +1,8 @@
1
+ import { TransportFailure } from '../infra/github/client.js';
1
2
  import { GitHubClient } from '../infra/github/index.js';
2
3
  import { GitHubAPIError } from '../infra/github/errors.js';
4
+ import { stopWith } from './command-stop.js';
5
+ import { kindOfFailure } from './failure.js';
3
6
  /**
4
7
  host 向けのクライアントを作る。host が undefined なら既定のホスト。トークンが無いときは GitHubAuthError を投げる
5
8
  */
@@ -7,7 +10,15 @@ export function createGitHubClient(out, host) {
7
10
  return new GitHubClient({ host, diagnostics: out });
8
11
  }
9
12
  /**
10
- クライアントを作る。認証などの失敗は error の行にして undefined を返すので、呼び出し側は終了コード 1 で終わる
13
+ GitHub の失敗(GitHubAPIError と、接続の失敗の TransportFailure)なら、その文を返す。それ以外は投げ直す
14
+ */
15
+ export function apiFailureMessage(error) {
16
+ if (error instanceof GitHubAPIError || error instanceof TransportFailure)
17
+ return error.message;
18
+ throw error;
19
+ }
20
+ /**
21
+ クライアントを作る。認証などの失敗は error の行にして終了コード 1 で止める
11
22
  */
12
23
  export function makeClient(out, config) {
13
24
  try {
@@ -16,8 +27,7 @@ export function makeClient(out, config) {
16
27
  catch (error) {
17
28
  if (!(error instanceof GitHubAPIError))
18
29
  throw error;
19
- out.error(error.message);
20
- return undefined;
30
+ return stopWith(out, error.message, kindOfFailure(error));
21
31
  }
22
32
  }
23
33
  //# sourceMappingURL=github-client.js.map
@@ -2,17 +2,11 @@
2
2
  // ルートとグループの説明。枠を使わず、コマンドごとの --help と同じ「見出し + 字下げした 2 列」の書式で出す(help-layout.ts)。
3
3
  // 節は Usage、説明、Options、Commands の順。中身の無い節は出さない。
4
4
  import { definitionSection, HELP_OPTION, helpWidth, paragraph, usageLines } from './help-layout.js';
5
+ import { COMMAND_GROUPS } from './names.js';
5
6
  export const PROGRAM_DESCRIPTION = 'pecot-workflow CLI - work tracking on GitHub Projects';
6
- const GROUP_DESCRIPTIONS = new Map([
7
- ['project', 'Manage projects through the GitHub API'],
8
- ['issue', 'Work with Issues'],
9
- ['pr', 'Work with PRs'],
10
- ['session', 'Manage the session'],
11
- ['release', 'Work with releases'],
12
- ['security', 'Put security alerts into a Tracker'],
13
- ['dependabot', 'Put Dependabot PRs waiting for a human decision into a Tracker'],
14
- ['worktree', 'Work with worktrees'],
15
- ]);
7
+ function groupHelp(name) {
8
+ return COMMAND_GROUPS.find(group => group.name === name)?.help ?? '';
9
+ }
16
10
  const ROOT_OPTIONS = [
17
11
  { name: '-v, --version', description: 'Show the version' },
18
12
  { name: '--repo <owner/repo>', description: 'Target repository, given explicitly as \'owner/repo\'' },
@@ -21,7 +15,8 @@ const ROOT_OPTIONS = [
21
15
  ];
22
16
  const ROOT_FOOTER = 'Run \'pecot COMMAND --help\' for the arguments and options of a command.';
23
17
  /**
24
- path の直下のコマンドとグループ。単独のコマンドが先、グループが後で、それぞれ登録順
18
+ path の直下のコマンドとグループを、コマンドを先にして登録順で並べる。
19
+ コマンドはどれも 2 語なので、ルートにはグループだけ、グループの下にはコマンドだけが並ぶ
25
20
  */
26
21
  function entriesOf(path, commands) {
27
22
  const level = path.length;
@@ -31,7 +26,7 @@ function entriesOf(path, commands) {
31
26
  .map(command => command.path.slice(level, level + 1).join(''));
32
27
  return [
33
28
  ...direct.map(command => ({ name: command.path.slice(level, level + 1).join(''), description: command.description })),
34
- ...[...new Set(groups)].map(name => ({ name, description: GROUP_DESCRIPTIONS.get(name) ?? '' })),
29
+ ...[...new Set(groups)].map(name => ({ name, description: groupHelp(name) })),
35
30
  ];
36
31
  }
37
32
  /**
@@ -41,7 +36,7 @@ path のグループ(空ならルート)の説明。Usage、説明、Options
41
36
  export function helpText(path, commands, columns = 80) {
42
37
  const width = helpWidth(columns);
43
38
  const isRoot = path.length === 0;
44
- const description = isRoot ? PROGRAM_DESCRIPTION : GROUP_DESCRIPTIONS.get(path.slice(0, 1).join('')) ?? '';
39
+ const description = isRoot ? PROGRAM_DESCRIPTION : groupHelp(path.slice(0, 1).join(''));
45
40
  const entries = entriesOf(path, commands);
46
41
  const sections = [
47
42
  usageLines(['pecot', ...path, '[OPTIONS] COMMAND [ARGS]...'].join(' '), width),