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