@open-tomato/rafa 0.45.0 → 0.47.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 (144) hide show
  1. package/README.md +285 -23
  2. package/dist/PROMPT.md +18 -1
  3. package/dist/adapters/logger/settings.d.ts +132 -0
  4. package/dist/bugs/closest.d.ts +19 -0
  5. package/dist/bugs/fenced.d.ts +8 -0
  6. package/dist/bugs/places.d.ts +20 -0
  7. package/dist/bugs/record.d.ts +145 -0
  8. package/dist/bugs/title.d.ts +83 -0
  9. package/dist/bundled/agents/doc-updater.md +17 -3
  10. package/dist/bundled/agents/loop-implementer.md +14 -2
  11. package/dist/bundled/operators/skills/rafa-stretch-pit-stop/SKILL.md +10 -3
  12. package/dist/bundled/operators/skills/rafa-stretch-sweep/SKILL.md +5 -0
  13. package/dist/bundled/skills/dev-planner/SKILL.md +101 -18
  14. package/dist/cli.js +76536 -64285
  15. package/dist/config/entry.d.ts +119 -0
  16. package/dist/config/index.d.ts +41 -0
  17. package/dist/config/index.js +54 -0
  18. package/dist/config/shape.d.ts +235 -0
  19. package/dist/config/templates.d.ts +64 -0
  20. package/dist/config-registry.d.ts +136 -0
  21. package/dist/config-schema-board-project.d.ts +157 -0
  22. package/dist/config-schema-bugs.d.ts +71 -0
  23. package/dist/config-schema-checks.d.ts +114 -0
  24. package/dist/config-schema-errors.d.ts +54 -0
  25. package/dist/config-schema-features.d.ts +64 -0
  26. package/dist/config-schema-hub.d.ts +152 -0
  27. package/dist/config-schema-issues.d.ts +95 -0
  28. package/dist/config-schema-logger.d.ts +91 -0
  29. package/dist/config-schema-loop-continue.d.ts +122 -0
  30. package/dist/config-schema-loop-retries.d.ts +94 -0
  31. package/dist/config-schema-release.d.ts +306 -0
  32. package/dist/config-schema-tests.d.ts +178 -0
  33. package/dist/config-schema-triage.d.ts +142 -0
  34. package/dist/config-schema-wrap-up.d.ts +96 -0
  35. package/dist/core/command/command.d.ts +228 -0
  36. package/dist/core/command/confirm.d.ts +73 -0
  37. package/dist/core/command/index.d.ts +130 -0
  38. package/dist/core/command/lazy.d.ts +54 -0
  39. package/dist/core/command/registry-types.d.ts +96 -0
  40. package/dist/core/command/running.d.ts +96 -0
  41. package/dist/core/command/shared-flags.d.ts +40 -0
  42. package/dist/core/command/spends.d.ts +39 -0
  43. package/dist/core/command/types.d.ts +92 -0
  44. package/dist/core/command/version.d.ts +4 -0
  45. package/dist/core/config/branch-template.d.ts +20 -0
  46. package/dist/core/config/config-items.d.ts +86 -0
  47. package/dist/core/config/config-load-module.d.ts +43 -0
  48. package/dist/core/config/config-load.d.ts +78 -0
  49. package/dist/core/config/config-origins.d.ts +58 -0
  50. package/dist/core/config/config-readers.d.ts +167 -0
  51. package/dist/core/config/config-schema.d.ts +212 -0
  52. package/dist/core/config/config-sections.d.ts +493 -0
  53. package/dist/core/config/config.d.ts +385 -0
  54. package/dist/core/config/core-section.d.ts +39 -0
  55. package/dist/core/config/dangerous.d.ts +58 -0
  56. package/dist/core/config/default-routing.d.ts +16 -0
  57. package/dist/core/config/index.d.ts +145 -0
  58. package/dist/core/config/merge-method.d.ts +40 -0
  59. package/dist/core/config/scope.d.ts +42 -0
  60. package/dist/core/config/section.d.ts +286 -0
  61. package/dist/core/config/sections.d.ts +53 -0
  62. package/dist/core/config/standard-schema.d.ts +27 -0
  63. package/dist/core/git/commit.d.ts +232 -0
  64. package/dist/core/git/gh-runner.d.ts +24 -0
  65. package/dist/core/git/git.d.ts +22 -0
  66. package/dist/core/git/index.d.ts +85 -0
  67. package/dist/core/loop/claude.d.ts +388 -0
  68. package/dist/core/loop/hop-record.d.ts +52 -0
  69. package/dist/core/loop/index.d.ts +179 -0
  70. package/dist/core/loop/session-env.d.ts +20 -0
  71. package/dist/core/loop/session-record-parse.d.ts +70 -0
  72. package/dist/core/loop/sessions.d.ts +420 -0
  73. package/dist/core/loop/suite-failure.d.ts +25 -0
  74. package/dist/core/output/active.d.ts +100 -0
  75. package/dist/core/output/stream.d.ts +20 -0
  76. package/dist/core/output/text.d.ts +55 -0
  77. package/dist/core/plan/block-reader.d.ts +46 -0
  78. package/dist/core/plan/blocks.d.ts +139 -0
  79. package/dist/core/plan/declaration.d.ts +366 -0
  80. package/dist/core/plan/plan-stamp.d.ts +75 -0
  81. package/dist/core/runtime/identity.d.ts +21 -0
  82. package/dist/core/runtime/index.d.ts +46 -0
  83. package/dist/effort/store/bring-forward.d.ts +131 -0
  84. package/dist/effort/store/check-rows.d.ts +31 -0
  85. package/dist/effort/store/commit-stats.d.ts +42 -0
  86. package/dist/effort/store/copy.d.ts +35 -0
  87. package/dist/effort/store/development-build.d.ts +105 -0
  88. package/dist/effort/store/effort-levels.d.ts +13 -0
  89. package/dist/effort/store/findings.d.ts +214 -0
  90. package/dist/effort/store/fix-schema.d.ts +184 -0
  91. package/dist/effort/store/index.js +10 -7
  92. package/dist/effort/store/location.d.ts +44 -0
  93. package/dist/effort/store/merge-commit-gaps.d.ts +68 -0
  94. package/dist/effort/store/merge-conflicts.d.ts +91 -0
  95. package/dist/effort/store/merge-rules.d.ts +82 -0
  96. package/dist/effort/store/merge-store.d.ts +211 -0
  97. package/dist/effort/store/merge-union.d.ts +92 -0
  98. package/dist/effort/store/migrate.d.ts +146 -0
  99. package/dist/effort/store/migrations.d.ts +92 -0
  100. package/dist/effort/store/ndjson-files.d.ts +114 -0
  101. package/dist/effort/store/origins.d.ts +116 -0
  102. package/dist/effort/store/plan-stubs.d.ts +79 -0
  103. package/dist/effort/store/rebuild-aside.d.ts +172 -0
  104. package/dist/effort/store/schema-plan.d.ts +102 -0
  105. package/dist/effort/store/session-row-types.d.ts +64 -0
  106. package/dist/effort/store/settings.d.ts +13 -0
  107. package/dist/effort/store/sqlite.d.ts +340 -0
  108. package/dist/effort/store/store-generation.d.ts +17 -0
  109. package/dist/effort/store/store-identity.d.ts +220 -0
  110. package/dist/effort/store/store-meta.d.ts +305 -0
  111. package/dist/effort/store/store-replaced.d.ts +72 -0
  112. package/dist/effort/store/types.d.ts +223 -0
  113. package/dist/errors/codes.d.ts +56 -0
  114. package/dist/errors/rafa-codes.d.ts +36 -0
  115. package/dist/{index-nv34ptht.js → index-38ktnyvz.js} +14 -9
  116. package/dist/index-3mwsr6wg.js +1070 -0
  117. package/dist/index-7dgc5g1t.js +13480 -0
  118. package/dist/index-cbqvgda6.js +766 -0
  119. package/dist/index-eay1bd2w.js +2632 -0
  120. package/dist/index-f1y86zbb.js +125 -0
  121. package/dist/index-n3e31fmw.js +1041 -0
  122. package/dist/{index-r28fzsvc.js → index-nwzx41g1.js} +351 -166
  123. package/dist/index-pzpb1rf7.js +153 -0
  124. package/dist/{index-mgh2s9bj.js → index-r5q2pdky.js} +65 -457
  125. package/dist/index-z1w83f81.js +4 -0
  126. package/dist/index.js +17592 -24119
  127. package/dist/learning/index.js +5 -6
  128. package/dist/plan/index.js +12 -11
  129. package/dist/plan-prompt.md +3 -1
  130. package/dist/ports/index.d.ts +732 -0
  131. package/dist/ports/learning.d.ts +101 -0
  132. package/dist/ports/log-level.d.ts +13 -0
  133. package/dist/ports/spec-review.d.ts +66 -0
  134. package/dist/ready-6p40c3gw.js +2007 -0
  135. package/dist/release-templates/release-bot-fragment.yml +153 -0
  136. package/dist/release-templates/release-publish.yml +110 -0
  137. package/dist/release-templates/release-settle.yml +122 -0
  138. package/dist/release-templates/release-tag.yml +102 -0
  139. package/dist/report/parse.d.ts +415 -0
  140. package/dist/schema/project-id.d.ts +79 -0
  141. package/dist/schema/tiers.d.ts +107 -0
  142. package/package.json +62 -3
  143. package/dist/index-hf2k497d.js +0 -16
  144. package/dist/index-nsr78ct2.js +0 -8219
@@ -0,0 +1,96 @@
1
+ /**
2
+ * The `loop.wrapUp` section of the config schema: the one setting the
3
+ * wrap-up reads when its session ends without an open pull request, with
4
+ * its field, its default, its spec and its reader.
5
+ * {@link WRAP_UP_SECTION} hands it to core as one `ConfigSection`,
6
+ * package `wrap-up`, and the `declare module` below adds
7
+ * {@link WrapUpSettings} to `RafaConfig`.
8
+ * {@link WrapUpShape} holds its part of the shared `loop` namespace,
9
+ * which `src/config/shape.ts` composes into `LoopShape` of `ConfigShape`,
10
+ * the nested file shape.
11
+ * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
12
+ * spread the objects below right after `loop.worktreeDir`, so the order
13
+ * settings are reported in holds the `loop` section together.
14
+ *
15
+ * The section has its own module, as `config-schema-release.ts` and
16
+ * `config-schema-tests.ts` do, because `config-schema.ts` stood at 578
17
+ * lines and `config-sections.ts` at 642, measured with `wc -l`, when
18
+ * this key was added: the schema module's own note asks a new section
19
+ * for a sibling, and the reader is a rule about a VALUE that only this
20
+ * key reads, so it sits here beside it. `config-registry.ts` imports this
21
+ * file to spread it; a caller reads the setting off the resolved
22
+ * `RafaConfig`.
23
+ *
24
+ * ## The key
25
+ *
26
+ * `.rafa/specs/rafa-579-loop-run-ends-delivered.md` has a loop run end
27
+ * with its pull request open. When the wrap-up session ends and no pull
28
+ * request is open for the branch, the runner spawns another wrap-up
29
+ * session that is told the pull request is missing, and
30
+ * `loop.wrapUp.retries` is how many of those it spawns before opening
31
+ * the pull request itself:
32
+ *
33
+ * - It defaults to `1`: one retry session, which costs one more
34
+ * session's spend on the run that needed it and nothing on a run
35
+ * whose first wrap-up opened the pull request.
36
+ * - It accepts a whole number from 1 to 3. Each retry is a full
37
+ * session, so the cap of 3 bounds what a run whose wrap-up keeps
38
+ * missing the pull request can spend before the runner opens it.
39
+ * - `false` means no retry: the runner goes straight to opening the
40
+ * pull request itself. It is spelled `false` and not `0`, so a
41
+ * number always names sessions that run; `0` is refused, as are a
42
+ * negative number, a fraction and anything above 3. `true` is
43
+ * refused too: it names no count, and reading it as the default
44
+ * would be a choice nobody wrote.
45
+ *
46
+ * A quoted `"2"` is refused, as every other reader refuses a string
47
+ * spelled like its type. The key is not a `CommandLineSetting`: the
48
+ * command line has no spelling for `false` or a number this module
49
+ * would not have to invent.
50
+ */
51
+ import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
52
+ import type { Reader } from '@open-tomato/rafa/core/config/sections';
53
+ declare module '@open-tomato/rafa/core/config/config-schema' {
54
+ /** The `wrap-up` section's fields, added to core's. */
55
+ interface RafaConfig extends WrapUpSettings {
56
+ }
57
+ }
58
+ /**
59
+ * `loop.wrapUp.retries`, the section's part of the shared `loop`
60
+ * namespace; `src/config/shape.ts` composes it into `LoopShape`.
61
+ */
62
+ export interface WrapUpShape {
63
+ readonly wrapUp: {
64
+ readonly retries: WrapUpRetries;
65
+ };
66
+ }
67
+ /** The fewest retry sessions `loop.wrapUp.retries` accepts as a number. */
68
+ export declare const WRAP_UP_RETRIES_MIN = 1;
69
+ /** The most retry sessions `loop.wrapUp.retries` accepts. */
70
+ export declare const WRAP_UP_RETRIES_MAX = 3;
71
+ /**
72
+ * How many retry wrap-up sessions a run spawns when its wrap-up ends
73
+ * with no pull request open, or `false` for none.
74
+ */
75
+ export type WrapUpRetries = number | false;
76
+ /** The `loop.wrapUp` section's settings, resolved. */
77
+ export interface WrapUpSettings {
78
+ /**
79
+ * The retry wrap-up sessions spawned before the runner opens the pull
80
+ * request itself, or `false` for none. `loop.wrapUp.retries`.
81
+ */
82
+ loopWrapUpRetries: WrapUpRetries;
83
+ }
84
+ /**
85
+ * Accepts `false` or a whole number from 1 to 3, each as itself; the
86
+ * module note says why `0`, `true` and a quoted number are refused.
87
+ */
88
+ export declare const wrapUpRetries: Reader<WrapUpRetries>;
89
+ /** What the `loop.wrapUp` setting resolves to when no layer names it. */
90
+ export declare const WRAP_UP_DEFAULTS: Readonly<WrapUpSettings>;
91
+ /** The `loop.wrapUp` section's setting spec. */
92
+ export declare const WRAP_UP_SETTINGS: {
93
+ readonly [K in keyof WrapUpSettings]: SettingSpec<K>;
94
+ };
95
+ /** The `wrap-up` section: `loop.wrapUp.retries`, with their defaults and no check. */
96
+ export declare const WRAP_UP_SECTION: ConfigSection;
@@ -0,0 +1,228 @@
1
+ /**
2
+ * The command rafa's dispatcher routes to: `RafaCommand`, the context it
3
+ * runs with, and `CommandExit`, the one way it refuses.
4
+ *
5
+ * The CLI surface spec declares `RafaCommand` as a superset of `cli-core`'s
6
+ * `CliCommand`, so a `cli-core` command still loads. The superset is spelled
7
+ * here over the copy in `types.ts` beside this file.
8
+ *
9
+ * ## Routing keys
10
+ *
11
+ * `subject` and `action` are the words a line routes by: `rafa loop start`
12
+ * runs the command whose subject is `loop` and whose action is `start`.
13
+ * A command whose action is its subject is a top-level command, reached
14
+ * by its one word: `status`, with subject and action both `status`. That is
15
+ * open-tomato's rule for a single-token verb, which it registers with
16
+ * tool and command equal. `name` is for display, and routes nothing.
17
+ *
18
+ * ## The context
19
+ *
20
+ * {@link RafaContext} is `CliContext` plus `argv`, the words of the line
21
+ * after the last word the dispatcher routed by, as they were typed. The
22
+ * phase 0 commands read their own flags, so a wrapper hands `argv` to
23
+ * the parser it already has. `args` and `flags` are the rest of the
24
+ * line read against the command's own `args` and `flags`, flags typed
25
+ * ahead of the subject included.
26
+ *
27
+ * It also carries `registry`, the registry the dispatcher routed the line
28
+ * through, every module mounted for the invocation included. `describe`
29
+ * reads it, so the roster it gives is the dispatcher's own and never a
30
+ * second one.
31
+ *
32
+ * And it carries `project`, the project the command runs in as
33
+ * `resolveScope` answers it (`packages/rafa/src/project/scope.ts`): its root, the home,
34
+ * and both scopes' paths. A command runs inside a project unless it
35
+ * declares `needsProject: false`. The dispatcher resolves the project
36
+ * before any other command runs, and runs none outside a project, so
37
+ * such a command's `project` is never null. For a command declaring
38
+ * `needsProject: false`, as `module exec`, `init` and `describe` do, it resolves
39
+ * nothing, and `project` is null inside a project as outside one.
40
+ *
41
+ * `run` takes a `RafaContext`, where `CliCommand.run` takes a
42
+ * `CliContext`, so the interface extends `CliCommand` without its `run`.
43
+ * A `RafaContext` is a `CliContext`, so a `run` written against
44
+ * `CliContext` is assignable to this one.
45
+ *
46
+ * ## Refusing
47
+ *
48
+ * A command refuses by throwing {@link CommandExit} with an exit code. The
49
+ * dispatcher is the only place that turns one into the process's exit
50
+ * code and the invocation's terminal event. A `process.exitCode` a
51
+ * command sets is not read, and a command setting one and returning is
52
+ * a success to the dispatcher.
53
+ *
54
+ * ## The shape check
55
+ *
56
+ * {@link commandProblem} answers what keeps a value from being a
57
+ * `RafaCommand`, for a roster the type checker never saw: a module's
58
+ * command entry is imported at run time. It checks the shape and not
59
+ * the content, so an empty `summary` or an empty `examples` list passes.
60
+ * The registry refuses a core command it answers for, and the module
61
+ * loader skips the file of a module command it answers for.
62
+ *
63
+ * `spends` is checked last, by `spendsProblem` (`spends.ts` beside this file),
64
+ * whose sentence names the field inside it: `spends.flag is "resolve",
65
+ * expected a flag as typed, starting with --`. A module entry declaring a
66
+ * malformed `spends` is therefore skipped like any other bad shape.
67
+ *
68
+ * ## Dangerous phrases
69
+ *
70
+ * `dangerous` maps a `dangerous.*` key to the phrase naming what the
71
+ * command does under it: `{ 'dangerous.acceptVersionCollision': 'a
72
+ * release guard reading collision merges anyway' }`. The dispatcher
73
+ * runs the command inside `runWithDangerousPhrases`
74
+ * (`packages/rafa/src/core/config/dangerous.ts`) with it, so a pass line the loader
75
+ * writes for a declared key during the run ends with `; <phrase>`. The
76
+ * shape check refuses a key not opening with `dangerous.` and a phrase
77
+ * that is not a non-empty string.
78
+ *
79
+ * ## Deprecated flags
80
+ *
81
+ * A flag a command declares is a {@link RafaFlagSpec}: a `FlagSpec` that
82
+ * may carry `deprecated`, naming the spelling to type instead. The
83
+ * dispatcher reads such a flag, typed bare, as that spelling and writes
84
+ * one deprecation line (`src/cli/dispatch.ts`), so
85
+ * `rafa effort report --json` runs as `rafa effort report --output=json`.
86
+ * The field is declared here rather than on `FlagSpec`, so the copy of
87
+ * `cli-core`'s contracts in `types.ts` keeps the source's shape.
88
+ */
89
+ import type { CommandRegistry } from './registry-types.js';
90
+ import type { CommandSpend } from './spends.js';
91
+ import type { CliCommand, CliContext, FlagSpec } from './types.js';
92
+ import type { DangerousPhrases } from '../config/dangerous.js';
93
+ import type { ProjectFound } from '../config/scope.js';
94
+ /** What an action can render: text a person reads, NDJSON events, one line per loop event, or the TUI. */
95
+ export declare const COMMAND_OUTPUTS: readonly ["text", "json", "events", "tui"];
96
+ /** One of the four renderings an action declares. */
97
+ export type CommandOutput = (typeof COMMAND_OUTPUTS)[number];
98
+ /** One example a command's help lists. */
99
+ export interface CommandExample {
100
+ /** The line as a person types it: `rafa loop start --plan=PLAN-x.md`. */
101
+ readonly cmd: string;
102
+ /** What the line does, in a sentence. */
103
+ readonly note: string;
104
+ }
105
+ /** Why a command is deprecated, and what to type instead. */
106
+ export interface CommandDeprecation {
107
+ /** The version the command was deprecated in. */
108
+ readonly since: string;
109
+ /** The spelling to use instead, after `rafa`: `loop start`. */
110
+ readonly use: string;
111
+ }
112
+ /** What a deprecated flag is read as, which is also what to type instead. */
113
+ export interface FlagDeprecation {
114
+ /**
115
+ * The spelling to type instead, `--output=json`: the words, joined by
116
+ * one space, the dispatcher reads the flag as.
117
+ */
118
+ readonly use: string;
119
+ }
120
+ /** A flag a rafa command declares: a `FlagSpec`, which may be a deprecated spelling. */
121
+ export interface RafaFlagSpec extends FlagSpec {
122
+ /** Set when the flag is a deprecated spelling; see the module note. */
123
+ readonly deprecated?: FlagDeprecation;
124
+ }
125
+ /** Everything a rafa command runs with. */
126
+ export interface RafaContext extends CliContext {
127
+ /** The words after the last word the line was routed by, as typed. */
128
+ readonly argv: readonly string[];
129
+ /** The registry the line was routed through, every module mounted for the invocation included. */
130
+ readonly registry: CommandRegistry;
131
+ /** The project the command runs in, or null for a command declaring `needsProject: false`; see the module note. */
132
+ readonly project: ProjectFound | null;
133
+ }
134
+ /** A command the dispatcher routes to by its subject and action. */
135
+ export interface RafaCommand extends Omit<CliCommand, 'run'> {
136
+ /** The first routing word: `loop` in `rafa loop start`. */
137
+ readonly subject: string;
138
+ /** The second routing word: `start`. Equal to `subject` for a top-level command. */
139
+ readonly action: string;
140
+ /** One line for the subject's roster. `description` may be longer. */
141
+ readonly summary: string;
142
+ /** The flags, any of them a deprecated spelling. */
143
+ flags: RafaFlagSpec[];
144
+ /** The examples help lists. */
145
+ readonly examples: readonly CommandExample[];
146
+ /**
147
+ * Whole other spellings of the command, each printing one deprecation
148
+ * line when typed, `start` for `loop start`, unless it is also one of
149
+ * {@link RafaCommand.lastingAliases}. Routed for a core command only; a
150
+ * module's command is reached through an `exec` action alone.
151
+ */
152
+ readonly aliases?: readonly string[];
153
+ /**
154
+ * The aliases, each also listed in `aliases`, kept for good rather than
155
+ * for one release: typed, they print no deprecation line. `epic` for
156
+ * `epic show`, which `rafa epics` reaches through the subject's plural.
157
+ */
158
+ readonly lastingAliases?: readonly string[];
159
+ /** What the action can render. */
160
+ readonly outputs: readonly CommandOutput[];
161
+ /** Set when the command itself is deprecated; typing it prints one deprecation line. */
162
+ readonly deprecated?: CommandDeprecation;
163
+ /** Out of every roster, and still dispatched. */
164
+ readonly hidden?: boolean;
165
+ /**
166
+ * The action delegates to a module: the word after it names a module
167
+ * mounted as `module/<name>`, and the word after that one of the
168
+ * module's actions.
169
+ */
170
+ readonly exec?: true;
171
+ /**
172
+ * False for a command that runs outside a project too, which the
173
+ * dispatcher resolves no project for: `module exec`, `init` and
174
+ * `describe`. Absent,
175
+ * the command runs inside a project; see the module note.
176
+ */
177
+ readonly needsProject?: boolean;
178
+ /**
179
+ * Whether running the command can start a Claude Code session, and
180
+ * under what condition; absent, it spends nothing. See `spends.ts`
181
+ * beside this file.
182
+ */
183
+ readonly spends?: CommandSpend;
184
+ /**
185
+ * What the command does under each `dangerous.*` key it declares, as a
186
+ * phrase the loader's pass line for that key ends with after `; `.
187
+ * The dispatcher sets it for the command's run; see "Dangerous
188
+ * phrases" in the module note.
189
+ */
190
+ readonly dangerous?: DangerousPhrases;
191
+ /** Runs the command. Throws {@link CommandExit} to refuse. */
192
+ readonly run: (context: RafaContext) => Promise<void>;
193
+ }
194
+ /**
195
+ * Thrown by a command to end its invocation with an exit code: nonzero to
196
+ * refuse, 0 to stop early as a success.
197
+ *
198
+ * The message, when it is not empty, is what the dispatcher tells the
199
+ * reader: on stderr in text mode, in the terminal event in json mode.
200
+ *
201
+ * `options` goes to `Error` as it is, so a `cause` given there is kept on
202
+ * the refusal: `new CommandExit(3, 'refused', { cause: error })` reads the
203
+ * error back as `exit.cause`.
204
+ */
205
+ export declare class CommandExit extends Error {
206
+ /** The exit code the invocation ends with, from 0 to 255. */
207
+ readonly exitCode: number;
208
+ /**
209
+ * Throws a `TypeError` when `exitCode` is not a whole number from 0 to 255,
210
+ * whatever `options` holds.
211
+ */
212
+ constructor(exitCode: number, message?: string, options?: ErrorOptions);
213
+ }
214
+ /**
215
+ * True when a value is a word a line can route by: no space, no slash and
216
+ * no leading dash. The slash is kept for the `module/<name>` mount keys,
217
+ * so no subject is spelled as one.
218
+ */
219
+ export declare function isRoutingWord(value: unknown): value is string;
220
+ /**
221
+ * What keeps `value` from being a `RafaCommand`, as a sentence naming the
222
+ * command when it can, or null when nothing does. See the module note.
223
+ */
224
+ export declare function commandProblem(value: unknown): string | null;
225
+ /** True when a command is top-level: its action is its subject. */
226
+ export declare function isTopLevel(command: Pick<RafaCommand, 'subject' | 'action'>): boolean;
227
+ /** A command's canonical spelling after `rafa`: `loop start`, or `status` for a top-level command. */
228
+ export declare function commandSpelling(command: Pick<RafaCommand, 'subject' | 'action'>): string;
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The line prompter: the one prompt that reads whole lines, not keys as
3
+ * `src/cli/prompt/`'s do, so it needs no raw mode and works on a pipe as
4
+ * well as on a terminal. Every yes-or-no question rafa asks, and the root
5
+ * `rafa init` reads, goes through a {@link Prompter}; the commands take
6
+ * one from {@link createLinePrompter} over `process.stdin` and
7
+ * `process.stderr`, and tests pass a scripted one.
8
+ *
9
+ * ## The prompter
10
+ *
11
+ * {@link createLinePrompter} reads lines from a stream with `readline`'s
12
+ * `line` and `close` events, and writes each question and each thing it
13
+ * says to another stream. It does not use `readline/promises`: measured
14
+ * on bun 1.3.14, a `question` pending when its input ends never settles,
15
+ * where the `close` event fires. The final line of an input that ends
16
+ * without a line break is still delivered as a line, measured the same
17
+ * way. readline is given no output and `terminal: false`, so on a
18
+ * terminal the terminal's own line discipline echoes and edits what is
19
+ * typed.
20
+ *
21
+ * Two line prompters over one input both receive every line, so a
22
+ * command handing a question to another closes its own first.
23
+ *
24
+ * ## The lazy prompter
25
+ *
26
+ * {@link lazyPrompter} wraps the opening of a prompter so a run that
27
+ * never asks opens nothing: the prompter is opened at the first
28
+ * question, kept for the next, and closed by `close`, after which the
29
+ * next question opens a fresh one. It asks in two forms over the one
30
+ * prompter: `askLine` answers the line as typed, or null once the input
31
+ * has ended, for a question that reads its own answer; `ask` is the yes
32
+ * reading over `askLine`, whether the line typed means yes: `y` or `yes`,
33
+ * trimmed and in any case, the reading every `[y/N]` question in rafa
34
+ * makes. Anything else declines, the empty answer and the null of an
35
+ * input that ended included. `issue ready`, `issue unblock`, `next`,
36
+ * `cleanup` and `plan create`'s three offers ask through `ask`, and
37
+ * `epic defer` and `epic promote` through `askLine`.
38
+ */
39
+ import type { Readable } from 'node:stream';
40
+ /** Asks an operator, and tells them what went wrong. */
41
+ export interface Prompter {
42
+ /** Writes `text` and a line break. */
43
+ readonly say: (text: string) => void;
44
+ /** Writes `question` and answers the next line typed, or null once the input has ended. */
45
+ readonly ask: (question: string) => Promise<string | null>;
46
+ /** Stops reading the input. */
47
+ readonly close: () => void;
48
+ }
49
+ /** A prompter opened at its first question, see the module note. */
50
+ export interface LazyPrompter {
51
+ /** Opens the prompter if it is not open, asks `question` and answers the line typed, or null once the input has ended. */
52
+ readonly askLine: (question: string) => Promise<string | null>;
53
+ /** Opens the prompter if it is not open, asks `question` and answers whether the line typed means yes. */
54
+ readonly ask: (question: string) => Promise<boolean>;
55
+ /** Closes the prompter if one is open; the next question opens another. */
56
+ readonly close: () => void;
57
+ }
58
+ /** A stream the prompter writes to: `process.stderr`, or a test's own. */
59
+ export interface PromptOutput {
60
+ readonly write: (chunk: string) => unknown;
61
+ }
62
+ /**
63
+ * A {@link Prompter} reading lines from `input` and writing to `output`;
64
+ * see the module note. A line typed before it is asked for is kept for
65
+ * the next question.
66
+ */
67
+ export declare function createLinePrompter(input: Readable, output: PromptOutput): Prompter;
68
+ /**
69
+ * A {@link LazyPrompter} over `open`, which is called at the first
70
+ * question and again at the first one after each `close`; see the
71
+ * module note.
72
+ */
73
+ export declare function lazyPrompter(open: () => Prompter): LazyPrompter;
@@ -0,0 +1,130 @@
1
+ /**
2
+ * The barrel over the command contract: every name `command.ts`,
3
+ * `confirm.ts`, `lazy.ts`, `registry-types.ts`, `running.ts`,
4
+ * `shared-flags.ts`, `spends.ts`, `types.ts` and `version.ts` export,
5
+ * and nothing else.
6
+ *
7
+ * A file outside `packages/rafa/src/core/` imports this file and never the nine
8
+ * behind it (`scripts/survey/core-barrels.ts` measures that, and
9
+ * `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
10
+ * file inside `packages/rafa/src/core/` imports the nine directly and never this
11
+ * file.
12
+ *
13
+ * ## What sits behind it
14
+ *
15
+ * - `command.ts`: `RafaCommand`, the `RafaContext` it runs with,
16
+ * `CommandExit`, the routing words and the shape check;
17
+ * - `confirm.ts`: the `Prompter` every yes-or-no question goes
18
+ * through, the line prompter that reads one from a stream, and the
19
+ * lazy prompter that opens one only to ask;
20
+ * - `lazy.ts`: `CommandDeclaration`, a command less its `run`, and
21
+ * `lazyCommand`, the command over a declaration whose `run` imports
22
+ * the command's module and delegates to its default export;
23
+ * - `registry-types.ts`: the contract of the dispatcher's registry,
24
+ * `CommandRegistry` and the five shapes it names, and
25
+ * `CommandFeature`, what one feature contributes to it, whose
26
+ * builder stays in `src/cli/registry.ts`;
27
+ * - `running.ts`: the command this process is running with its parsed
28
+ * flags, recorded by the dispatcher and read by the spend guard;
29
+ * - `shared-flags.ts`: the flags commands of several features
30
+ * declare, spelled once: `HINT_FLAG` and `HINT_FLAG_SPEC`, the
31
+ * `--no-hint` flag of the six commands that end with a hint, and
32
+ * `DEFAULT_CI_TIMEOUT_MIN`, the default of the loop's
33
+ * `--ci-timeout` and of `pr wait`'s `--timeout`;
34
+ * - `spends.ts`: a command's `spends` declaration, `CommandSpend`, its
35
+ * shape check and the mark help ends a spender's roster line with;
36
+ * - `types.ts`: the contracts copied from open-tomato's `cli-core`,
37
+ * `CliContext`, `CliCommand`, `ArgSpec` and `FlagSpec`, which
38
+ * `RafaCommand` extends;
39
+ * - `version.ts`: the version the running build answers with, and the
40
+ * line that spells it.
41
+ *
42
+ * The nine hold no name in common, so each name is exported once and
43
+ * from the file that declares it.
44
+ *
45
+ * ## Why one barrel can hold all nine
46
+ *
47
+ * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
48
+ * imports the barrel back by value is a runtime cycle. None of the nine
49
+ * imports a file outside `packages/rafa/src/core/` by value. `command.ts` takes
50
+ * `spendsProblem` from `spends.ts` beside it, and both take
51
+ * `describeValue` from `packages/rafa/src/core/config/config-sections.ts`.
52
+ * `lazy.ts` takes the shape check, `CommandExit` and `commandSpelling`
53
+ * from `command.ts`, and `messageOf` from the same config file; the
54
+ * module a lazy command loads is the caller's `load()`, imported when
55
+ * the command runs, never by `lazy.ts` itself.
56
+ * `confirm.ts` and `running.ts` import `node:` modules alone by value,
57
+ * `running.ts` naming `command.ts` and `types.ts` with `import type`.
58
+ * `version.ts` imports the root `package.json`, and `types.ts` nothing
59
+ * by value: it names `packages/rafa/src/core/config/config-sections.ts` and the
60
+ * `Output` port with `import type`. `registry-types.ts` imports nothing
61
+ * by value either: it names `command.ts` with `import type`, and this
62
+ * file exports its names with `export type`, so loading the barrel
63
+ * never loads it. `shared-flags.ts` imports nothing by value either: it
64
+ * names `command.ts` with `import type` alone.
65
+ *
66
+ * `command.ts` also names `packages/rafa/src/project/scope.ts` with `import type`,
67
+ * which is erased before anything loads; it named `src/cli/registry.ts`
68
+ * the same way until the registry's contract moved into
69
+ * `registry-types.ts`. `src/cli/registry.ts` imports this barrel by
70
+ * value, for the shape check and the routing words, so that edge is the
71
+ * one a value import in `command.ts` would turn into a cycle.
72
+ *
73
+ * Measured when the three moved: the value imports of the non-test files
74
+ * under `src/` and `packages/` held six cycles before the move and the
75
+ * same six after it, none through a file of this folder. The control,
76
+ * the same tree with `command.ts` taking one value (`HELP_WORD`) from
77
+ * `src/cli/registry.ts`, held a seventh: `src/cli/registry.ts`,
78
+ * `command.ts` and this file.
79
+ *
80
+ * Measured again when `types.ts` moved in, over every strongly connected
81
+ * set of the same value imports: five cycles at the base and five after
82
+ * the move, none through a file of this folder or of `src/cli/core/`.
83
+ * The same `HELP_WORD` control held a sixth, `src/cli/registry.ts`,
84
+ * `command.ts` and this file.
85
+ *
86
+ * Measured again when `spends.ts` moved in, the same way: five cycles at
87
+ * the base and five after the move, none through a file of this folder
88
+ * or of `src/cli/`. The same `HELP_WORD` control held a sixth,
89
+ * `src/cli/registry.ts`, `command.ts` and this file.
90
+ *
91
+ * Measured again when the registry's contract moved into
92
+ * `registry-types.ts`, the same way: five cycles at the base and five
93
+ * after the move, none through a file of this folder or of `src/cli/`.
94
+ * The same `HELP_WORD` control held a sixth, `src/cli/registry.ts`,
95
+ * `command.ts` and this file.
96
+ *
97
+ * Measured again when `shared-flags.ts` moved in, the same way and with
98
+ * the untracked new file read: five cycles at the base and four after
99
+ * the move, none through a file of this folder. The one gone is
100
+ * `src/next/actions.ts` and `src/next/hint.ts`, broken because
101
+ * `actions.ts` now takes `HINT_FLAG` from this barrel rather than from
102
+ * `hint.ts`. The control, `shared-flags.ts` taking one value
103
+ * (`HINT_TIMEOUT_MS`) from `src/next/hint.ts`, folded this file,
104
+ * `shared-flags.ts` and `hint.ts` into one strongly connected set of
105
+ * seventy files.
106
+ *
107
+ * ## What it exports
108
+ *
109
+ * Each name is spelled, types apart from values, as the config barrels
110
+ * spell theirs. No name here is part of the published surface:
111
+ * `src/index.ts` re-exports nothing from this file.
112
+ *
113
+ * `index.test.ts` holds the list to the nine files: every name any of
114
+ * them exports is here once, as the same binding, and no other name is
115
+ * here.
116
+ */
117
+ export type { CommandDeprecation, CommandExample, CommandOutput, FlagDeprecation, RafaCommand, RafaContext, RafaFlagSpec, } from './command.js';
118
+ export type { LazyPrompter, PromptOutput, Prompter } from './confirm.js';
119
+ export type { CommandDeclaration } from './lazy.js';
120
+ export type { CommandAlias, CommandFeature, CommandRegistry, CommandRegistryInput, ModuleMount, RosterOptions, SubjectSpec, } from './registry-types.js';
121
+ export type { RunningCommand } from './running.js';
122
+ export type { CommandSpend, SpendsWhen } from './spends.js';
123
+ export type { ArgSpec, CliCommand, CliContext, FlagSpec, } from './types.js';
124
+ export { COMMAND_OUTPUTS, CommandExit, commandProblem, commandSpelling, isRoutingWord, isTopLevel, } from './command.js';
125
+ export { createLinePrompter, lazyPrompter } from './confirm.js';
126
+ export { lazyCommand } from './lazy.js';
127
+ export { restoreRunningCommand, runAsRunningCommand, runningCommand, setRunningCommand, } from './running.js';
128
+ export { DEFAULT_CI_TIMEOUT_MIN, HINT_FLAG, HINT_FLAG_SPEC } from './shared-flags.js';
129
+ export { SPENDS_GLYPH, SPENDS_WHEN, spendsCondition, spendsMark, spendsProblem, } from './spends.js';
130
+ export { RAFA_VERSION, versionLine } from './version.js';
@@ -0,0 +1,54 @@
1
+ /**
2
+ * A command whose module is imported when it runs, not when the roster
3
+ * is built: {@link lazyCommand} over a {@link CommandDeclaration}.
4
+ *
5
+ * ## What is declared and what is loaded
6
+ *
7
+ * A declaration is a `RafaCommand` less its `run`: every field routing,
8
+ * help, `describe` and the spend guard read, so a roster of lazy
9
+ * commands is built, routed and rendered without importing one command
10
+ * module. The lazy command is the declaration spread under a `run` of
11
+ * its own, so it passes `commandProblem` (`command.ts` beside this
12
+ * file) as the declaration's fields stand.
13
+ *
14
+ * Its `run` awaits `load()`, typically `() => import('./x.js')`, and
15
+ * holds the module's default export to a command: one `commandProblem`
16
+ * accepts, whose subject and action are the declaration's. It then hands
17
+ * the context to that command's `run` and settles as that `run`
18
+ * settles, a `CommandExit` it throws included. The loaded command's
19
+ * other fields are not compared with the declaration's: the dispatcher
20
+ * routed, parsed and guarded by the declaration's before `run` was
21
+ * called.
22
+ *
23
+ * ## Refusing
24
+ *
25
+ * A load that rejects, a default export `commandProblem` refuses, and a
26
+ * default export spelled as another command each refuse with
27
+ * `CommandExit(1, message)`, the message reading
28
+ * `feature "<feature>": command "<spelling>" failed to load: <reason>`.
29
+ * The spelling is `commandSpelling`'s, so a top-level command reads as
30
+ * its one word, as every other refusal naming a command spells it. The
31
+ * reason is the rejection's message, the shape check's sentence, or the
32
+ * spelling the export has against the one declared.
33
+ *
34
+ * Nothing is cached here: a second run calls `load()` again, and the
35
+ * module loader's own cache answers it.
36
+ */
37
+ import type { RafaCommand } from './command.js';
38
+ /** A command less its `run`: what a feature declares for a command it loads when run. */
39
+ export type CommandDeclaration = Omit<RafaCommand, 'run'>;
40
+ /** What a command module's import resolves to: the command is its default export. */
41
+ type CommandModule = {
42
+ readonly default?: unknown;
43
+ } | null | undefined;
44
+ /**
45
+ * A command spreading `declaration` under a `run` that loads the
46
+ * command and delegates to it. See the module note.
47
+ *
48
+ * @param declaration - Every field of the command but its `run`.
49
+ * @param load - Imports the command's module, whose default export is the command.
50
+ * @param feature - The name of the feature the command belongs to, which a refusal names.
51
+ * @returns The lazy command.
52
+ */
53
+ export declare function lazyCommand(declaration: CommandDeclaration, load: () => Promise<CommandModule>, feature: string): RafaCommand;
54
+ export {};