@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,385 @@
1
+ /**
2
+ * Reading rafa's settings: the phase 1 schema of the config files
3
+ * (`.rafa/config.yaml`, `rafa.config.ts` or `rafa.config.mjs`).
4
+ *
5
+ * Four files rank, two per scope ({@link ConfigLayers}): the project's
6
+ * local file over the project's file, then the user scope's local file
7
+ * over the user scope's file under `~/.rafa/`. A scope's local file is
8
+ * its `.rafa/config.yaml`, read over the scope's module file key by key;
9
+ * which file on disk fills each layer is `config-load.ts`'s to say.
10
+ * Every setting takes the value the COMMAND LINE gave it, else the
11
+ * value of the first of the four files, in that order, that gave it one,
12
+ * else its default; a map setting merges by key in the reverse order,
13
+ * the default under the user's files under the project's. Each
14
+ * setting is ranked on its own, so a flag naming one leaves the others
15
+ * to the files and a file naming one leaves the others to the files
16
+ * under it, and {@link ResolvedConfig.sources} records which layer
17
+ * answered each. That record keeps precedence observable when two
18
+ * layers agree: a file spelling the default still reports its layer,
19
+ * where the value alone could not tell a file that was read from one
20
+ * that was skipped. `local` names the project's local file and `file`
21
+ * the project's other file, as it did when that was the only file read;
22
+ * `user` names either of the user scope's, and the origin in
23
+ * {@link ResolvedConfig.provenance}, read off the file that answered,
24
+ * tells the two apart.
25
+ *
26
+ * A file may name config templates with its `templates` key, and each
27
+ * template's entry sits under that file's own keys and over every lower
28
+ * file: each of the four over its own templates over the next file down,
29
+ * the last over the default. A setting a template answered and no
30
+ * file outranked reports `template`, and its `provenance` names the
31
+ * template and the file that named it. {@link layTemplatesUnder} lays
32
+ * them; `config-load.ts` reads them through the template hook.
33
+ *
34
+ * This module is the pure half: text, or a document already parsed,
35
+ * into a layer, and layers into one resolution. Finding and reading each
36
+ * scope's file, behind a home seam, is `config-load.ts`, which reads a
37
+ * module file's merged entries through the same {@link readConfigDocument}
38
+ * a YAML file's document goes through. Scope resolution and `rafa init`
39
+ * are not here.
40
+ *
41
+ * ## Where the rules live
42
+ *
43
+ * The reader is three modules and a helper of the schema's, and a name
44
+ * moving between them is a refactor, never a change of behaviour. This
45
+ * file is intended as the public surface, re-exporting everything the
46
+ * other two modules export for a caller to import rather than reaching
47
+ * into a sibling; however, most
48
+ * callers import `config-sections.ts`'s names directly,
49
+ * through its barrel `core/config/sections.js`. `MergeMethod`, the type
50
+ * of {@link RafaConfig.prMergeMethod}, is `merge-method.ts`'s, exported
51
+ * by that barrel and re-exported by the pull request port
52
+ * (`src/pr/types.ts`); this module does not re-export it.
53
+ *
54
+ * - `config-sections.ts` holds every rule about a VALUE: the readers,
55
+ * the closed lists of values, and why nothing is coerced.
56
+ * - `config-items.ts` holds the prerequisite item and module source
57
+ * shapes, read through the helpers `config-sections.ts` exports.
58
+ * This module re-exports its types and kind lists, as it did while
59
+ * they sat in `config-sections.ts`.
60
+ * - The rules about a KEY sit in three modules. `config-schema.ts`
61
+ * declares {@link RafaConfig}'s core fields and the setting types,
62
+ * and exports no value. `core-section.ts` holds core's file keys,
63
+ * specs and defaults, and {@link CONFIG_FILE}. `section.ts` holds
64
+ * the registry the sections are handed to, and the setting, section
65
+ * and known-key indexes it reads off the registered specs. This
66
+ * module reads each spec, each default and every index off that
67
+ * registry, and names no section. `src/config-registry.ts`, outside
68
+ * `packages/rafa/src/core/`, lists the sections and exports the merged schema,
69
+ * `CONFIG_DEFAULTS` and `SETTINGS` among it. The four readings the
70
+ * spec leaves to the reader — open tracker kinds, empty
71
+ * prerequisite tiers, `version: 1` alone, and `loop.settingSources`
72
+ * as an ordered list — are argued in `core-section.ts`; the readings each
73
+ * later section's spec leaves are argued in
74
+ * `config-schema-readings.ts`, a note that exports nothing, except
75
+ * the `pr` and `release` sections', which sit with their fields in
76
+ * `config-schema-release.ts`, the `tests` section's, which sit
77
+ * with theirs in `config-schema-tests.ts`, the `triage`
78
+ * section's, in `config-schema-triage.ts`, and the `errors`
79
+ * section's, in `config-schema-errors.ts`, each handed to core as
80
+ * a section by `src/config-registry.ts`.
81
+ * - `config-readers.ts` holds `mapOf` and the named readers
82
+ * `core-section.ts` reads its settings through. No caller reads a
83
+ * setting through them but the schema, so nothing here re-exports
84
+ * them.
85
+ * - This module holds the rules about LAYERS: which layer answers a
86
+ * setting, what a file may carry, and what is refused.
87
+ *
88
+ * The split is what keeps each under the 800-line cap of
89
+ * `context/source.md`, which no gate reads. Measured with `wc -l` at the
90
+ * commit that added the `pr` section: `config.ts` is 506 lines,
91
+ * `config-schema.ts` 396 and `config-sections.ts` 478. A new setting is
92
+ * one field in `config-schema.ts` with one default and one spec in
93
+ * `core-section.ts` (in
94
+ * `config-schema-release.ts` for a `pr` or `release` key, in
95
+ * `config-schema-tests.ts` for a `tests` key, in
96
+ * `config-schema-triage.ts` for a `triage` key, in
97
+ * `config-schema-errors.ts` for an `errors` key), and its reader
98
+ * in `config-sections.ts`. Nothing here names it: {@link readLayer}
99
+ * and {@link resolveConfig} loop over the names registered with
100
+ * `section.ts` (`activeSettings()`) and take each default from
101
+ * `activeDefaults()`, so a layer and a resolution hold every registered
102
+ * setting, in registration order. `src/config-registry.ts`, outside
103
+ * `packages/rafa/src/core/`, registers the fourteen sections when its
104
+ * `registerCoreConfigSections` is called; a process that has not called
105
+ * it reads no setting at all, where the
106
+ * literal this loop replaced held every setting whatever was registered.
107
+ *
108
+ * {@link parseConfigText} turns YAML text into one file layer and
109
+ * {@link resolveConfig} ranks the layers. Both are pure, so every
110
+ * precedence case is tested without a disk. The only read and the only
111
+ * place that prints are in `config-load.ts`.
112
+ *
113
+ * ## Unknown keys and unusable values
114
+ *
115
+ * The two are treated differently, and the difference is who the file
116
+ * was written for.
117
+ *
118
+ * - An UNKNOWN key is retained and warned about, never refused. It
119
+ * lands in {@link ConfigFile.extras} under its path (`nonesuch`,
120
+ * `plan.depth`, `prerequisites.required[0].timeout`) with the value
121
+ * it carried, and acts on nothing. A file written for a later phase
122
+ * names keys this one has never heard of; refusing them would make
123
+ * every addition to the schema a breaking change for older
124
+ * installs. That is the reason `core/plan/declaration.ts` keeps an
125
+ * unrecognised declaration key in its `extras`, and it holds here
126
+ * unchanged. The warning lists the keys known where the unknown one
127
+ * sits: the top level's, a section's, or an item's.
128
+ * - An UNUSABLE value for a key this module DOES answer to is
129
+ * refused with a {@link ConfigError}. `store: postgres` asks for a
130
+ * backend nothing here provides, and falling back to the default
131
+ * would write rows into a store other than the one the operator
132
+ * named — a silent success, the failure the collector refuses an
133
+ * unrecognised argument to prevent. Every problem is collected
134
+ * before the throw, so one run names all of them. A section that is
135
+ * not a mapping is one: `tracker: linear` is refused, where a
136
+ * phase 0 file could carry it as an unknown key.
137
+ *
138
+ * A refusal that reads two settings at once is a section's `checks`
139
+ * (`section.ts`), since the two may come from different files:
140
+ * {@link resolveConfig} runs every registered section's checks once
141
+ * every setting is ranked and throws one {@link ConfigError} with every
142
+ * problem they report. The one check today is the `hub` section's,
143
+ * `effort.sync: service` with no `hub.url` in any layer, naming the
144
+ * file that chose `service`; `config-schema-hub.ts` argues it.
145
+ *
146
+ * A file is judged whole, whatever the command line says. A flag that
147
+ * outranks an unusable file value does not excuse it, because the next
148
+ * run without the flag reads it.
149
+ *
150
+ * A `null` value says nothing; it is neither a value nor a problem.
151
+ * YAML makes `null` of a key whose children are all commented out —
152
+ * `plan:` above ` # inject: full` parses to `{ plan: null }` — and
153
+ * refusing it would punish the commonest edit a config file receives.
154
+ * Three settings RESOLVE to null — `pr.provider`, `pr.base` and
155
+ * `roadmap.issue` — and the rule holds for them unchanged: a file naming one with no value is
156
+ * silent, and silence there resolves to the same null from the defaults
157
+ * layer, reported as `default` rather than `file`. What null means to a
158
+ * caller is `core-section.ts`'s and `config-schema-release.ts`'s to say.
159
+ *
160
+ * A setting's dotted path is built by joining keys, so `plan.inject`
161
+ * written flat at the top level reaches the same setting as `inject`
162
+ * nested under `plan`. Both spellings are accepted, and a file giving
163
+ * one setting in both is refused: they are different YAML keys, so the
164
+ * parser keeps both, and letting one win would be a silent choice.
165
+ *
166
+ * Every key here is looked up in the `Map` and the `Set` `section.ts`
167
+ * builds off the registered settings, never with `in` or an object
168
+ * index; the reason is argued there.
169
+ *
170
+ * ## The parser, measured on bun 1.3.14
171
+ *
172
+ * `Bun.YAML.parse` is the whole parser; the repo takes no YAML
173
+ * dependency. Six of its behaviours shape the rules above, each read
174
+ * off the parser rather than its documentation:
175
+ *
176
+ * - An empty file, a whitespace-only one, a comment-only one and a
177
+ * bare `---` all parse to `null`, and read as a file that says
178
+ * nothing.
179
+ * - A multi-document stream parses to a LIST of documents, which is
180
+ * refused with every other top level that is not a mapping.
181
+ * - A duplicated key is not an error: the last occurrence wins and
182
+ * the first leaves no trace, so nothing here can warn about it.
183
+ * - Malformed YAML throws a `SyntaxError` whose message carries no
184
+ * line or column. The refusal names the file; it cannot name the
185
+ * line.
186
+ * - A child indented with a TAB parses differently by version: on
187
+ * bun 1.3.14 `plan:` over a tab-indented `inject: full` parses as
188
+ * `plan: null` beside a top-level `inject`, and on bun 1.4.2 it
189
+ * throws `Tab characters cannot be used as indentation`. So a line
190
+ * whose indentation holds a tab is refused, by line number, before
191
+ * the parser sees the text, and every bun gives one answer. A blank
192
+ * or comment line may carry one, and a tab inside a value parses as
193
+ * the value's own on both. One cost: a block scalar line whose
194
+ * content opens with a tab after its spaces is refused too.
195
+ * - `yes` and `on` parse as strings, and `True` and `TRUE` as the
196
+ * boolean. So a `tracking` flag spelled `yes` is refused rather
197
+ * than read as true.
198
+ */
199
+ import type { SettingOrigin } from './config-origins.js';
200
+ import type { CommandLineSetting, ConfigSetting, RafaConfig } from './config-schema.js';
201
+ import type { ConfigExtra } from './config-sections.js';
202
+ export type { CommandLineSetting, ConfigSetting, RafaConfig, } from './config-schema.js';
203
+ export { CONFIG_FILE } from './core-section.js';
204
+ export type { BoardRelationshipMode, ClaimsAhead, ClaimsStaleAfter, ClaudeSettingSource, ConfigExtra, ConfigVersion, InjectMode, LessonSwitch, OutputMode, PrProvider, ReleaseEnabled, RouteTarget, SkillResolverName, StoreBackend, SyncStrategy, TierPin, TierSwitch, } from './config-sections.js';
205
+ export { BOARD_PROJECT_TEMPLATE_DEFAULT, BOARD_RELATIONSHIP_MODES, CLAUDE_SETTING_SOURCES, CONFIG_VERSIONS, INJECT_MODES, OUTPUT_MODES, PR_PROVIDERS, RELEASE_AUTO, STORE_BACKENDS, SYNC_STRATEGIES, } from './config-sections.js';
206
+ export type { ModuleSource, ModuleSourceKind, OptionalPrerequisiteItem, PrerequisiteItem, PrerequisiteKind, PrerequisiteScope, } from './config-items.js';
207
+ export { MODULE_SOURCE_KINDS, PREREQUISITE_KINDS } from './config-items.js';
208
+ /**
209
+ * The layer that answered a setting: the command line, the project's
210
+ * local file, the project's file, either of the user scope's two files,
211
+ * a template any file named, or the default. Which user file answered,
212
+ * and which file named the template, is the setting's `provenance`.
213
+ */
214
+ export type ConfigSource = 'cli' | 'local' | 'file' | 'user' | 'template' | 'default';
215
+ /**
216
+ * One layer's say on every setting: a value, or undefined for silence.
217
+ *
218
+ * Every key is REQUIRED, with undefined standing for silence, so a
219
+ * setting added to {@link RafaConfig} is a compile error wherever a
220
+ * layer is built rather than a setting some layer forgot.
221
+ */
222
+ export type ConfigLayer = {
223
+ readonly [K in ConfigSetting]: RafaConfig[K] | undefined;
224
+ };
225
+ /**
226
+ * Command-line values as a flag parser hands them over: the raw string,
227
+ * or undefined when the flag was not given. {@link resolveConfig}
228
+ * validates them and refuses what the file would refuse, an empty
229
+ * string included. A key naming no {@link CommandLineSetting} is not
230
+ * read.
231
+ */
232
+ export type ConfigOverrides = {
233
+ readonly [K in CommandLineSetting]?: string | undefined;
234
+ };
235
+ /** What one config file said. */
236
+ export interface ConfigFile {
237
+ /** The file, as the caller named it. */
238
+ path: string;
239
+ /** Its value for each setting, or undefined where it said nothing. */
240
+ values: ConfigLayer;
241
+ /** Every key that names no setting and opens no section. */
242
+ extras: readonly ConfigExtra[];
243
+ /**
244
+ * The zero-based entry that last set each setting, for a file of
245
+ * several entries. Absent for a file of one, a YAML file, whose every
246
+ * setting is entry 0.
247
+ */
248
+ entries?: ReadonlyMap<ConfigSetting, number>;
249
+ /**
250
+ * The template that answered each setting the file's own keys left
251
+ * silent, by name, as {@link layTemplatesUnder} laid it. Absent for a
252
+ * file naming no template.
253
+ */
254
+ templates?: ReadonlyMap<ConfigSetting, string>;
255
+ }
256
+ /** One template a file named, read: its name and its say on every setting. */
257
+ export interface TemplateLayer {
258
+ /** The name the file's `templates` key gave. */
259
+ readonly name: string;
260
+ /** Its value for each setting, or undefined where it said nothing. */
261
+ readonly values: ConfigLayer;
262
+ }
263
+ /** The layers {@link resolveConfig} ranks, highest first. */
264
+ export interface ConfigLayers {
265
+ /** Command-line values. Absent is the same as no flag given. */
266
+ cli?: ConfigOverrides;
267
+ /** The project's parsed local file, its `.rafa/config.yaml`, or null when there is none. */
268
+ local?: ConfigFile | null;
269
+ /** The project's parsed file, or null when there is none. */
270
+ file?: ConfigFile | null;
271
+ /** The user scope's parsed local file, or null when there is none. Its settings report `user`. */
272
+ userLocal?: ConfigFile | null;
273
+ /** The user scope's parsed file, or null when there is none. */
274
+ user?: ConfigFile | null;
275
+ }
276
+ /** Every setting resolved, with the layer each value came from. */
277
+ export interface ResolvedConfig {
278
+ /** The value each setting resolved to. */
279
+ config: RafaConfig;
280
+ /** The layer that answered each setting. */
281
+ sources: Readonly<Record<ConfigSetting, ConfigSource>>;
282
+ /** The project's file consulted, or null when there was none. */
283
+ path: string | null;
284
+ /** The project's local file consulted, or null when there was none. */
285
+ localPath: string | null;
286
+ /** The user scope's file consulted, or null when there was none. */
287
+ userPath: string | null;
288
+ /** The user scope's local file consulted, its `~/.rafa/config.yaml`, or null when there was none. */
289
+ userLocalPath: string | null;
290
+ /** The project file's unknown keys, retained. Empty with no file. */
291
+ extras: readonly ConfigExtra[];
292
+ /** The project's local file's unknown keys, retained. Empty with no file. */
293
+ localExtras: readonly ConfigExtra[];
294
+ /** The user file's unknown keys, retained. Empty with no file. */
295
+ userExtras: readonly ConfigExtra[];
296
+ /** The user scope's local file's unknown keys, retained. Empty with no file. */
297
+ userLocalExtras: readonly ConfigExtra[];
298
+ /**
299
+ * One sentence per retained unknown key, in layer order from the
300
+ * bottom: the user file's, the user's local file's, the project
301
+ * file's, then the project's local file's.
302
+ */
303
+ warnings: readonly string[];
304
+ /**
305
+ * The file and entry that answered each setting, or null where the
306
+ * command line or a default did (`config-origins.ts`).
307
+ */
308
+ provenance: Readonly<Record<ConfigSetting, SettingOrigin | null>>;
309
+ }
310
+ /**
311
+ * A config the loop cannot run on: unreadable, not YAML, not a
312
+ * mapping, or naming a value a setting does not accept.
313
+ *
314
+ * Its own class so a caller can tell a refusal it should print and
315
+ * exit on from a fault it should not swallow.
316
+ */
317
+ export declare class ConfigError extends Error {
318
+ /** Every problem found, one sentence each. */
319
+ readonly problems: readonly string[];
320
+ constructor(problems: readonly string[], options?: ErrorOptions);
321
+ }
322
+ /**
323
+ * Parses YAML into its document, refusing text that is not YAML with
324
+ * the file named. A tab in a line's indentation is refused before the
325
+ * parser sees the text, because bun's parser answers it differently by
326
+ * version. Judges no key: {@link readConfigDocument} does.
327
+ */
328
+ export declare function parseConfigDocument(text: string, path: string): unknown;
329
+ /** The config file's path under `root`. */
330
+ export declare function configFilePath(root: string): string;
331
+ /**
332
+ * Reads config text into one file layer. Pure: `path` only labels the
333
+ * layer and the refusals.
334
+ *
335
+ * Throws a {@link ConfigError} naming every problem the text has — a
336
+ * line indented with a tab, not YAML, not a mapping at the top, a section that is not a mapping, a
337
+ * setting given twice, a value a setting does not accept. An unknown
338
+ * key is none of these: it is retained in {@link ConfigFile.extras},
339
+ * the keys an item carried after the keys of the document.
340
+ */
341
+ export declare function parseConfigText(text: string, path: string): ConfigFile;
342
+ /**
343
+ * Reads a parsed document into one file layer, as {@link parseConfigText}
344
+ * reads the text it parses: null says nothing, anything but a mapping at
345
+ * the top is refused, and every key is judged. Pure; `path` only labels.
346
+ */
347
+ export declare function readConfigDocument(parsed: unknown, path: string): ConfigFile;
348
+ /**
349
+ * `file` with each of `templates` laid under its own keys, in the order
350
+ * named, a later template over an earlier one: a setting the file left
351
+ * silent takes the last template's value that answers it, and a map
352
+ * setting merges by key, the templates under the file. Each setting a
353
+ * template answered and the file did not is recorded in
354
+ * {@link ConfigFile.templates} under that template's name. Pure; answers
355
+ * `file` itself when no template is given.
356
+ *
357
+ * @param file - The file as its own keys read.
358
+ * @param templates - The templates its `templates` key named, read.
359
+ * @returns The file with the templates' values beneath its own.
360
+ */
361
+ export declare function layTemplatesUnder(file: ConfigFile, templates: readonly TemplateLayer[]): ConfigFile;
362
+ /**
363
+ * Ranks the layers: for each registered setting, the command line over
364
+ * the project's local file, that over the project's file, that over the
365
+ * user scope's local file, that over the user scope's file, and that
366
+ * over its registered default (`activeDefaults()` in `section.ts`). A
367
+ * map setting merges by key in the reverse order, each file over the
368
+ * ones beneath it. A file's templates are already laid under it
369
+ * ({@link layTemplatesUnder}), so a setting one answered ranks with its
370
+ * file and reports `template`. Each setting's origin is read off the
371
+ * file that answered it ({@link originOf}), the highest one naming a map
372
+ * setting, so the two user files, both reporting `user`, name their own.
373
+ *
374
+ * Pure. Warnings come back as data — one per unknown key any file
375
+ * retained, from the bottom layer up — and are never printed here. A command-line value no
376
+ * setting accepts throws a {@link ConfigError} naming every one, and
377
+ * is never downgraded to the file's value: an operator who mistyped a
378
+ * flag asked for something, and running on something else is the
379
+ * silent success the module note refuses. Every registered section's
380
+ * checks then run over the resolution, and any problem one reports
381
+ * throws a {@link ConfigError} too naming every such problem: the
382
+ * `hub` section's refuses `effort.sync: service` with no `hub.url` in
383
+ * any layer, naming the file that chose `service`.
384
+ */
385
+ export declare function resolveConfig(layers?: ConfigLayers): ResolvedConfig;
@@ -0,0 +1,39 @@
1
+ import type { RafaConfig, SettingSpec } from './config-schema.js';
2
+ import type { ConfigSection } from './section.js';
3
+ /**
4
+ * The config file, relative to the directory it sits under: the project
5
+ * root for the project's, the home directory for the user scope's.
6
+ *
7
+ * `join` rather than a literal, as `effort/store/ndjson-files.ts` spells
8
+ * its own directory, so a path built here compares equal to one a
9
+ * caller built with `join` of its own.
10
+ */
11
+ export declare const CONFIG_FILE: string;
12
+ /**
13
+ * The directory a scope keeps its files in, relative to the project
14
+ * root or the home: `.rafa`. Taken from `CONFIG_FILE`, so the two
15
+ * cannot name different directories.
16
+ */
17
+ export declare const SCOPE_DIR: string;
18
+ /**
19
+ * The name of one of core's own settings: every field `config-schema.ts`
20
+ * declares on `RafaConfig`, in the order problems are reported. Spelled
21
+ * rather than read off a value, since `isolatedDeclarations` asks every
22
+ * exported type to be written out.
23
+ */
24
+ export type CoreSetting = 'version' | 'store' | 'effortBusyTimeoutMs' | 'effortSync' | 'inject' | 'planDir' | 'specsDir' | 'trackerDefault' | 'trackerFallback' | 'learningAdapter' | 'learningBlessMinConfidence' | 'learningPromoteAfter' | 'learningPromoteMinConfidence' | 'outputMode' | 'prerequisitesRequired' | 'prerequisitesOptional' | 'trackingSpecs' | 'trackingPlans' | 'trackingAll' | 'modules' | 'allowList' | 'settingSources' | 'loopWorktreeDir' | 'boardTrustedAuthors' | 'boardRelationships' | 'boardProjectTemplate' | 'boardProjectNumber' | 'roadmapIssue' | 'claimsStaleAfter' | 'claimsAhead' | 'cleanupStaleDays' | 'cleanupWorktreeIdleDays' | 'cleanupKeep' | 'dangerousAcceptStaleRefs' | 'dangerousSelfUpdateDuringLoop' | 'statusNotice' | 'tiersRafa' | 'tiersSkills' | 'tiersAgents' | 'routing' | 'taskSkills' | 'taskLessons' | 'mergeDuplicates' | 'namingBranch' | 'templates';
25
+ /** Core's section: its package, the spec and the default of each of its settings, and no check. */
26
+ export interface CoreSection extends ConfigSection {
27
+ /** Each of core's settings, by name, in the order problems are reported. */
28
+ readonly settings: {
29
+ readonly [K in CoreSetting]: SettingSpec<K>;
30
+ };
31
+ /** What each of core's settings resolves to when no layer names it. */
32
+ readonly defaults: Readonly<Pick<RafaConfig, CoreSetting>>;
33
+ }
34
+ /**
35
+ * Core's own settings, handed in as a section: package `core`, every
36
+ * setting `config-schema.ts` declares with its spec and its default, and
37
+ * no cross-key check. Frozen, with its settings record.
38
+ */
39
+ export declare const CORE_SECTION: CoreSection;
@@ -0,0 +1,58 @@
1
+ import type { ResolvedConfig } from './config.js';
2
+ /** What a command does under each `dangerous.*` key it declares, by key. */
3
+ export type DangerousPhrases = Readonly<Record<string, string>>;
4
+ /**
5
+ * Runs `run` with `phrases` as the running command's in an async scope
6
+ * of its own, and answers what `run` answers; see the module note.
7
+ *
8
+ * @param phrases - The command's `dangerous` field, absent for none.
9
+ * @param run - The command's run.
10
+ * @returns What `run` answers.
11
+ */
12
+ export declare function runWithDangerousPhrases<T>(phrases: DangerousPhrases | undefined, run: () => T): T;
13
+ /**
14
+ * Sets `phrases` at module level; see the module note.
15
+ *
16
+ * @param phrases - The phrases to set, absent for none.
17
+ * @returns The module-level phrases replaced, for {@link restoreDangerousPhrases}.
18
+ */
19
+ export declare function setDangerousPhrases(phrases: DangerousPhrases | undefined): DangerousPhrases;
20
+ /**
21
+ * Puts back phrases {@link setDangerousPhrases} answered.
22
+ *
23
+ * @param previous - The phrases it answered.
24
+ */
25
+ export declare function restoreDangerousPhrases(previous: DangerousPhrases): void;
26
+ /**
27
+ * The running command's phrases: the scope's, else the module-level ones.
28
+ *
29
+ * @returns The phrases by key, empty when none is declared.
30
+ */
31
+ export declare function dangerousPhrases(): DangerousPhrases;
32
+ /**
33
+ * Every key of the active registry that opens with `dangerous.`, in
34
+ * registration order; see the module note.
35
+ *
36
+ * @returns The keys, such as `dangerous.acceptStaleRefs`; empty while
37
+ * no section is registered.
38
+ */
39
+ export declare function dangerousKeys(): readonly string[];
40
+ /**
41
+ * One pass line per dangerous key `resolved` holds off its default; see
42
+ * the module note.
43
+ *
44
+ * @param resolved - A resolution `loadConfig` or `resolveConfig` answered.
45
+ * @returns The lines, such as
46
+ * `dangerous.acceptStaleRefs: true (/repo/rafa.config.ts, entry 1)`,
47
+ * each ending with `; <phrase>` for a key the running command declares.
48
+ */
49
+ export declare function dangerousPassLines(resolved: ResolvedConfig): readonly string[];
50
+ /**
51
+ * Writes through `warn` each of `resolved`'s pass lines not yet written
52
+ * for `invocation`; see the module note.
53
+ *
54
+ * @param resolved - The resolution just loaded.
55
+ * @param warn - The warning sink `loadConfig` writes through.
56
+ * @param invocation - The object one invocation is known by.
57
+ */
58
+ export declare function writeDangerousPassLines(resolved: ResolvedConfig, warn: (message: string) => void, invocation: object): void;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * rafa's routing defaults: which agent a task of each shape goes to
3
+ * when no config layer says otherwise.
4
+ *
5
+ * The table moved here from `src/tiers/routing.ts`, which re-exports
6
+ * each name, so `core-section.ts` reads {@link DEFAULT_ROUTING} without
7
+ * importing above core. What the rows mean, and why the map is one
8
+ * shared `Map` while the list is frozen, is `routing.ts`'s module note.
9
+ */
10
+ import type { RouteTarget } from './config-sections.js';
11
+ /** One default row: a task shape and the agent that takes it. */
12
+ export type Route = readonly [shape: string, agent: string];
13
+ /** rafa's routing table, in the order the spec lists it. */
14
+ export declare const DEFAULT_ROUTES: readonly Route[];
15
+ /** {@link DEFAULT_ROUTES} as the map `routing` resolves to by default. */
16
+ export declare const DEFAULT_ROUTING: ReadonlyMap<string, RouteTarget>;
@@ -0,0 +1,145 @@
1
+ /**
2
+ * The barrel over the config's schema and its layers: every name
3
+ * `config-items.ts`, `config-schema.ts`, `core-section.ts`, `section.ts`,
4
+ * `config.ts`, `dangerous.ts`, `scope.ts` and `default-routing.ts` export, less the names the
5
+ * `sections.ts` barrel holds, and nothing else.
6
+ *
7
+ * A file outside `packages/rafa/src/core/` imports this file and never the eight
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 eight directly and never this
11
+ * file.
12
+ *
13
+ * ## The barrels hold no name in common
14
+ *
15
+ * `packages/rafa/src/core/config/` has three barrels, all listed under `CORE_BARRELS`
16
+ * in `scripts/survey/core-moves.ts`. `sections.ts` holds the leaf pair,
17
+ * `config-sections.ts` and `config-readers.ts`, with `branch-template.ts`
18
+ * beside it, and argues why the pair has a barrel of its own. `load.ts` holds `config-load.ts` alone, and
19
+ * argues the same for it. This one holds the four files that read a
20
+ * key or rank a layer, and `section.ts`, the contract a section file
21
+ * outside `packages/rafa/src/core/` is typed by, the registry it is handed to and the
22
+ * key indexes read off that registry. `dangerous.ts` joined it with the
23
+ * running command's phrases (`runWithDangerousPhrases`), which the
24
+ * dispatcher sets around every command. It fits neither other barrel:
25
+ * it imports `config-sections.ts`, so it is no leaf for `sections.ts`,
26
+ * and `src/index.ts` publishes `load.ts` whole, where the phrases and
27
+ * pass lines are no published name.
28
+ *
29
+ * `scope.ts` joined it with a scope's paths, `Scope`, the project the
30
+ * dispatcher resolved, `ProjectFound`, and `scopeAt`, whose walk,
31
+ * `resolveScope`, stays in `packages/rafa/src/project/scope.ts`. It reads `config.ts`
32
+ * and `core-section.ts` by value and `config-load.ts` as a type, so it
33
+ * is no leaf for `sections.ts`, and `load.ts` holds `config-load.ts`
34
+ * alone.
35
+ *
36
+ * `config.ts` re-exports twenty-seven names of `config-sections.ts`
37
+ * (`InjectMode`, `OUTPUT_MODES`, `ConfigExtra` and the like), as it did
38
+ * before it moved. None of them is exported here: a caller outside
39
+ * `packages/rafa/src/core/` takes each from `sections.ts`, so a name has one barrel to
40
+ * be learned from. A file that used to take `ConfigError` and
41
+ * `OUTPUT_MODES` in one line from `config.js` now spells two lines.
42
+ *
43
+ * ## Why one barrel can hold all eight
44
+ *
45
+ * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
46
+ * imports the barrel back by value is a runtime cycle. None of the
47
+ * eight files behind this one imports outward by value:
48
+ * `core-section.ts` reads the routing defaults from `default-routing.ts`
49
+ * beside it, and `src/tiers/routing.ts` imports them from this barrel by
50
+ * value with nothing here importing it back. No file behind it
51
+ * imports a section file (`src/config-schema-*.ts`), by value or as a
52
+ * type: `config-merged.ts`, which spread the eleven into one schema,
53
+ * was retired when its importers moved to `src/config-registry.ts`,
54
+ * `config.ts` reads every key index and runs every section's checks
55
+ * off `section.ts`, and `src/tests/core-config-sections.sweep.test.ts`
56
+ * holds the rule for every file under `packages/rafa/src/core/`. The registry imports
57
+ * this barrel by value and nothing here imports the registry. A section
58
+ * file reads its values from `sections.ts`, which imports none of the
59
+ * eight, and adds its fields to `RafaConfig` with a `declare module` on
60
+ * `config-schema.ts`, which the checker follows and which loads
61
+ * nothing. `config-schema.ts` and `section.ts` import types alone.
62
+ *
63
+ * Measured when the three moved: the value imports of the non-test files
64
+ * under `src/`, `scripts/` and `packages/` held six cycles before the
65
+ * move and the same six after it, none through a file of this folder,
66
+ * and each barrel, each of the three files and each section file loaded
67
+ * first in a fresh `bun` process, `SETTINGS` holding its 89 entries
68
+ * each time.
69
+ *
70
+ * Measured again when core's keys moved into `core-section.ts`, on bun
71
+ * 1.3.14: each barrel, each of the five files, `section.ts`,
72
+ * `src/tiers/routing.ts` and each section file loaded first in a fresh
73
+ * `bun` process, `SETTINGS` and `CONFIG_DEFAULTS` holding 89 entries and
74
+ * `CORE_SECTION` 42 each time. The control, `config-schema-hub.ts`
75
+ * reading `SETTINGS` off this barrel at load, threw `Cannot access
76
+ * 'HUB_DEFAULTS' before initialization` when loaded first.
77
+ *
78
+ * Measured again when `section.ts` joined and each section file took a
79
+ * `ConfigSection` of its own, on bun 1.3.14: each config barrel,
80
+ * `section.ts`, the since-retired `config-merged.ts`, `config.ts` and
81
+ * each section file loaded first in a fresh `bun` process with
82
+ * `SETTINGS` holding 89 entries, and core's section and the eleven
83
+ * merged by `mergeConfigSections` into the same 89 settings and the
84
+ * same defaults as `SETTINGS` and `CONFIG_DEFAULTS`, with one check.
85
+ *
86
+ * Measured again when `config-merged.ts` was retired, on bun 1.3.14:
87
+ * the value imports of the five files behind this one reach no section
88
+ * file and not the registry, and each config barrel, each of the five
89
+ * files, `config-load.ts`, the registry, `packages/rafa/src/effort/store/settings.ts`,
90
+ * `src/tiers/routing.ts`, `packages/rafa/src/core/adapters/registry.ts` and each
91
+ * section file loaded first in a fresh `bun` process, the registry then
92
+ * answering 89 registered settings and 89 defaults each time.
93
+ *
94
+ * Measured again when `dangerous.ts` joined, on bun 1.3.14: this
95
+ * barrel, `dangerous.ts`, `config-load.ts`, the registry,
96
+ * `src/cli/dispatch.ts` and `packages/rafa/src/core/command/command.ts` each loaded
97
+ * first in a fresh `bun` process, the registry then holding 91 settings
98
+ * and `dangerousKeys` three keys each time.
99
+ *
100
+ * ## What it exports
101
+ *
102
+ * Each name is spelled, types apart from values, as `sections.ts` spells
103
+ * its own, and taken from the file that declares it: `config.ts`
104
+ * re-exports `RafaConfig` from `config-schema.ts`, `CONFIG_FILE` from
105
+ * `core-section.ts` and the item types and kind lists from
106
+ * `config-items.ts`, and each is exported here once. The merged schema
107
+ * (`SETTINGS`, `CONFIG_DEFAULTS`, `SETTING_NAMES`, `SETTING_BY_KEY`,
108
+ * `SECTIONS` and `knownKeysAbove`) is not here: a file outside
109
+ * `packages/rafa/src/core/` imports it from `src/config-registry.ts`, and core reads
110
+ * the registered settings, defaults and key indexes off `section.ts`.
111
+ * A feature file that reads the whole `CONFIG_DEFAULTS` or `SETTINGS`
112
+ * record without importing the registry takes `registeredDefaults()`
113
+ * or `registeredSettings()` from here, which answer the registered
114
+ * records typed whole.
115
+ * Neither are the hub's `HubContext` and `HubTimeout`, which a file
116
+ * imports from `src/config-schema-hub.ts`.
117
+ *
118
+ * The published surface is narrower than this file. `src/index.ts`
119
+ * re-exports part of it, and of the runtime names leaves out core's
120
+ * section, the routing defaults, the item readers, `config.ts`'s two
121
+ * document readers the loader reads a scope through, and the section
122
+ * registry with its key indexes (`CORE_SECTION`, `moduleSource`, `registerConfigSections`,
123
+ * `activeSettingByKey` and thirty-three more), which `src/index.test.ts`
124
+ * spells under `CONFIG_BARREL_ONLY`. Its `CONFIG_DEFAULTS` is
125
+ * `src/config-registry.ts`'s.
126
+ *
127
+ * `index.test.ts` holds the list to the eight files: every name any of
128
+ * them exports and `sections.ts` does not is here once, as the same
129
+ * binding, and no other name is here.
130
+ */
131
+ export type { ModuleSource, ModuleSourceKind, OptionalPrerequisiteItem, PrerequisiteItem, PrerequisiteKind, PrerequisiteScope, } from './config-items.js';
132
+ export type { CommandLineSetting, ConfigSetting, RafaConfig, SettingSpec, } from './config-schema.js';
133
+ export type { CoreSection, CoreSetting } from './core-section.js';
134
+ export type { ConfigCheck, ConfigCheckInput, ConfigLoadHook, ConfigSection, ConfigSectionRegistry, ConfigTemplateHook, SettingsRecord, } from './section.js';
135
+ export type { ConfigFile, ConfigLayer, ConfigLayers, ConfigOverrides, ConfigSource, ResolvedConfig, TemplateLayer, } from './config.js';
136
+ export type { DangerousPhrases } from './dangerous.js';
137
+ export type { ProjectFound, Scope } from './scope.js';
138
+ export type { Route } from './default-routing.js';
139
+ export { MODULE_SOURCE_KEYS, MODULE_SOURCE_KINDS, moduleSource, OPTIONAL_ITEM_KEYS, optionalPrerequisite, PREREQUISITE_KINDS, REQUIRED_ITEM_KEYS, requiredPrerequisite, } from './config-items.js';
140
+ export { CONFIG_FILE, CORE_SECTION, SCOPE_DIR } from './core-section.js';
141
+ export { activeChecks, activeConfigLoadHook, activeConfigTemplateHook, activeDefaults, activeKnownKeysAbove, activeSectionPaths, activeSections, activeSettingByKey, activeSettings, ConfigSectionError, EMPTY_CONFIG_REGISTRY, mergeConfigSections, registerConfigSections, registeredDefaults, registeredSettings, restoreConfigSections, setConfigLoadHook, setConfigTemplateHook, } from './section.js';
142
+ export { ConfigError, configFilePath, layTemplatesUnder, parseConfigDocument, parseConfigText, readConfigDocument, resolveConfig, } from './config.js';
143
+ export { dangerousKeys, dangerousPassLines, dangerousPhrases, restoreDangerousPhrases, runWithDangerousPhrases, setDangerousPhrases, writeDangerousPassLines, } from './dangerous.js';
144
+ export { scopeAt } from './scope.js';
145
+ export { DEFAULT_ROUTES, DEFAULT_ROUTING } from './default-routing.js';