@open-tomato/rafa 0.52.1 → 0.54.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 (40) hide show
  1. package/dist/PROMPT.md +7 -0
  2. package/dist/bundled/agents/loop-implementer.md +7 -1
  3. package/dist/bundled/operators/skills/rafa-stretch-gap-log/SKILL.md +16 -0
  4. package/dist/bundled/operators/skills/rafa-stretch-pit-stop/SKILL.md +14 -8
  5. package/dist/bundled/operators/skills/rafa-stretch-sweep/SKILL.md +4 -2
  6. package/dist/cli.js +4401 -2084
  7. package/dist/config/index.js +2 -2
  8. package/dist/config/shape.d.ts +7 -5
  9. package/dist/config-registry.d.ts +5 -5
  10. package/dist/config-schema-collaborate.d.ts +85 -0
  11. package/dist/config-schema-features.d.ts +2 -2
  12. package/dist/config-schema-hints.d.ts +53 -0
  13. package/dist/config-schema-hub.d.ts +5 -4
  14. package/dist/core/command/shared-flags.d.ts +1 -1
  15. package/dist/core/config/config-schema.d.ts +1 -1
  16. package/dist/core/config/config.d.ts +1 -1
  17. package/dist/core/git/index.d.ts +12 -5
  18. package/dist/core/git/placed-line.d.ts +86 -0
  19. package/dist/effort/session-log-path.d.ts +34 -0
  20. package/dist/effort/store/answered-rows.d.ts +38 -0
  21. package/dist/effort/store/index.js +5 -3
  22. package/dist/effort/store/merge-conflicts.d.ts +8 -4
  23. package/dist/effort/store/merge-rules.d.ts +16 -5
  24. package/dist/effort/store/merge-store.d.ts +14 -3
  25. package/dist/effort/store/origins.d.ts +5 -4
  26. package/dist/effort/store/repository-facts.d.ts +147 -0
  27. package/dist/effort/store/session-row-types.d.ts +6 -1
  28. package/dist/effort/store/sqlite.d.ts +11 -6
  29. package/dist/{index-4dwaxd5r.js → index-8rr1etrx.js} +10 -3
  30. package/dist/{index-nqaqh4zz.js → index-d772zq3m.js} +44 -4
  31. package/dist/{index-m672ptpg.js → index-dj8en7fg.js} +1 -1
  32. package/dist/{index-1tdzcheq.js → index-mkhbaye7.js} +306 -43
  33. package/dist/{index-4wy2nmyt.js → index-waawdjq2.js} +140 -119
  34. package/dist/index.js +1622 -564
  35. package/dist/learning/index.js +112 -53
  36. package/dist/ports/index.d.ts +5 -5
  37. package/dist/ports/learning.d.ts +28 -2
  38. package/dist/{ready-kac4ty0p.js → ready-9e1pyxdh.js} +3 -3
  39. package/dist/utils/shell.d.ts +17 -0
  40. package/package.json +12 -5
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Repository facts: the readings of a shared source that two stores can
3
+ * both hold, and the supersedes that make two readings of one fact
4
+ * count once.
5
+ *
6
+ * A port and the hub can each read the same pull request's checks on
7
+ * the same head, so a merge of their stores holds two `plan_ci` rows that
8
+ * say one thing. Neither row is wrong and neither is dropped: the second
9
+ * is superseded by a row of `reading_supersedes`, never by a flag on the
10
+ * reading, and every reader that counts facts reads through those rows.
11
+ *
12
+ * ## The registry
13
+ *
14
+ * {@link REPOSITORY_FACTS} lists every table whose rows are readings of
15
+ * a shared source, beside `MERGE_RULES` (`merge-rules.ts`). An entry
16
+ * declares only its fact columns, the columns whose values are what the
17
+ * reading says, and its time column, when the reading was taken. Its
18
+ * identity, the columns that name one reading, is the table's
19
+ * `MERGE_RULES` identity and is never spelled twice.
20
+ *
21
+ * | Table | Facts | Time |
22
+ * | --- | --- | --- |
23
+ * | `plan_ci` | `pr`, `head_sha`, `verdict`, `failing` | `read_at` |
24
+ *
25
+ * ## The rule
26
+ *
27
+ * {@link SAME_FACT_RULE}, `same-fact@1`: two readings of one table are
28
+ * one fact when their fact columns are equal, two NULLs counting as
29
+ * equal; the canonical reading is the one with the earliest reading
30
+ * time. Two readings at one time are ordered by their key, so every
31
+ * store picks the same canonical one. For `plan_ci` the time is part of
32
+ * the identity, so two readings with one `pr`, `head_sha` and `read_at`
33
+ * are one row already and never meet that tie.
34
+ *
35
+ * ## A reading's key
36
+ *
37
+ * {@link readingKey} names a reading by its table's identity, as the
38
+ * JSON array of the identity values in `MERGE_RULES` order:
39
+ * `[7,"3f2a…","2026-11-08T10:00:00.000Z"]` for a `plan_ci` row. Never by
40
+ * the origin pair, which a reading an older runtime wrote does not hold.
41
+ * An identity value is text, a finite number or NULL; any other value is
42
+ * refused, since JSON would not spell it back.
43
+ *
44
+ * ## Writing supersedes
45
+ *
46
+ * {@link writeSupersedes} is handed the keys of the readings a write or
47
+ * a merge touched. For each fact they reach it reads every reading of
48
+ * that fact, takes the canonical one, and gives every other reading that
49
+ * is not yet the `superseded_key` of a row of that table and rule one
50
+ * row naming the canonical reading. So a late reading older than the
51
+ * canonical one adds a row superseding the old canonical reading, and
52
+ * the rows the old one already canonicalised are left to the reader's
53
+ * chain. Each insert is stamped (`stampedValues`, `origins.ts`) and
54
+ * absorbed on the table's identity (`reading_supersedes_by_fact`), so a
55
+ * port and the hub that write one supersede write one row.
56
+ *
57
+ * The writer opens no transaction of its own: a merge calls it as its
58
+ * last step inside the transaction of the union, and a reading's writer
59
+ * inside its own, so the readings and their supersedes land together.
60
+ * It never rescans a table it was not handed keys of.
61
+ *
62
+ * ## Reading facts
63
+ *
64
+ * {@link readRepositoryFacts} answers one {@link RepositoryFact} per
65
+ * fact of a table: its canonical reading, `sightings` (how many readings
66
+ * it superseded, so two readings of one fact answer one sighting), the
67
+ * origins that read it, and `lastSighting`, the latest reading time over
68
+ * all its readings, the canonical one included. Each reading follows its
69
+ * supersede rows to the reading no row of the rule supersedes, the
70
+ * earliest one first where a reading has two; a row naming a reading the
71
+ * store does not hold is not followed, and a chain that comes back to a
72
+ * reading it passed, which the writer never writes, ends at the earliest
73
+ * reading of that loop. The reader trusts the rows: what they join is
74
+ * one fact, as the writer that wrote them read it.
75
+ *
76
+ * A reading no supersede names stands as a fact of its own, as a
77
+ * reading written before the writer ran does. Nothing here matches
78
+ * readings at read time.
79
+ */
80
+ import type { Database, SQLQueryBindings } from 'bun:sqlite';
81
+ /** One {@link REPOSITORY_FACTS} entry: what a reading says, and when it was read. */
82
+ export interface RepositoryFactColumns {
83
+ /** The columns whose values are the fact; equal in all of them, two readings are one fact. */
84
+ readonly facts: readonly string[];
85
+ /** The column holding when the reading was taken, as ISO 8601 text. */
86
+ readonly time: string;
87
+ }
88
+ /** Every table whose rows are readings of a shared source, by name. */
89
+ export declare const REPOSITORY_FACTS: Readonly<Record<string, RepositoryFactColumns>>;
90
+ /** The rule every supersede here is written under, as `reading_supersedes.rule` holds it. */
91
+ export declare const SAME_FACT_RULE = "same-fact@1";
92
+ /** One reading of a repository fact, as the reader answers it. */
93
+ export interface FactReading {
94
+ /** The reading's key, see {@link readingKey}. */
95
+ readonly key: string;
96
+ /** The fact columns' values, by column name. */
97
+ readonly fact: Readonly<Record<string, SQLQueryBindings>>;
98
+ /** When it was read. */
99
+ readonly time: string;
100
+ /** The store that wrote it, or null for a row with no origin pair. */
101
+ readonly origin: string | null;
102
+ }
103
+ /** One fact of a table, every reading of it counted once. */
104
+ export interface RepositoryFact {
105
+ /** The reading table. */
106
+ readonly table: string;
107
+ /** The earliest reading, the one its supersede chains end at. */
108
+ readonly canonical: FactReading;
109
+ /** How many readings the canonical one supersedes. */
110
+ readonly sightings: number;
111
+ /** The distinct origin stores of its readings, sorted; a reading with no origin adds none. */
112
+ readonly origins: readonly string[];
113
+ /** The latest reading time over all its readings, the canonical one included. */
114
+ readonly lastSighting: string;
115
+ }
116
+ /** A row as the readings query answers it. */
117
+ type StoredRow = Readonly<Record<string, SQLQueryBindings>>;
118
+ /**
119
+ * The key of one reading of `table`: the JSON array of its identity
120
+ * values in `MERGE_RULES` order. Throws for a table with no
121
+ * {@link REPOSITORY_FACTS} entry and for an identity value that is not
122
+ * text, a finite number or NULL. See the module note.
123
+ */
124
+ export declare function readingKey(table: string, row: StoredRow): string;
125
+ /**
126
+ * Writes the supersedes the readings of `table` named by `touchedKeys`
127
+ * call for, and answers how many rows it added: for each fact they
128
+ * reach, one row per reading of it that is not its canonical one and
129
+ * not yet superseded under {@link SAME_FACT_RULE}. A key named twice, or
130
+ * two keys of one fact, write that fact's rows once.
131
+ *
132
+ * Throws for a table with no {@link REPOSITORY_FACTS} entry, a key that
133
+ * is not a JSON array of the table's identity values, and a key naming
134
+ * no reading the store holds: each is a caller's fault, and the caller's
135
+ * transaction takes back what was written. See the module note.
136
+ */
137
+ export declare function writeSupersedes(db: Database, table: string, touchedKeys: readonly string[]): number;
138
+ /**
139
+ * Every fact of `table`, each reading counted once: one
140
+ * {@link RepositoryFact} per reading the supersede chains end at, in the
141
+ * order of their canonical readings' time, then key.
142
+ *
143
+ * Throws for a table with no {@link REPOSITORY_FACTS} entry. See the
144
+ * module note for how a chain is followed.
145
+ */
146
+ export declare function readRepositoryFacts(db: Database, table: string): RepositoryFact[];
147
+ export {};
@@ -34,7 +34,12 @@ export interface SessionUsageTotals {
34
34
  export interface SessionStats {
35
35
  /** Log basename without its extension, which is the session uuid. */
36
36
  sessionId: string;
37
- /** The path the row was accumulated from. */
37
+ /**
38
+ * The stored form of the log's path (#1489): `<folder>/<file>`, with no
39
+ * leading `/`, for a log under `<home>/.claude/projects/`, joined back
40
+ * under the reading machine's home by `resolveSessionLogPath`; the
41
+ * absolute path for a log anywhere else, such as a `logDir` override's.
42
+ */
38
43
  filePath: string;
39
44
  /** Non-empty lines read. */
40
45
  lineCount: number;
@@ -42,14 +42,17 @@
42
42
  * because the uniqueness constraint on it is what deduplicates.
43
43
  * `worktree` is repeated beside it only so a query can read it; `read`
44
44
  * still answers the row from `row_json`, so both backends' rows stay
45
- * byte-identical.
45
+ * byte-identical. Both pass what they parsed through `answeredRows`
46
+ * (`answered-rows.ts`) on its way out of `read`, which answers an old
47
+ * session row's absolute `filePath` in its stored form and leaves
48
+ * `row_json` as it was written.
46
49
  *
47
50
  * `seq` is an `INTEGER PRIMARY KEY`, SQLite's alias for the rowid, so
48
51
  * the append order is a column the schema declares rather than an
49
52
  * implicit one. That is a declaration, not a repair: measured on SQLite
50
53
  * 3.51.0, a `VACUUM` left implicit rowids where they were as well.
51
54
  *
52
- * The file holds seventeen tables that are not kinds. Six are filled from
55
+ * The file holds eighteen tables that are not kinds. Six are filled from
53
56
  * task reports: `findings`, `blockers`, `out_of_scope_bugs` and
54
57
  * `changes`, one per list a report carries, `report_absences`, one row
55
58
  * per task session whose output held no report to read, and
@@ -62,10 +65,12 @@
62
65
  * six are, one row per documentation line a report named as stale;
63
66
  * `stale-docs.ts` writes it and holds its row type. A twelfth,
64
67
  * `bug_routes`, holds one row per `out_of_scope_bugs` entry the triage
65
- * step routed; `bug-routes.ts` writes it and holds its row type. The
66
- * thirteenth is `schema_migrations`, the migration log, which only
67
- * `bring-forward.ts` writes; the section on bringing a store forward
68
- * says what it holds. The last four are the store's own identity and
68
+ * step routed; `bug-routes.ts` writes it and holds its row type. A
69
+ * thirteenth, `reading_supersedes`, holds one row per reading of a
70
+ * shared source that another reading of the same fact supersedes;
71
+ * `repository-facts.ts` writes and reads it. The fourteenth is `schema_migrations`, the
72
+ * migration log, which only `bring-forward.ts` writes; the section on
73
+ * bringing a store forward says what it holds. The last four are the store's own identity and
69
74
  * merge trail: `store_meta`, `store_replaced`, `merges` and
70
75
  * `merge_conflicts`. The port's row map names none of them, and
71
76
  * nothing in this module reads or writes them. `findings.ts` writes the
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  CORE_SECTION
4
- } from "./index-m672ptpg.js";
4
+ } from "./index-dj8en7fg.js";
5
5
  import {
6
6
  BUSY_TIMEOUT_MAX_MS,
7
7
  BUSY_TIMEOUT_MIN_MS,
@@ -220,7 +220,7 @@ var HINT_FLAG_SPEC = Object.freeze({
220
220
  });
221
221
  var DEFAULT_CI_TIMEOUT_MIN = 20;
222
222
  // package.json
223
- var version = "0.52.1";
223
+ var version = "0.54.0";
224
224
 
225
225
  // packages/rafa/src/core/command/version.ts
226
226
  var RAFA_VERSION = version;
@@ -296,6 +296,13 @@ function unquoteGitPath(raw) {
296
296
  }
297
297
  return new TextDecoder().decode(new Uint8Array(bytes));
298
298
  }
299
+ // packages/rafa/src/utils/shell.ts
300
+ var PLAIN_WORD = /^[A-Za-z0-9._:/-]+$/;
301
+ var QUOTE = "'";
302
+ var QUOTED_QUOTE = "'\\''";
303
+ function shellQuote(word) {
304
+ return PLAIN_WORD.test(word) ? word : QUOTE + word.split(QUOTE).join(QUOTED_QUOTE) + QUOTE;
305
+ }
299
306
  // packages/rafa/src/core/git/commit.ts
300
307
  import { spawnSync as spawnSync2 } from "child_process";
301
308
  var DEFAULT_COMMIT_TYPE = "chore";
@@ -667,4 +674,4 @@ function asHopRecord(value) {
667
674
  };
668
675
  }
669
676
 
670
- export { PORT_VERSIONS, createAdapterRegistry, registerAdapters, restoreAdapters, activeAdapterRegistry, CORE_ADAPTER_REGISTRY, CommandExit, commandSpelling, createLinePrompter, lazyPrompter, GLOBAL_FLAGS, runningCommand, HINT_FLAG, HINT_FLAG_SPEC, DEFAULT_CI_TIMEOUT_MIN, RAFA_VERSION, createGitRunner, gitSaid, parseWorkingTree, commitTaskWork, TRUSTED_PERMISSIONS, isRecord, asPlace, asHopRecord, PROJECT_ID_LENGTH, PROJECT_ID_PATTERN, normalizeRemote, gitRemoteUrl, setActiveStoreSettings, activeStoreSettings };
677
+ export { PORT_VERSIONS, createAdapterRegistry, registerAdapters, restoreAdapters, activeAdapterRegistry, CORE_ADAPTER_REGISTRY, CommandExit, commandSpelling, createLinePrompter, lazyPrompter, GLOBAL_FLAGS, runningCommand, HINT_FLAG, HINT_FLAG_SPEC, DEFAULT_CI_TIMEOUT_MIN, RAFA_VERSION, createGitRunner, gitSaid, parseWorkingTree, shellQuote, commitTaskWork, TRUSTED_PERMISSIONS, isRecord, asPlace, asHopRecord, PROJECT_ID_LENGTH, PROJECT_ID_PATTERN, normalizeRemote, gitRemoteUrl, setActiveStoreSettings, activeStoreSettings };
@@ -22,7 +22,7 @@ import {
22
22
  registerConfigSections,
23
23
  setConfigLoadHook,
24
24
  setConfigTemplateHook
25
- } from "./index-m672ptpg.js";
25
+ } from "./index-dj8en7fg.js";
26
26
  import {
27
27
  below,
28
28
  describeValue,
@@ -197,6 +197,27 @@ var CHECKS_SECTION = Object.freeze({
197
197
  defaults: CHECKS_DEFAULTS
198
198
  });
199
199
 
200
+ // packages/rafa/src/config-schema-collaborate.ts
201
+ var COLLABORATE_TOOLS = Object.freeze(["rafa"]);
202
+ var COLLABORATE_DEFAULTS = Object.freeze({
203
+ collaborateRafa: null
204
+ });
205
+ var REPOSITORY = /^[^/\s]+\/[^/\s]+$/u;
206
+ var REPOSITORY_EXPECTED = "a repository as owner/name, such as open-tomato/rafa";
207
+ var collaborateRepository = (raw, at) => typeof raw === "string" && REPOSITORY.test(raw) ? { value: raw, problems: [], extras: [] } : refused(at, raw, REPOSITORY_EXPECTED);
208
+ var COLLABORATE_SETTINGS = {
209
+ collaborateRafa: { key: "collaborate.rafa", read: collaborateRepository, cli: false }
210
+ };
211
+ var FIELD_OF = Object.freeze({
212
+ rafa: "collaborateRafa"
213
+ });
214
+ var COLLABORATE_SECTION = Object.freeze({
215
+ package: "collaborate",
216
+ settings: Object.freeze(COLLABORATE_SETTINGS),
217
+ defaults: COLLABORATE_DEFAULTS,
218
+ checks: Object.freeze([])
219
+ });
220
+
200
221
  // packages/rafa/src/config-schema-errors.ts
201
222
  var ERROR_CODE_KEYS = ["code", "description", "hint", "level", "since"];
202
223
  var KNOWN_KEYS = new Set(ERROR_CODE_KEYS);
@@ -278,6 +299,19 @@ var FEATURES_SECTION = Object.freeze({
278
299
  defaults: FEATURES_DEFAULTS
279
300
  });
280
301
 
302
+ // packages/rafa/src/config-schema-hints.ts
303
+ var HINTS_DEFAULTS = Object.freeze({
304
+ hintsSkills: false
305
+ });
306
+ var HINTS_SETTINGS = {
307
+ hintsSkills: { key: "hints.skills", read: flag, cli: false }
308
+ };
309
+ var HINTS_SECTION = Object.freeze({
310
+ package: "hints",
311
+ settings: Object.freeze(HINTS_SETTINGS),
312
+ defaults: HINTS_DEFAULTS
313
+ });
314
+
281
315
  // packages/rafa/src/config-schema-hub.ts
282
316
  var HUB_TIMEOUT_MIN_SECONDS = 1;
283
317
  var HUB_TIMEOUT_MAX_SECONDS = 30;
@@ -796,7 +830,9 @@ var CONFIG_SECTIONS = Object.freeze([
796
830
  ISSUES_SECTION,
797
831
  TESTS_SECTION,
798
832
  CHECKS_SECTION,
799
- FEATURES_SECTION
833
+ FEATURES_SECTION,
834
+ COLLABORATE_SECTION,
835
+ HINTS_SECTION
800
836
  ]);
801
837
  function handConfigToLogger(config) {
802
838
  setActiveLoggerSettings(loggerSettingsOf(config));
@@ -877,7 +913,9 @@ var CONFIG_DEFAULTS = Object.freeze({
877
913
  ...run(CORE_VALUES, CORE_TAIL),
878
914
  ...TESTS_DEFAULTS,
879
915
  ...CHECKS_DEFAULTS,
880
- ...FEATURES_DEFAULTS
916
+ ...FEATURES_DEFAULTS,
917
+ ...COLLABORATE_DEFAULTS,
918
+ ...HINTS_DEFAULTS
881
919
  });
882
920
  var SETTINGS = Object.freeze({
883
921
  ...run(CORE_SPECS, CORE_HEAD),
@@ -901,7 +939,9 @@ var SETTINGS = Object.freeze({
901
939
  ...run(CORE_SPECS, CORE_TAIL),
902
940
  ...TESTS_SETTINGS,
903
941
  ...CHECKS_SETTINGS,
904
- ...FEATURES_SETTINGS
942
+ ...FEATURES_SETTINGS,
943
+ ...COLLABORATE_SETTINGS,
944
+ ...HINTS_SETTINGS
905
945
  });
906
946
  var SETTING_NAMES = Object.freeze(Object.keys(SETTINGS));
907
947
  function inSettingOrder(sections, names) {
@@ -251,7 +251,7 @@ var CORE_DEFAULTS = Object.freeze({
251
251
  learningAdapter: "local",
252
252
  learningBlessMinConfidence: 0.5,
253
253
  learningPromoteAfter: 3,
254
- learningPromoteMinConfidence: 0.7,
254
+ learningPromoteMinConfidence: 0.6,
255
255
  outputMode: "text",
256
256
  prerequisitesRequired: Object.freeze([]),
257
257
  prerequisitesOptional: Object.freeze([]),