@open-tomato/rafa 0.46.0 → 0.48.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 (94) hide show
  1. package/README.md +70 -37
  2. package/dist/adapters/logger/settings.d.ts +2 -2
  3. package/dist/bugs/places.d.ts +1 -1
  4. package/dist/bugs/record.d.ts +1 -1
  5. package/dist/bundled/skills/dev-planner/SKILL.md +2 -2
  6. package/dist/cli.js +73457 -72996
  7. package/dist/config/index.d.ts +5 -0
  8. package/dist/config/index.js +6 -4
  9. package/dist/config/shape.d.ts +20 -15
  10. package/dist/config/templates.d.ts +64 -0
  11. package/dist/config-registry.d.ts +21 -12
  12. package/dist/config-schema-board-project.d.ts +3 -3
  13. package/dist/config-schema-bugs.d.ts +3 -3
  14. package/dist/config-schema-checks.d.ts +114 -0
  15. package/dist/config-schema-errors.d.ts +3 -3
  16. package/dist/config-schema-features.d.ts +4 -4
  17. package/dist/config-schema-hub.d.ts +6 -4
  18. package/dist/config-schema-issues.d.ts +2 -2
  19. package/dist/config-schema-logger.d.ts +3 -3
  20. package/dist/config-schema-loop-continue.d.ts +3 -3
  21. package/dist/config-schema-loop-retries.d.ts +4 -4
  22. package/dist/config-schema-release.d.ts +23 -24
  23. package/dist/config-schema-tests.d.ts +35 -27
  24. package/dist/config-schema-triage.d.ts +3 -3
  25. package/dist/config-schema-wrap-up.d.ts +4 -4
  26. package/dist/core/command/command.d.ts +1 -1
  27. package/dist/core/command/confirm.d.ts +11 -5
  28. package/dist/core/command/global-flags.d.ts +25 -0
  29. package/dist/core/command/index.d.ts +47 -23
  30. package/dist/core/command/registry-types.d.ts +4 -4
  31. package/dist/core/command/shared-flags.d.ts +40 -0
  32. package/dist/core/command/types.d.ts +3 -2
  33. package/dist/core/config/branch-template.d.ts +2 -0
  34. package/dist/core/config/config-items.d.ts +1 -1
  35. package/dist/core/config/config-load-module.d.ts +43 -0
  36. package/dist/core/config/config-load.d.ts +43 -12
  37. package/dist/core/config/config-origins.d.ts +31 -30
  38. package/dist/core/config/config-schema.d.ts +11 -0
  39. package/dist/core/config/config-sections.d.ts +15 -14
  40. package/dist/core/config/config.d.ts +90 -25
  41. package/dist/core/config/core-section.d.ts +1 -1
  42. package/dist/core/config/default-routing.d.ts +1 -1
  43. package/dist/core/config/index.d.ts +14 -10
  44. package/dist/core/config/merge-method.d.ts +40 -0
  45. package/dist/core/config/scope.d.ts +2 -2
  46. package/dist/core/config/section.d.ts +81 -1
  47. package/dist/core/config/sections.d.ts +17 -6
  48. package/dist/core/git/gh-runner.d.ts +1 -1
  49. package/dist/core/git/git.d.ts +34 -0
  50. package/dist/core/git/index.d.ts +13 -8
  51. package/dist/core/loop/claude.d.ts +11 -5
  52. package/dist/core/loop/hop-record.d.ts +6 -6
  53. package/dist/core/loop/index.d.ts +9 -8
  54. package/dist/core/loop/session-record-parse.d.ts +9 -2
  55. package/dist/core/loop/sessions.d.ts +23 -11
  56. package/dist/core/loop/suite-failure.d.ts +8 -6
  57. package/dist/core/output/active.d.ts +1 -1
  58. package/dist/core/plan/block-reader.d.ts +1 -1
  59. package/dist/core/runtime/identity.d.ts +13 -0
  60. package/dist/core/runtime/index.d.ts +12 -6
  61. package/dist/effort/store/check-rows.d.ts +1 -1
  62. package/dist/effort/store/commit-stats.d.ts +1 -1
  63. package/dist/effort/store/index.js +7 -8
  64. package/dist/effort/store/merge-commit-gaps.d.ts +1 -1
  65. package/dist/effort/store/plan-stubs.d.ts +1 -1
  66. package/dist/effort/store/session-row-types.d.ts +2 -2
  67. package/dist/errors/rafa-codes.d.ts +1 -1
  68. package/dist/index-2xzkzwm6.js +670 -0
  69. package/dist/index-ajv88fkm.js +448 -0
  70. package/dist/{index-ykggr043.js → index-fpgmdmww.js} +13 -5
  71. package/dist/index-g91ys6kw.js +249 -0
  72. package/dist/{index-cy98y87p.js → index-jx3x70xh.js} +1111 -638
  73. package/dist/{index-gvek4r8m.js → index-m672ptpg.js} +84 -26
  74. package/dist/{index-39kbcw68.js → index-w5qbpdtp.js} +415 -842
  75. package/dist/{index-gqz4jn6j.js → index-z4r20zwr.js} +8974 -11438
  76. package/dist/{index-j4k2vdz3.js → index-zsak0jy6.js} +124 -290
  77. package/dist/index.js +24940 -18766
  78. package/dist/learning/index.js +221 -12
  79. package/dist/plan/index.js +10 -9
  80. package/dist/ports/index.d.ts +7 -7
  81. package/dist/ports/learning.d.ts +5 -4
  82. package/dist/ports/spec-review.d.ts +1 -1
  83. package/dist/ready-gax3hhtt.js +241 -0
  84. package/dist/release-templates/release-bot-fragment.yml +6 -6
  85. package/dist/release-templates/release-publish.yml +8 -8
  86. package/dist/release-templates/release-settle.yml +8 -7
  87. package/dist/release-templates/release-tag.yml +8 -7
  88. package/package.json +53 -2
  89. package/dist/index-77ajfffn.js +0 -223
  90. package/dist/index-jh1r4kcn.js +0 -1067
  91. package/dist/index-z1w83f81.js +0 -4
  92. package/dist/pr/checks.d.ts +0 -133
  93. package/dist/pr/types.d.ts +0 -422
  94. package/dist/ready-4f8edezt.js +0 -2016
@@ -29,31 +29,35 @@
29
29
  *
30
30
  * - `tests.fullSuiteTriggers` names the files a task's diff runs the
31
31
  * full suite for, however the task line scoped its tests. Its
32
- * default is the five files whose change can move a test no import
33
- * graph reaches: `bunfig.toml`, `tsconfig*.json`, `package.json`,
34
- * `bun.lock` and `bun.lockb`. The plan adds the preload files
35
- * `bunfig.toml`'s `[test] preload` names, and those are NOT in this
36
- * default: a default is a value this module can spell, and which
37
- * files a project preloads is a question about its disk, answered
38
- * at run time by the reader of the scope. A project that sets this
39
- * key replaces the five, and the preload files are added to its own
40
- * list all the same.
32
+ * default is empty. The `escalation` template
33
+ * (`src/config/templates.ts`) names the five files whose change can
34
+ * move a test no import graph reaches: `bunfig.toml`,
35
+ * `tsconfig*.json`, `package.json`, `bun.lock` and `bun.lockb`. The
36
+ * runner adds the preload files `bunfig.toml`'s `[test] preload`
37
+ * names to whatever list resolves, empty included, and those are in
38
+ * no list here: which files a project preloads is a question about
39
+ * its disk, answered at run time by the reader of the scope.
41
40
  * - `tests.integration` names the test files a stage step runs beside
42
41
  * the tests under the folders the stage touched, because they drive
43
- * the whole CLI rather than one folder's modules. Its default is the
44
- * four spellings this repository gives such a file, in any folder:
45
- * a name ending `-integration.test.ts` or `.integration.test.ts`,
46
- * one holding `-spawned` and ending `.test.ts`, and one ending
47
- * `-cli.test.ts`. Each default pattern opens with the any-folder
48
- * prefix, two stars and a slash, which this note cannot spell
49
- * because it would close the comment.
42
+ * the whole CLI rather than one folder's modules. Its default is
43
+ * empty. The `escalation` template names the four spellings this
44
+ * repository gives such a file, in any folder: a name ending
45
+ * `-integration.test.ts` or `.integration.test.ts`, one holding
46
+ * `-spawned` and ending `.test.ts`, and one ending `-cli.test.ts`.
47
+ * Each of its patterns opens with the any-folder prefix, two stars
48
+ * and a slash, which this note cannot spell because it would close
49
+ * the comment. A task step reads it too when `checks.task` names
50
+ * `integration` or `unit`.
50
51
  * - `tests.contract` names the contract tests. A contract test checks
51
52
  * the promise a package makes to others, with a fixture, and runs in
52
53
  * that package's own `test` task in ring 1 of CI, where a use-case
53
54
  * test matching `tests.integration` runs in ring 0's full run. Its
54
- * default is one pattern: a name ending `.contract.test.ts`, in any
55
- * folder, under the same any-folder prefix. No step reads the key
56
- * yet; its readers come with the CI rings that run each kind.
55
+ * default is empty. The `escalation` template names one pattern: a
56
+ * name ending `.contract.test.ts`, in any folder, under the same
57
+ * any-folder prefix. The runner's task step reads it when
58
+ * `checks.task` names `contract` or `unit`
59
+ * (`start/suite-task-step.ts`); its CI readers come with the rings
60
+ * that run each kind.
57
61
  * - `tests.alwaysRun` names the test files a task's scoped run takes
58
62
  * beside the ones `bun test --changed=<base>` selects. A content
59
63
  * sweep, a test that imports no project file and reads the tree at
@@ -64,14 +68,18 @@
64
68
  * since the sweeps it names may not have been written yet. The task
65
69
  * prompt reads it (`start/task-gate-lines.ts`), naming the files it
66
70
  * resolves to, and so does the runner's task step
67
- * (`start/task-always-run.ts`), running those files beside a
68
- * `module` or `affected` scope.
71
+ * (`start/task-always-run.ts`), running those files beside an
72
+ * `affected` run and in a path list where `related` is in play
73
+ * (`start/suite-step.ts`'s module note).
69
74
  *
70
75
  * An empty list is a value every glob key accepts, and means what it says:
71
76
  * no file triggers the full suite beyond the preload files, a stage
72
- * runs no integration tier, no file is a contract test, or a task runs no sweep beside its scoped
73
- * tests. It is not read as "the default", since a list written `[]`
74
- * has been said.
77
+ * runs no integration file, no file is a contract test, or a task runs
78
+ * no sweep beside its scoped tests. The first three default to it, so a
79
+ * project that names no template runs no trigger, no integration file
80
+ * and no contract file; one that writes `templates: [escalation]` takes
81
+ * the template's lists under its own keys. A list written `[]` has been
82
+ * said, and outranks the template's.
75
83
  *
76
84
  * ## The reader
77
85
  *
@@ -110,9 +118,9 @@
110
118
  * (`config-schema-readings.ts`): a global flag nobody typed would be one
111
119
  * this module invented.
112
120
  */
113
- import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
114
- import type { Reader } from '@open-tomato/rafa/core/config/sections';
115
- declare module '@open-tomato/rafa/core/config/config-schema' {
121
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
122
+ import type { Reader } from './core/config/sections.js';
123
+ declare module './core/config/config-schema.js' {
116
124
  /** The `tests` section's fields, added to core's. */
117
125
  interface RafaConfig extends TestsSettings {
118
126
  }
@@ -56,9 +56,9 @@
56
56
  * command line has no spelling for `false` or a number this module
57
57
  * would not have to invent.
58
58
  */
59
- import type { ConfigSection, SettingSpec } from '@open-tomato/rafa/core/config';
60
- import type { Reader } from '@open-tomato/rafa/core/config/sections';
61
- declare module '@open-tomato/rafa/core/config/config-schema' {
59
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
60
+ import type { Reader } from './core/config/sections.js';
61
+ declare module './core/config/config-schema.js' {
62
62
  /** The `triage` section's fields, added to core's. */
63
63
  interface RafaConfig extends TriageSettings {
64
64
  }
@@ -9,7 +9,7 @@
9
9
  * which `src/config/shape.ts` composes into `LoopShape` of `ConfigShape`,
10
10
  * the nested file shape.
11
11
  * `config-registry.ts`'s `CONFIG_DEFAULTS` and `SETTINGS`
12
- * spread the objects below right after `loop.worktreeDir`, so the order
12
+ * spread the objects below right after `loop.worktreeSetup`, so the order
13
13
  * settings are reported in holds the `loop` section together.
14
14
  *
15
15
  * The section has its own module, as `config-schema-release.ts` and
@@ -48,9 +48,9 @@
48
48
  * command line has no spelling for `false` or a number this module
49
49
  * would not have to invent.
50
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' {
51
+ import type { ConfigSection, SettingSpec } from './core/config/index.js';
52
+ import type { Reader } from './core/config/sections.js';
53
+ declare module './core/config/config-schema.js' {
54
54
  /** The `wrap-up` section's fields, added to core's. */
55
55
  interface RafaConfig extends WrapUpSettings {
56
56
  }
@@ -30,7 +30,7 @@
30
30
  * second one.
31
31
  *
32
32
  * And it carries `project`, the project the command runs in as
33
- * `resolveScope` answers it (`src/project/scope.ts`): its root, the home,
33
+ * `resolveScope` answers it (`packages/rafa/src/project/scope.ts`): its root, the home,
34
34
  * and both scopes' paths. A command runs inside a project unless it
35
35
  * declares `needsProject: false`. The dispatcher resolves the project
36
36
  * before any other command runs, and runs none outside a project, so
@@ -26,11 +26,15 @@
26
26
  * {@link lazyPrompter} wraps the opening of a prompter so a run that
27
27
  * never asks opens nothing: the prompter is opened at the first
28
28
  * question, kept for the next, and closed by `close`, after which the
29
- * next question opens a fresh one. Its `ask` answers whether the line
30
- * typed means yes: `y` or `yes`, trimmed and in any case, the reading
31
- * every `[y/N]` question in rafa makes. Anything else declines, the empty
32
- * answer and the null of an input that ended included. `issue ready`,
33
- * `next`, `cleanup` and `plan create`'s three offers ask through it.
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`.
34
38
  */
35
39
  import type { Readable } from 'node:stream';
36
40
  /** Asks an operator, and tells them what went wrong. */
@@ -44,6 +48,8 @@ export interface Prompter {
44
48
  }
45
49
  /** A prompter opened at its first question, see the module note. */
46
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>;
47
53
  /** Opens the prompter if it is not open, asks `question` and answers whether the line typed means yes. */
48
54
  readonly ask: (question: string) => Promise<boolean>;
49
55
  /** Closes the prompter if one is open; the next question opens another. */
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The flags every command reads, as the root help lists them.
3
+ *
4
+ * {@link GLOBAL_FLAGS} are core's rather than the CLI's because two
5
+ * readers outside one package take them: `src/cli/help.ts`, which lists
6
+ * them in the root help, and `packages/rafa-board/src/refs/verify.ts`, a board file, which
7
+ * reads their names as flags no command declares and still `present`.
8
+ * Board imports core and no CLI file, so the flags sit here, beside the
9
+ * command contract both readers already import.
10
+ *
11
+ * The file imports nothing.
12
+ */
13
+ /** A flag every command reads, as the root help lists it. */
14
+ export interface GlobalFlag {
15
+ /** The spellings, as a person types them. */
16
+ readonly spelling: string;
17
+ /** What the flag does, in a phrase. */
18
+ readonly note: string;
19
+ }
20
+ /**
21
+ * The flags the root help lists: the two `assembleContext` reads for
22
+ * every command, typed ahead of the subject or after the action, then
23
+ * `--version`, which `routeLine` reads and which is typed alone.
24
+ */
25
+ export declare const GLOBAL_FLAGS: readonly GlobalFlag[];
@@ -1,12 +1,13 @@
1
1
  /**
2
2
  * The barrel over the command contract: every name `command.ts`,
3
- * `confirm.ts`, `lazy.ts`, `registry-types.ts`, `running.ts`,
4
- * `spends.ts`, `types.ts` and `version.ts` export, and nothing else.
3
+ * `confirm.ts`, `global-flags.ts`, `lazy.ts`, `registry-types.ts`,
4
+ * `running.ts`, `shared-flags.ts`, `spends.ts`, `types.ts` and
5
+ * `version.ts` export, and nothing else.
5
6
  *
6
- * A file outside `packages/rafa/src/core/` imports this file and never the eight
7
+ * A file outside `packages/rafa/src/core/` imports this file and never the ten
7
8
  * behind it (`scripts/survey/core-barrels.ts` measures that, and
8
9
  * `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
9
- * file inside `packages/rafa/src/core/` imports the eight directly and never this
10
+ * file inside `packages/rafa/src/core/` imports the ten directly and never this
10
11
  * file.
11
12
  *
12
13
  * ## What sits behind it
@@ -16,15 +17,22 @@
16
17
  * - `confirm.ts`: the `Prompter` every yes-or-no question goes
17
18
  * through, the line prompter that reads one from a stream, and the
18
19
  * lazy prompter that opens one only to ask;
20
+ * - `global-flags.ts`: `GLOBAL_FLAGS`, the flags every command reads
21
+ * as the root help lists them, and `GlobalFlag`, the shape of one;
19
22
  * - `lazy.ts`: `CommandDeclaration`, a command less its `run`, and
20
23
  * `lazyCommand`, the command over a declaration whose `run` imports
21
24
  * the command's module and delegates to its default export;
22
25
  * - `registry-types.ts`: the contract of the dispatcher's registry,
23
26
  * `CommandRegistry` and the five shapes it names, and
24
27
  * `CommandFeature`, what one feature contributes to it, whose
25
- * builder stays in `src/cli/registry.ts`;
28
+ * builder stays in `packages/rafa/src/cli/registry.ts`;
26
29
  * - `running.ts`: the command this process is running with its parsed
27
30
  * flags, recorded by the dispatcher and read by the spend guard;
31
+ * - `shared-flags.ts`: the flags commands of several features
32
+ * declare, spelled once: `HINT_FLAG` and `HINT_FLAG_SPEC`, the
33
+ * `--no-hint` flag of the six commands that end with a hint, and
34
+ * `DEFAULT_CI_TIMEOUT_MIN`, the default of the loop's
35
+ * `--ci-timeout` and of `pr wait`'s `--timeout`;
28
36
  * - `spends.ts`: a command's `spends` declaration, `CommandSpend`, its
29
37
  * shape check and the mark help ends a spender's roster line with;
30
38
  * - `types.ts`: the contracts copied from open-tomato's `cli-core`,
@@ -33,13 +41,13 @@
33
41
  * - `version.ts`: the version the running build answers with, and the
34
42
  * line that spells it.
35
43
  *
36
- * The eight hold no name in common, so each name is exported once and
44
+ * The ten hold no name in common, so each name is exported once and
37
45
  * from the file that declares it.
38
46
  *
39
- * ## Why one barrel can hold all eight
47
+ * ## Why one barrel can hold all ten
40
48
  *
41
49
  * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
42
- * imports the barrel back by value is a runtime cycle. None of the eight
50
+ * imports the barrel back by value is a runtime cycle. None of the ten
43
51
  * imports a file outside `packages/rafa/src/core/` by value. `command.ts` takes
44
52
  * `spendsProblem` from `spends.ts` beside it, and both take
45
53
  * `describeValue` from `packages/rafa/src/core/config/config-sections.ts`.
@@ -54,38 +62,51 @@
54
62
  * `Output` port with `import type`. `registry-types.ts` imports nothing
55
63
  * by value either: it names `command.ts` with `import type`, and this
56
64
  * file exports its names with `export type`, so loading the barrel
57
- * never loads it.
65
+ * never loads it. `shared-flags.ts` imports nothing by value either: it
66
+ * names `command.ts` with `import type` alone. `global-flags.ts` imports
67
+ * nothing at all.
58
68
  *
59
- * `command.ts` also names `src/project/scope.ts` with `import type`,
60
- * which is erased before anything loads; it named `src/cli/registry.ts`
61
- * the same way until the registry's contract moved into
62
- * `registry-types.ts`. `src/cli/registry.ts` imports this barrel by
63
- * value, for the shape check and the routing words, so that edge is the
64
- * one a value import in `command.ts` would turn into a cycle.
69
+ * `command.ts` also names `packages/rafa/src/project/scope.ts` with `import type`,
70
+ * which is erased before anything loads; it named
71
+ * `packages/rafa/src/cli/registry.ts` the same way until the registry's
72
+ * contract moved into `registry-types.ts`.
73
+ * `packages/rafa/src/cli/registry.ts` imports this barrel by value, for
74
+ * the shape check and the routing words, so that edge is the one a value
75
+ * import in `command.ts` would turn into a cycle.
65
76
  *
66
77
  * Measured when the three moved: the value imports of the non-test files
67
78
  * under `src/` and `packages/` held six cycles before the move and the
68
79
  * same six after it, none through a file of this folder. The control,
69
80
  * the same tree with `command.ts` taking one value (`HELP_WORD`) from
70
- * `src/cli/registry.ts`, held a seventh: `src/cli/registry.ts`,
71
- * `command.ts` and this file.
81
+ * `packages/rafa/src/cli/registry.ts`, held a seventh:
82
+ * `packages/rafa/src/cli/registry.ts`, `command.ts` and this file.
72
83
  *
73
84
  * Measured again when `types.ts` moved in, over every strongly connected
74
85
  * set of the same value imports: five cycles at the base and five after
75
86
  * the move, none through a file of this folder or of `src/cli/core/`.
76
- * The same `HELP_WORD` control held a sixth, `src/cli/registry.ts`,
77
- * `command.ts` and this file.
87
+ * The same `HELP_WORD` control held a sixth,
88
+ * `packages/rafa/src/cli/registry.ts`, `command.ts` and this file.
78
89
  *
79
90
  * Measured again when `spends.ts` moved in, the same way: five cycles at
80
91
  * the base and five after the move, none through a file of this folder
81
92
  * or of `src/cli/`. The same `HELP_WORD` control held a sixth,
82
- * `src/cli/registry.ts`, `command.ts` and this file.
93
+ * `packages/rafa/src/cli/registry.ts`, `command.ts` and this file.
83
94
  *
84
95
  * Measured again when the registry's contract moved into
85
96
  * `registry-types.ts`, the same way: five cycles at the base and five
86
97
  * after the move, none through a file of this folder or of `src/cli/`.
87
- * The same `HELP_WORD` control held a sixth, `src/cli/registry.ts`,
88
- * `command.ts` and this file.
98
+ * The same `HELP_WORD` control held a sixth,
99
+ * `packages/rafa/src/cli/registry.ts`, `command.ts` and this file.
100
+ *
101
+ * Measured again when `shared-flags.ts` moved in, the same way and with
102
+ * the untracked new file read: five cycles at the base and four after
103
+ * the move, none through a file of this folder. The one gone is
104
+ * `packages/rafa-run/src/next/actions.ts` and `packages/rafa-run/src/next/hint.ts`, broken because
105
+ * `actions.ts` now takes `HINT_FLAG` from this barrel rather than from
106
+ * `hint.ts`. The control, `shared-flags.ts` taking one value
107
+ * (`HINT_TIMEOUT_MS`) from `packages/rafa-run/src/next/hint.ts`, folded this file,
108
+ * `shared-flags.ts` and `hint.ts` into one strongly connected set of
109
+ * seventy files.
89
110
  *
90
111
  * ## What it exports
91
112
  *
@@ -93,12 +114,13 @@
93
114
  * spell theirs. No name here is part of the published surface:
94
115
  * `src/index.ts` re-exports nothing from this file.
95
116
  *
96
- * `index.test.ts` holds the list to the eight files: every name any of
117
+ * `index.test.ts` holds the list to the ten files: every name any of
97
118
  * them exports is here once, as the same binding, and no other name is
98
119
  * here.
99
120
  */
100
121
  export type { CommandDeprecation, CommandExample, CommandOutput, FlagDeprecation, RafaCommand, RafaContext, RafaFlagSpec, } from './command.js';
101
122
  export type { LazyPrompter, PromptOutput, Prompter } from './confirm.js';
123
+ export type { GlobalFlag } from './global-flags.js';
102
124
  export type { CommandDeclaration } from './lazy.js';
103
125
  export type { CommandAlias, CommandFeature, CommandRegistry, CommandRegistryInput, ModuleMount, RosterOptions, SubjectSpec, } from './registry-types.js';
104
126
  export type { RunningCommand } from './running.js';
@@ -106,7 +128,9 @@ export type { CommandSpend, SpendsWhen } from './spends.js';
106
128
  export type { ArgSpec, CliCommand, CliContext, FlagSpec, } from './types.js';
107
129
  export { COMMAND_OUTPUTS, CommandExit, commandProblem, commandSpelling, isRoutingWord, isTopLevel, } from './command.js';
108
130
  export { createLinePrompter, lazyPrompter } from './confirm.js';
131
+ export { GLOBAL_FLAGS } from './global-flags.js';
109
132
  export { lazyCommand } from './lazy.js';
110
133
  export { restoreRunningCommand, runAsRunningCommand, runningCommand, setRunningCommand, } from './running.js';
134
+ export { DEFAULT_CI_TIMEOUT_MIN, HINT_FLAG, HINT_FLAG_SPEC } from './shared-flags.js';
111
135
  export { SPENDS_GLYPH, SPENDS_WHEN, spendsCondition, spendsMark, spendsProblem, } from './spends.js';
112
136
  export { RAFA_VERSION, versionLine } from './version.js';
@@ -5,10 +5,10 @@
5
5
  * the registry its subjects and commands in.
6
6
  *
7
7
  * The registry itself, `createCommandRegistry` and the refusals it
8
- * throws, stays the CLI's, in `src/cli/registry.ts`, which imports
9
- * these names from here and re-exports them under the same names. Core
10
- * holds the contract alone, so `RafaContext` can name the registry a
11
- * command runs with without importing a file above core.
8
+ * throws, stays the CLI's, in `packages/rafa/src/cli/registry.ts`, which
9
+ * imports these names from here and re-exports them under the same
10
+ * names. Core holds the contract alone, so `RafaContext` can name the
11
+ * registry a command runs with without importing a file above core.
12
12
  *
13
13
  * Every name here is a type: the file imports `RafaCommand` from
14
14
  * `command.ts` beside it with `import type`, and nothing by value.
@@ -0,0 +1,40 @@
1
+ /**
2
+ * The flags commands of several features declare, spelled once.
3
+ *
4
+ * {@link HINT_FLAG_SPEC} is the `--no-hint` flag of the six commands
5
+ * that end by naming the step that follows (`packages/rafa-run/src/next/ending.ts`):
6
+ * `pr merge`, `pr wait`, `pr triage`, `plan create`, `issue ready` and
7
+ * `loop start`. They belong to four features, and three of them are
8
+ * declared in a declarations file (`packages/rafa-pr/src/commands/pr/declarations.ts`,
9
+ * `packages/rafa-board/src/commands/issue/declarations.ts`), which imports core's entries
10
+ * alone and no module under `src/`. So the flag lives here, where every
11
+ * one of the six can reach it, and each declares this value itself
12
+ * rather than a copy its tests would have to hold equal.
13
+ *
14
+ * {@link DEFAULT_CI_TIMEOUT_MIN} is here for the same reason: the
15
+ * loop's `--ci-timeout` (`src/commands/loop/start.ts`,
16
+ * `packages/rafa-run/src/start/run-setup.ts`) and `pr wait`'s `--timeout`
17
+ * (`packages/rafa-pr/src/commands/pr/declarations.ts`, `packages/rafa-pr/src/commands/pr/wait.ts`) both
18
+ * default to it, and the second is spelled in a declarations file.
19
+ *
20
+ * The file imports nothing by value: it names `command.ts` with
21
+ * `import type` for {@link RafaFlagSpec}, which is erased before
22
+ * anything loads.
23
+ */
24
+ import type { RafaFlagSpec } from './command.js';
25
+ /** The flag each of the six commands declares to let a hint be turned off. */
26
+ export declare const HINT_FLAG = "hint";
27
+ /**
28
+ * The flag each of the six declares, so `--no-hint` suppresses the
29
+ * ending. Boolean and defaulting to true, which is what makes
30
+ * `--no-hint` read as false for it (`parseArgs.ts` beside this file).
31
+ */
32
+ export declare const HINT_FLAG_SPEC: RafaFlagSpec;
33
+ /**
34
+ * How many minutes a pull request's checks are polled before the wait
35
+ * gives up on them. The loop's `--ci-timeout` and `pr wait`'s
36
+ * `--timeout` both default to it, so one wait typed by hand and the
37
+ * loop's own CI gate hold a pull request to the same deadline;
38
+ * `pr triage --resolve` waits this long too.
39
+ */
40
+ export declare const DEFAULT_CI_TIMEOUT_MIN: number;
@@ -5,8 +5,9 @@
5
5
  * Copied from open-tomato's `packages/shared/cli-core/src/types.ts` at
6
6
  * commit `6c774b81fc62489f31748c47e251f11448e3904a` (2026-06-25). The
7
7
  * package is not on the public registry, so rafa copies it rather than
8
- * depending on it, as it copies `parseArgs.ts` and `assembleContext.ts`,
9
- * which stay in `src/cli/core/`, from the same package.
8
+ * depending on it, as it copies `parseArgs.ts`, now beside this file,
9
+ * and `assembleContext.ts`, which stays in `src/cli/core/`, from the
10
+ * same package.
10
11
  *
11
12
  * The copy sat beside those two until it moved into `packages/rafa/src/core/command/`,
12
13
  * so core's `command.ts` reads it without importing the CLI.
@@ -1,3 +1,5 @@
1
+ /** The base every row that names one is read against where `pr.base` names none. */
2
+ export declare const DEFAULT_BASE_BRANCH = "main";
1
3
  /**
2
4
  * The glob matching every plan branch the template names: the template
3
5
  * with `{stub}` replaced by `rafa-*`.
@@ -37,7 +37,7 @@ export type PrerequisiteKind = (typeof PREREQUISITE_KINDS)[number];
37
37
  /**
38
38
  * Which of a run's dispatches need a plan's item: its tasks, its wrap-up,
39
39
  * or both. Read from the `[tasks]` or `[wrap-up]` marker of a
40
- * PREREQUISITES file (`src/preflight/prerequisites-md.ts`).
40
+ * PREREQUISITES file (`packages/rafa/src/preflight/prerequisites-md.ts`).
41
41
  */
42
42
  export type PrerequisiteScope = 'tasks' | 'wrap-up' | 'both';
43
43
  /** One item of `prerequisites.required`. */
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The helpers `config-load.ts` reads a module file (`rafa.config.ts`,
3
+ * `rafa.config.mjs`) through: the `false` the merge removes set back,
4
+ * the entry that last touched each setting, and the refusal of a module
5
+ * it imports and cannot find.
6
+ *
7
+ * They sit beside the loader rather than in it so `config-load.ts`,
8
+ * which reads two places per scope, stays under the 800-line ceiling of
9
+ * `context/source.md`. The rules they apply are the loader's, argued in
10
+ * its module note under "Reading a scope's file" and "Refusals"; nothing
11
+ * here reads a file, and no file outside `config-load.ts` imports this
12
+ * one.
13
+ */
14
+ import type { Mapping } from './config-sections.js';
15
+ import type { ConfigSetting } from './config.js';
16
+ import type { LoadResult, Provenance } from '@open-tomato/define-config';
17
+ /**
18
+ * The refusal of a module file importing `specifier`, which cannot be
19
+ * found from it: the file, the module and, for a package, the install.
20
+ *
21
+ * @param path - The module file.
22
+ * @param specifier - The import it could not resolve.
23
+ * @returns One problem sentence.
24
+ */
25
+ export declare function missingModuleProblem(path: string, specifier: string): string;
26
+ /**
27
+ * A module file's merged value with each `false` the merge removed set
28
+ * back, unless a later entry removed or replaced a mapping above it or
29
+ * the key's reader refuses `false` there; see "Reading a scope's file"
30
+ * in `config-load.ts`.
31
+ *
32
+ * @param result - What define-config's loader read off the file.
33
+ * @returns The mapping the file's settings are read from.
34
+ */
35
+ export declare function restoredMapping({ config, provenance }: LoadResult): Mapping;
36
+ /**
37
+ * The last entry that touched each registered setting of a module file,
38
+ * its key or a key below it: what `provenance` names.
39
+ *
40
+ * @param provenance - The loader's record of every key the file's entries set.
41
+ * @returns The entry by setting, for the settings the file touched.
42
+ */
43
+ export declare function entriesOf(provenance: Provenance): ReadonlyMap<ConfigSetting, number>;
@@ -6,6 +6,13 @@ export interface ConfigRoots {
6
6
  /** The home directory: the user scope's files sit under its `.rafa/`. */
7
7
  readonly home: string;
8
8
  }
9
+ /** The project scope's two files, each read with its templates laid under; see {@link readProjectScope}. */
10
+ export interface ProjectScopeFiles {
11
+ /** The project's YAML file, its local layer, or null when there is none. */
12
+ readonly local: ConfigFile | null;
13
+ /** The project's module file, `rafa.config.ts` or `rafa.config.mjs`, or null when there is none. */
14
+ readonly file: ConfigFile | null;
15
+ }
9
16
  /**
10
17
  * Reads `.rafa/config.yaml` under `root`, or answers null when nothing
11
18
  * is at that path. Anything there that cannot be read — a directory,
@@ -16,13 +23,34 @@ export interface ConfigRoots {
16
23
  */
17
24
  export declare function readConfigFile(root: string): ConfigFile | null;
18
25
  /**
19
- * Reads the user scope's file under `roots.home` and the project's
20
- * under `roots.root`, ranks both against `cli`, and prints a warning
21
- * per shadowed YAML file, per key set twice in one file and per unknown
22
- * key through `warn`, the active output's `warn` when none is given.
23
- * After them it writes one pass line per `dangerous.*` key set off its
24
- * default (`dangerous.ts`), once per invocation: the active output's
25
- * when `warn` is the default, the sink's own when one is given.
26
+ * Reads the project scope's two files under `root`, each with the
27
+ * templates it names laid under it, and answers them unranked: no user
28
+ * scope, no warning printed, no load hook called and no store setting
29
+ * touched. Every refusal {@link loadConfig} raises for either file is
30
+ * raised here, a key set twice in one file at the `merge.duplicates`
31
+ * of the two files included. See the module note.
32
+ *
33
+ * @param root - The project root: the module file sits here and the
34
+ * YAML file under its `.rafa/`.
35
+ * @returns The YAML file as `local` and the module file as `file`, each
36
+ * null when the project holds none.
37
+ * @throws {ConfigError} For a file the load refuses.
38
+ * @throws {Error} When no config section is registered.
39
+ */
40
+ export declare function readProjectScope(root: string): Promise<ProjectScopeFiles>;
41
+ /**
42
+ * Reads the user scope's two files under `roots.home` and the project's
43
+ * two under `roots.root`, ranks the four against `cli`, and prints a
44
+ * warning per key set twice in one file and per unknown key through
45
+ * `warn`, the active output's `warn` when none is given. After them it
46
+ * writes one pass line per `dangerous.*` key set off its default
47
+ * (`dangerous.ts`), once per invocation: the active output's when
48
+ * `warn` is the default, the sink's own when one is given.
49
+ *
50
+ * Each scope's YAML file is its local layer, ranked over its module
51
+ * file key by key: the project's as `local` over its module file as
52
+ * `file`, the user scope's as `userLocal` over its module file as
53
+ * `user`. See "The local layer" in the module note.
26
54
  *
27
55
  * The resolved config is handed to the load hook (`activeConfigLoadHook`
28
56
  * in `section.ts`) before any warning is printed. The registry,
@@ -35,13 +63,16 @@ export declare function readConfigFile(root: string): ConfigFile | null;
35
63
  * (`effort/store/settings.ts`), so every store open after this call
36
64
  * waits that long for a lock.
37
65
  *
66
+ * Each file has the templates its `templates` key names laid under its
67
+ * own keys, read through the active template hook; a name the hook does
68
+ * not know is refused. See "Templates" in the module note.
69
+ *
38
70
  * The files are read and judged before the command line is looked at,
39
- * the user's first, so a run with problems in all three reports the
40
- * user file's alone. See the module note for the home, the lookup and
41
- * every refusal.
71
+ * the user's first and each scope's module file before its YAML file,
72
+ * so a run with problems in every layer reports the first file's alone.
73
+ * See the module note for the home, the lookup and every refusal.
42
74
  *
43
75
  * @returns The resolution, with `provenance` naming the file and entry
44
- * of each setting a file answered, and `shadowed` the YAML files a
45
- * module file left unread.
76
+ * of each setting a file answered.
46
77
  */
47
78
  export declare function loadConfig(roots: ConfigRoots, cli?: ConfigOverrides, warn?: (message: string) => void): Promise<ResolvedConfig>;