@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 registry's contract: the {@link CommandRegistry} the dispatcher
3
+ * routes through, what it is built from, the subjects, aliases and
4
+ * mounts it answers, and the {@link CommandFeature} one feature hands
5
+ * the registry its subjects and commands in.
6
+ *
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.
12
+ *
13
+ * Every name here is a type: the file imports `RafaCommand` from
14
+ * `command.ts` beside it with `import type`, and nothing by value.
15
+ */
16
+ import type { RafaCommand } from './command.js';
17
+ /** A subject: the first routing word, and what its roster line says. */
18
+ export interface SubjectSpec {
19
+ /** The routing word, singular: `issue`. */
20
+ readonly name: string;
21
+ /** One line for the root roster. */
22
+ readonly summary: string;
23
+ }
24
+ /** The commands one module's entry exports, mounted under `module/<name>`. */
25
+ export interface ModuleMount {
26
+ /** The word typed after an `exec` action: `linear` in `rafa module exec linear next`. */
27
+ readonly name: string;
28
+ /** The file the commands were imported from. */
29
+ readonly entry: string;
30
+ /** The commands, each routed by its action. */
31
+ readonly commands: readonly RafaCommand[];
32
+ }
33
+ /** One alias: the words it is typed as, the command it routes to, and whether it is kept for good. */
34
+ export interface CommandAlias {
35
+ readonly words: readonly string[];
36
+ readonly command: RafaCommand;
37
+ /** True for one of the command's `lastingAliases`, which prints no deprecation line. */
38
+ readonly lasting: boolean;
39
+ }
40
+ /** Whether a roster keeps hidden commands. */
41
+ export interface RosterOptions {
42
+ /** Keeps the commands declaring `hidden`. Off by default. */
43
+ readonly includeHidden?: boolean;
44
+ }
45
+ /** What a registry is built from. */
46
+ export interface CommandRegistryInput {
47
+ /** The subjects, in roster order. */
48
+ readonly subjects: readonly SubjectSpec[];
49
+ /** The core commands, in roster order. */
50
+ readonly commands: readonly RafaCommand[];
51
+ }
52
+ /**
53
+ * What one feature contributes to a registry: its name, the subjects it
54
+ * declares and the commands under them, each list in roster order. The
55
+ * same two lists as a {@link CommandRegistryInput}, under the name that
56
+ * says which feature they came from.
57
+ */
58
+ export interface CommandFeature {
59
+ /** The feature's name, which a load failure of one of its commands names. */
60
+ readonly name: string;
61
+ /** The subjects the feature declares, in roster order. */
62
+ readonly subjects: readonly SubjectSpec[];
63
+ /** The feature's commands, in roster order. */
64
+ readonly commands: readonly RafaCommand[];
65
+ }
66
+ /** The subjects, commands, aliases and mounts the dispatcher routes through. Never changes once made. */
67
+ export interface CommandRegistry {
68
+ /** The subjects, in the order declared. */
69
+ readonly subjects: () => readonly SubjectSpec[];
70
+ /** The subject a word names, as its name or its plural, or undefined. */
71
+ readonly subjectOf: (word: string) => SubjectSpec | undefined;
72
+ /** The core commands in the order declared, top-level ones included. */
73
+ readonly commands: (options?: RosterOptions) => readonly RafaCommand[];
74
+ /**
75
+ * The commands under a subject's name, or under a mount's key
76
+ * (`module/<name>`), in the order declared. Empty for a name holding
77
+ * none, a top-level command's included.
78
+ */
79
+ readonly actionsOf: (subject: string, options?: RosterOptions) => readonly RafaCommand[];
80
+ /** The command under a subject's name or a mount's key, and an action, or undefined. */
81
+ readonly find: (subject: string, action: string) => RafaCommand | undefined;
82
+ /** The top-level command a word names, or undefined. */
83
+ readonly topLevel: (word: string) => RafaCommand | undefined;
84
+ /** Every alias, longest first, in the order declared among equals. */
85
+ readonly aliases: () => readonly CommandAlias[];
86
+ /** The mounts, in the order mounted. */
87
+ readonly mounts: () => readonly ModuleMount[];
88
+ /** The mount a module name names, or undefined. */
89
+ readonly mountOf: (name: string) => ModuleMount | undefined;
90
+ /**
91
+ * A new registry holding this one's mounts followed by `mount`, leaving
92
+ * this one unchanged. Throws, answering no registry, on a mount the
93
+ * module note refuses.
94
+ */
95
+ readonly mount: (mount: ModuleMount) => CommandRegistry;
96
+ }
@@ -0,0 +1,96 @@
1
+ /**
2
+ * The command this process is running, and the flags its line was parsed
3
+ * into.
4
+ *
5
+ * A reader deep below a command's `run` — the spend guard in
6
+ * `packages/rafa/src/core/loop/claude.ts` — asks {@link runningCommand} which command it
7
+ * runs under, without a context threaded down to it. The record is held
8
+ * in two places, and the reader answers the first that has one.
9
+ *
10
+ * ## The scope
11
+ *
12
+ * {@link runAsRunningCommand} runs a function with a record in an async
13
+ * scope of its own, an `AsyncLocalStorage` (`node:async_hooks`). Inside
14
+ * that function, and in everything it awaits or starts, the reader
15
+ * answers that record; once the function ends, however it ends, nothing
16
+ * of it is left. The dispatcher runs every command this way
17
+ * (`src/cli/dispatch.ts`), so nothing it records outlives the
18
+ * invocation.
19
+ *
20
+ * A scope belongs to one run, so runs need not nest to stay apart. Two
21
+ * runs that overlap in one process, started together and awaited with
22
+ * `Promise.all`, each read their own record whichever ends first. A run
23
+ * started inside another reads the inner record inside and the outer one
24
+ * after. The module-level value below keeps overlapping runs apart only
25
+ * while they nest: set and put back in a `finally` it is a stack, and
26
+ * two that end out of order leave the record of one of them for the
27
+ * rest of the process (#927).
28
+ *
29
+ * ## The module-level value
30
+ *
31
+ * {@link setRunningCommand} records a command with its parsed flags at
32
+ * module level and answers the record it replaced, null when nothing was
33
+ * recorded. {@link restoreRunningCommand} puts back a record
34
+ * {@link setRunningCommand} answered, so a caller that sets one restores
35
+ * it in a `finally`. Outside every scope the reader answers this value,
36
+ * or null. No module but a test sets it: a case stands in for a dispatch
37
+ * with it, as `src/tests/core-coupled/core/loop/claude.test.ts` does ahead of a door.
38
+ *
39
+ * ## A set made inside a scope
40
+ *
41
+ * The reader prefers the scope, and the setters write the module-level
42
+ * value alone, inside a scope as outside one. So a set made inside a
43
+ * scope changes nothing that scope reads, answers the module-level
44
+ * record it replaced, and is what the reader answers once the scope has
45
+ * ended. A scope's record cannot be replaced from inside it.
46
+ *
47
+ * ## What reads outside the scope
48
+ *
49
+ * A scope follows the awaits and the callbacks started inside it. A
50
+ * callback the runtime calls from elsewhere does not carry it. Measured
51
+ * under bun 1.3.14, three listeners registered inside a scope read no
52
+ * store: a `process.on` signal listener when the signal arrived, an
53
+ * abort listener that handler fired, and an abort listener an
54
+ * `AbortSignal.timeout` fired. A timer, a child process's `data`
55
+ * listener, a `readline` `line` listener and the code after an await
56
+ * such a handler settled all read the scope's. A reader outside the
57
+ * scope gets the module-level value; one that needs the scope's is
58
+ * wrapped with `AsyncResource.bind` where it is registered.
59
+ *
60
+ * The flags are copied and frozen when recorded, so a caller changing
61
+ * its own flags object afterwards changes nothing recorded.
62
+ *
63
+ * Bun runs every test file in one process, and the module-level value is
64
+ * module state: a case that sets a record restores the one it replaced
65
+ * after it.
66
+ */
67
+ import type { RafaCommand } from './command.js';
68
+ import type { CliContext } from './types.js';
69
+ /** A running command and the flags its line was parsed into. */
70
+ export interface RunningCommand {
71
+ /** The command running. */
72
+ readonly command: RafaCommand;
73
+ /** Its parsed flags by name, as the context carries them. */
74
+ readonly flags: CliContext['flags'];
75
+ }
76
+ /**
77
+ * Runs `run` with `command` and `flags` recorded as running in an async
78
+ * scope of its own, and answers what `run` answers. The record is read
79
+ * inside `run` and whatever it awaits, and nowhere after it; see the
80
+ * module note.
81
+ */
82
+ export declare function runAsRunningCommand<T>(command: RafaCommand, flags: CliContext['flags'], run: () => T): T;
83
+ /**
84
+ * Records `command` as running with `flags` at module level, and answers
85
+ * the module-level record it replaced for {@link restoreRunningCommand}.
86
+ * Inside a scope it changes nothing that scope reads; see the module
87
+ * note.
88
+ */
89
+ export declare function setRunningCommand(command: RafaCommand, flags: CliContext['flags']): RunningCommand | null;
90
+ /**
91
+ * The command running now with its flags: the record of the scope this
92
+ * is read in, else the module-level one, else null.
93
+ */
94
+ export declare function runningCommand(): RunningCommand | null;
95
+ /** Puts back `previous`, a module-level record {@link setRunningCommand} answered. */
96
+ export declare function restoreRunningCommand(previous: RunningCommand | null): void;
@@ -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 (`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 (`src/commands/pr/declarations.ts`,
9
+ * `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
+ * `src/start/run-setup.ts`) and `pr wait`'s `--timeout`
17
+ * (`src/commands/pr/declarations.ts`, `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 (`src/cli/core/parseArgs.ts`).
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;
@@ -0,0 +1,39 @@
1
+ /** The mark help puts on a command that spends Claude usage. */
2
+ export declare const SPENDS_GLYPH = "\uD83E\uDE99";
3
+ /** The four values `when` takes. */
4
+ export declare const SPENDS_WHEN: readonly ["always", "with", "unless", "through"];
5
+ /** One of the four forms of a declaration. */
6
+ export type SpendsWhen = (typeof SPENDS_WHEN)[number];
7
+ /** What a command spends, and when; see the module note. */
8
+ export type CommandSpend = {
9
+ readonly when: 'always';
10
+ readonly what: string;
11
+ } | {
12
+ readonly when: 'with';
13
+ readonly flag: string;
14
+ readonly what: string;
15
+ } | {
16
+ readonly when: 'unless';
17
+ readonly flag: string;
18
+ readonly what: string;
19
+ } | {
20
+ readonly when: 'through';
21
+ readonly what: string;
22
+ };
23
+ /**
24
+ * What keeps `value` from being a `spends` declaration, as a sentence
25
+ * naming the field, or null when nothing does. Absent passes: a command
26
+ * that declares nothing spends nothing.
27
+ */
28
+ export declare function spendsProblem(value: unknown): string | null;
29
+ /**
30
+ * The condition a declaration spends under, as help prints it:
31
+ * `with --resolve`, `unless --no-model`, or null for `always` and
32
+ * `through`.
33
+ */
34
+ export declare function spendsCondition(spend: CommandSpend): string | null;
35
+ /**
36
+ * The mark ending a spender's roster line: `🪙`, `🪙 with --resolve` or
37
+ * `🪙 unless --no-model`.
38
+ */
39
+ export declare function spendsMark(spend: CommandSpend): string;
@@ -0,0 +1,92 @@
1
+ /**
2
+ * The contracts a rafa command is written against: the context it runs
3
+ * with, the positional arguments and flags it declares, and the command.
4
+ *
5
+ * Copied from open-tomato's `packages/shared/cli-core/src/types.ts` at
6
+ * commit `6c774b81fc62489f31748c47e251f11448e3904a` (2026-06-25). The
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.
10
+ *
11
+ * The copy sat beside those two until it moved into `packages/rafa/src/core/command/`,
12
+ * so core's `command.ts` reads it without importing the CLI.
13
+ * `packages/rafa/src/core/command/index.ts` exports its names to every
14
+ * file outside core; the re-export `src/cli/core/types.ts` kept for the
15
+ * CLI was deleted when core moved into its package (#1090).
16
+ *
17
+ * ## What the copy changes
18
+ *
19
+ * `CliContext.output` is rafa's `Output` port, which `packages/rafa/src/ports/index.ts`
20
+ * copies from the source's `CliOutput`. The source imports that type from
21
+ * its own `output.ts`, whose two renderers rafa ported to
22
+ * `packages/rafa/src/core/output/text.ts` and `src/adapters/output/json.ts`. Every member is otherwise the source's, with a
23
+ * TSDoc line added to each.
24
+ *
25
+ * `ArgSpec` and `FlagSpec` are still two names for one shape. The source
26
+ * declares `default` and `aliases` on both and reads neither. The copy's
27
+ * `parseArgs` reads a flag's `default` and `aliases` and an argument's
28
+ * `default`, and refuses an argument that declares `aliases`, as its
29
+ * module note says.
30
+ */
31
+ import type { Output } from '../../ports/index.js';
32
+ import type { OutputMode } from '../config/config-sections.js';
33
+ /** Everything a command runs with, built and frozen by `assembleContext`. */
34
+ export interface CliContext {
35
+ /** The positional words of the line, in order. */
36
+ args: readonly string[];
37
+ /** The flags of the line by name: a value, `true` for a bare flag, `false` for `--no-<name>`. */
38
+ flags: Readonly<Record<string, string | boolean>>;
39
+ /** How the command's output is rendered: lines a person reads, NDJSON events, or one line per loop event. */
40
+ outputMode: OutputMode;
41
+ /** How much the command writes, from 0, the least, to 3. */
42
+ verbosity: 0 | 1 | 2 | 3;
43
+ /** Where the command writes, rendered in its `outputMode`. */
44
+ output: Output;
45
+ /** Aborted when the command is asked to stop. */
46
+ signal: AbortSignal;
47
+ /** The environment the context was built from, as a frozen copy. */
48
+ env: Readonly<Record<string, string | undefined>>;
49
+ }
50
+ /** A positional argument a command declares. */
51
+ export interface ArgSpec {
52
+ /** What the argument is called. */
53
+ name: string;
54
+ /** What the argument holds, in a sentence. */
55
+ description: string;
56
+ /** The value's type. `parseArgs` converts no word to it: every word is a string. */
57
+ type: 'string' | 'boolean' | 'number';
58
+ /** Whether the command needs the argument. `parseArgs` refuses no line leaving it out. */
59
+ required?: boolean;
60
+ /** The word filled in when the line leaves the argument out, as a string. */
61
+ default?: string | boolean | number;
62
+ /** Refused by `parseArgs` when it names any: a positional word has no spelling but its place. */
63
+ aliases?: readonly string[];
64
+ }
65
+ /** A flag a command declares. */
66
+ export interface FlagSpec {
67
+ /** The flag's name, which `CliContext.flags` is keyed by: `plan` for `--plan`. */
68
+ name: string;
69
+ /** What the flag does, in a sentence. */
70
+ description: string;
71
+ /** The value's type. `parseArgs` converts no value to it: a value is a string. */
72
+ type: 'string' | 'boolean' | 'number';
73
+ /** Whether the command needs the flag. `parseArgs` refuses no line leaving it out. */
74
+ required?: boolean;
75
+ /** The value filled in when the line gives the flag none: a number as its string, anything else as it is. */
76
+ default?: string | boolean | number;
77
+ /** Other spellings of the flag, each read as its name: `p` reads `-p` and `--p` as `plan`. */
78
+ aliases?: readonly string[];
79
+ }
80
+ /** A command: what it declares, and what runs. */
81
+ export interface CliCommand {
82
+ /** The command's name. */
83
+ name: string;
84
+ /** What the command does. */
85
+ description: string;
86
+ /** The positional arguments, in the order the line gives them. */
87
+ args: ArgSpec[];
88
+ /** The flags. */
89
+ flags: FlagSpec[];
90
+ /** Runs the command with the context built for it. */
91
+ run: (context: CliContext) => Promise<void>;
92
+ }
@@ -0,0 +1,4 @@
1
+ /** The `version` of `package.json`, inlined into the build that reads it. */
2
+ export declare const RAFA_VERSION: string;
3
+ /** The line `rafa --version` prints and `rafa doctor` opens with: `rafa <version>`. */
4
+ export declare function versionLine(): string;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * The glob matching every plan branch the template names: the template
3
+ * with `{stub}` replaced by `rafa-*`.
4
+ *
5
+ * @param template - A `naming.branch` template, such as `feat/{stub}`.
6
+ * @returns The glob, `feat/rafa-*` for the default template.
7
+ */
8
+ export declare function branchGlob(template: string): string;
9
+ /**
10
+ * The stub a branch carries under the template: what lies between the
11
+ * template's part before `{stub}` and its part after, when the branch
12
+ * opens with the one, closes with the other, and the stub between opens
13
+ * with `rafa-`.
14
+ *
15
+ * @param template - A `naming.branch` template, such as `feat/{stub}`.
16
+ * @param branch - A branch name, without `refs/heads/`.
17
+ * @returns The stub, `rafa-12-x` for `feat/rafa-12-x` under the default
18
+ * template; null for a branch the template does not name.
19
+ */
20
+ export declare function stubOfBranch(template: string, branch: string): string | null;
@@ -0,0 +1,86 @@
1
+ /**
2
+ * The two item shapes the schema's lists hold: a prerequisite item and
3
+ * a module source, each read by one reader of `config-sections.ts`'s
4
+ * {@link Reader} shape.
5
+ *
6
+ * Every other rule about a VALUE is `config-sections.ts`'s, and so are
7
+ * the rules every reader keeps, items included: a kind key matched with
8
+ * `===`, a null optional key saying nothing, and a key an item does not
9
+ * read retained as a {@link ConfigExtra}. The shapes moved here out of
10
+ * that module to keep it under the size cap of `context/source.md`: it
11
+ * stood at 792 lines before the move. `config.ts` re-exports the item
12
+ * types and kind lists, as it did while they lived there.
13
+ *
14
+ * The import runs one way. This module reads the reading helpers
15
+ * `config-sections.ts` exports, and that module imports nothing from
16
+ * this one, so the two form no cycle.
17
+ *
18
+ * ## The item shapes
19
+ *
20
+ * A prerequisite item names exactly one of `tool`, `env`, `service` or
21
+ * `lsp`, may carry a `probe`, and on the optional tier a `reason`. That
22
+ * is the shape of the block under "Config schema" in
23
+ * `.rafa/specs/phase-1-installable.md`. A `reason` on a required item is a
24
+ * key that tier does not read, so it is retained and warned about.
25
+ *
26
+ * A module source names exactly one of `npm`, `github` or `path`, and a
27
+ * `github` source may carry a `ref`: the source shapes of the registry
28
+ * example in `.rafa/specs/modules-and-addons.md`, which `modules:` lists
29
+ * "by source". This module accepts all three. Whether a source kind can
30
+ * be loaded is the module loader's answer, not the config's.
31
+ */
32
+ import type { Reader } from './config-sections.js';
33
+ /** The keys one of which names a prerequisite item. */
34
+ export declare const PREREQUISITE_KINDS: readonly ["tool", "env", "service", "lsp"];
35
+ /** One of the four prerequisite kinds. */
36
+ export type PrerequisiteKind = (typeof PREREQUISITE_KINDS)[number];
37
+ /**
38
+ * Which of a run's dispatches need a plan's item: its tasks, its wrap-up,
39
+ * or both. Read from the `[tasks]` or `[wrap-up]` marker of a
40
+ * PREREQUISITES file (`src/preflight/prerequisites-md.ts`).
41
+ */
42
+ export type PrerequisiteScope = 'tasks' | 'wrap-up' | 'both';
43
+ /** One item of `prerequisites.required`. */
44
+ export interface PrerequisiteItem {
45
+ /** Which of the four keys named it. */
46
+ kind: PrerequisiteKind;
47
+ /** What that key named: `bun`, `GITHUB_TOKEN`, a URL, `typescript`. */
48
+ name: string;
49
+ /** The command that proves it, or null to check presence alone. */
50
+ probe: string | null;
51
+ /**
52
+ * The scope a plan's PREREQUISITES file gave the item. Left out of an
53
+ * item the config names, which has no spelling for one.
54
+ */
55
+ scope?: PrerequisiteScope;
56
+ }
57
+ /** One item of `prerequisites.optional`. */
58
+ export interface OptionalPrerequisiteItem extends PrerequisiteItem {
59
+ /** Why the item helps, for the line naming it missing; or null. */
60
+ reason: string | null;
61
+ }
62
+ /** The keys a required prerequisite item reads. */
63
+ export declare const REQUIRED_ITEM_KEYS: readonly string[];
64
+ /** The keys an optional prerequisite item reads. */
65
+ export declare const OPTIONAL_ITEM_KEYS: readonly string[];
66
+ /** Reads one `prerequisites.required` item. */
67
+ export declare const requiredPrerequisite: Reader<PrerequisiteItem>;
68
+ /** Reads one `prerequisites.optional` item. */
69
+ export declare const optionalPrerequisite: Reader<OptionalPrerequisiteItem>;
70
+ /** The keys one of which names a module source. */
71
+ export declare const MODULE_SOURCE_KINDS: readonly ["npm", "github", "path"];
72
+ /** One of the three module source kinds. */
73
+ export type ModuleSourceKind = (typeof MODULE_SOURCE_KINDS)[number];
74
+ /** One entry of `modules:`: where a module is installed from. */
75
+ export interface ModuleSource {
76
+ /** Which of the three keys named it. */
77
+ kind: ModuleSourceKind;
78
+ /** What that key named: a package name, an `owner/repo`, a path. */
79
+ location: string;
80
+ /** The git ref beside a `github` source; null for every other. */
81
+ ref: string | null;
82
+ }
83
+ /** The keys a module source reads, `ref` on a `github` one alone. */
84
+ export declare const MODULE_SOURCE_KEYS: readonly string[];
85
+ /** Reads one `modules:` entry. */
86
+ export declare const moduleSource: Reader<ModuleSource>;
@@ -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>;
@@ -0,0 +1,78 @@
1
+ import type { ConfigFile, ConfigOverrides, ResolvedConfig } from './config.js';
2
+ /** The two directories {@link loadConfig} reads a config file under. */
3
+ export interface ConfigRoots {
4
+ /** The project root: its scope's files sit here and under its `.rafa/`. */
5
+ readonly root: string;
6
+ /** The home directory: the user scope's files sit under its `.rafa/`. */
7
+ readonly home: string;
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
+ }
16
+ /**
17
+ * Reads `.rafa/config.yaml` under `root`, or answers null when nothing
18
+ * is at that path. Anything there that cannot be read — a directory,
19
+ * a file without read permission — is refused with a
20
+ * {@link ConfigError} rather than read as absent; see the module note.
21
+ * Reads the YAML file alone: {@link loadConfig} is what looks up a
22
+ * scope's module files.
23
+ */
24
+ export declare function readConfigFile(root: string): ConfigFile | null;
25
+ /**
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.
54
+ *
55
+ * The resolved config is handed to the load hook (`activeConfigLoadHook`
56
+ * in `section.ts`) before any warning is printed. The registry,
57
+ * `src/config-registry.ts`, sets that hook to hand the logger
58
+ * (`adapters/logger/settings.ts`) its `logger` settings, so a
59
+ * `logger.level` of `error` also quiets the warnings of the load that
60
+ * set it. With no hook set the logger keeps the settings it had.
61
+ *
62
+ * The resolved `effort.busyTimeoutMs` is handed to the effort store
63
+ * (`effort/store/settings.ts`), so every store open after this call
64
+ * waits that long for a lock.
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
+ *
70
+ * The files are read and judged before the command line is looked at,
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.
74
+ *
75
+ * @returns The resolution, with `provenance` naming the file and entry
76
+ * of each setting a file answered.
77
+ */
78
+ export declare function loadConfig(roots: ConfigRoots, cli?: ConfigOverrides, warn?: (message: string) => void): Promise<ResolvedConfig>;
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Where a resolved setting came from: the record `ResolvedConfig`
3
+ * carries beside its values, `provenance` (`config.ts`).
4
+ *
5
+ * ## An origin
6
+ *
7
+ * A {@link SettingOrigin} names the file that answered one setting and
8
+ * the entry of that file that last set it, zero-based, as
9
+ * `@open-tomato/define-config` counts a module file's entries. A YAML
10
+ * file is one entry, so every setting it answers is entry 0. A setting
11
+ * the command line or a default answered has no origin: no file set it.
12
+ *
13
+ * `resolveConfig` ranks four files, two per scope: the project's local
14
+ * file, the project's file, the user scope's local file and the user
15
+ * scope's file, highest first. {@link originOf} takes the FILE that
16
+ * answered a setting, never a source name, so the two user files, which
17
+ * both report source `user`, each name their own path, as the project's
18
+ * local file (`local`) and its other file (`file`) do. `cli` and
19
+ * `default` name no file and answer none. A map setting merged across
20
+ * several files names the highest of them, the file its source names.
21
+ *
22
+ * A setting a template answered (`template`) names the file whose
23
+ * `templates` key named it, which is the file that answered, since a
24
+ * file's templates are laid under its own keys, with the entry of that
25
+ * file that last set `templates`, and carries the template's name as
26
+ * `template`. An origin a file's own key gave carries no `template`.
27
+ *
28
+ * No file of a scope shadows another: each scope is read from its
29
+ * module file and its YAML file over it (`config-load.ts`), so no
30
+ * record here names a file left unread.
31
+ */
32
+ import type { ConfigFile, ConfigSetting, ConfigSource } from './config.js';
33
+ /** The two scopes a config file is read in. */
34
+ export type ConfigScopeName = 'user' | 'project';
35
+ /** The file and entry that answered one setting. */
36
+ export interface SettingOrigin {
37
+ /** The file, as its layer names it. */
38
+ readonly file: string;
39
+ /**
40
+ * The zero-based entry of that file that last set the setting, or for
41
+ * a template's setting the entry that last set the file's `templates`.
42
+ */
43
+ readonly entry: number;
44
+ /** The template that answered the setting, by name; absent for a file's own key. */
45
+ readonly template?: string;
46
+ }
47
+ /**
48
+ * The origin of `setting`, read off the file that answered it; see the
49
+ * module note.
50
+ *
51
+ * @param source - The layer that answered the setting.
52
+ * @param setting - The setting.
53
+ * @param answeredBy - The file that answered it, or null where the
54
+ * command line or a default did.
55
+ * @returns The file and entry, or null for the command line, a default,
56
+ * or a template the file records none for.
57
+ */
58
+ export declare function originOf(source: ConfigSource, setting: ConfigSetting, answeredBy: ConfigFile | null): SettingOrigin | null;