@verevoir/aigency-work 0.0.0-stage → 0.2.1
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/CHANGELOG.md +85 -0
- package/LICENSE +201 -0
- package/README.md +23 -2
- package/dist/asf-board.d.ts +29 -0
- package/dist/asf-board.js +826 -0
- package/dist/board.d.ts +428 -0
- package/dist/board.js +6 -0
- package/dist/card.d.ts +94 -0
- package/dist/card.js +89 -0
- package/dist/in-memory-board.d.ts +16 -0
- package/dist/in-memory-board.js +160 -0
- package/dist/in-memory-store.d.ts +26 -0
- package/dist/in-memory-store.js +79 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.js +15 -0
- package/dist/move-card.d.ts +141 -0
- package/dist/move-card.js +104 -0
- package/dist/multiplexer.d.ts +55 -0
- package/dist/multiplexer.js +54 -0
- package/dist/notion-board.d.ts +47 -0
- package/dist/notion-board.js +733 -0
- package/dist/payload-board.d.ts +50 -0
- package/dist/payload-board.js +225 -0
- package/dist/payload.d.ts +55 -0
- package/dist/payload.js +151 -0
- package/dist/schema-change.d.ts +78 -0
- package/dist/schema-change.js +0 -0
- package/dist/store-board.d.ts +33 -0
- package/dist/store-board.js +426 -0
- package/dist/store.d.ts +105 -0
- package/dist/store.js +13 -0
- package/package.json +45 -4
package/dist/board.d.ts
ADDED
|
@@ -0,0 +1,428 @@
|
|
|
1
|
+
import type { Card, Problem, State } from './card.js';
|
|
2
|
+
/**
|
|
3
|
+
* Deliberately absent from this file: comment-writing.
|
|
4
|
+
*
|
|
5
|
+
* The documents describing this boundary disagree about whether comments
|
|
6
|
+
* belong in it. The prose names them: this repository's own README calls
|
|
7
|
+
* itself "the tracker boundary: cards, columns and comments", and
|
|
8
|
+
* `aigency-rebuild/design/architecture.md` repeats the same three nouns
|
|
9
|
+
* for this project (`work`). But `aigency-rebuild/recon/contracts.md` —
|
|
10
|
+
* the document that is supposed to be the authoritative port table —
|
|
11
|
+
* names the two ports for this boundary (`WorkflowCardSource` /
|
|
12
|
+
* `WorkflowRunSink`) and describes them only as "the work-tracker
|
|
13
|
+
* boundary — read half and write half", with no mention of a comment
|
|
14
|
+
* capability on either one.
|
|
15
|
+
*
|
|
16
|
+
* Building against the prose's reading commits this boundary to a shape
|
|
17
|
+
* the port table never sanctioned. Building against the port table's
|
|
18
|
+
* reading drops something the prose names explicitly. Building the wrong
|
|
19
|
+
* half of a disagreement like that is worse than building neither, so
|
|
20
|
+
* this file builds neither: no `Comment` type, no comment method on
|
|
21
|
+
* `CardSource` or `CardSink`. The gap is left open on purpose, and it
|
|
22
|
+
* should stay open until the two documents agree — settling it silently
|
|
23
|
+
* here, either way, would look like a decision that was never actually
|
|
24
|
+
* made.
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* The read half: getting one card by id, and listing what a board holds.
|
|
28
|
+
*
|
|
29
|
+
* `get`'s three outcomes are the point of this interface. `found` and
|
|
30
|
+
* `absent` are the two answers most callers expect; `unreachable` is the
|
|
31
|
+
* one that is easy to fold into `absent`, and must not be. A network
|
|
32
|
+
* failure and a deleted card are different facts, and a caller told only
|
|
33
|
+
* "not found" for both will treat a tracker outage as if every card on
|
|
34
|
+
* it had been deleted. `absent` and `unreachable` must never collapse
|
|
35
|
+
* into one another, whichever card id was asked for.
|
|
36
|
+
*/
|
|
37
|
+
export interface CardSource {
|
|
38
|
+
get(id: string): Promise<GetResult>;
|
|
39
|
+
/**
|
|
40
|
+
* Lists what a board holds.
|
|
41
|
+
*
|
|
42
|
+
* No board identifier is threaded through this call. `Card.source`
|
|
43
|
+
* names which tracker and adapter a card came from (see `card.ts`) —
|
|
44
|
+
* not which board within that tracker. If a single `CardSource` could
|
|
45
|
+
* answer for more than one board, cards from different boards it
|
|
46
|
+
* returned would carry the same `source` string and be
|
|
47
|
+
* indistinguishable downstream by the one field that is supposed to
|
|
48
|
+
* say where a card came from. So a `CardSource` is scoped to one board
|
|
49
|
+
* at construction — the same way a filesystem adapter is rooted to one
|
|
50
|
+
* tree rather than taking a root on every call — and `list()` means
|
|
51
|
+
* "what is on the board this source already points at", never "what
|
|
52
|
+
* is on board X".
|
|
53
|
+
*/
|
|
54
|
+
list(): Promise<ListResult>;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* One stored record that could not be read as a card — a payload the
|
|
58
|
+
* underlying tracker actually holds, kept exactly as it arrived, the way
|
|
59
|
+
* `Card.unknownFields` keeps whatever a `Card` has no slot for, except
|
|
60
|
+
* this one failed validation outright rather than being carried through.
|
|
61
|
+
*
|
|
62
|
+
* `id` is the key the source stored the record under — independent of
|
|
63
|
+
* whatever malformed or missing `id` sits inside the payload itself.
|
|
64
|
+
* Keying by the store's own identifier, not the payload's, is what keeps
|
|
65
|
+
* a broken record findable at all: a `CardSource` backed by raw payloads
|
|
66
|
+
* (see `payload-board.ts`) can encounter a payload with no readable id
|
|
67
|
+
* whatsoever, and it would be useless to report a problem under an
|
|
68
|
+
* identifier the report exists to explain is missing.
|
|
69
|
+
*
|
|
70
|
+
* `problems` is `parseCard`'s whole list, not one line picked from it —
|
|
71
|
+
* the same discipline `parseCard` itself applies (see `card.ts`): a
|
|
72
|
+
* caller fixing a live tracker record one field at a time deserves the
|
|
73
|
+
* complete picture, not a first problem that hides the second.
|
|
74
|
+
*/
|
|
75
|
+
export interface UnparseableRecord {
|
|
76
|
+
readonly id: string;
|
|
77
|
+
readonly problems: readonly Problem[];
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* `unparseable` is a fourth outcome, not a shade of `absent` or
|
|
81
|
+
* `unreachable` — because it is neither. `absent` means the tracker was
|
|
82
|
+
* asked and has nothing under that id. `unreachable` means the tracker
|
|
83
|
+
* was never asked at all. `unparseable` means something a source that
|
|
84
|
+
* stores validated `Card`s can never produce: the tracker was asked, it
|
|
85
|
+
* answered, and what it handed back does not parse as a card — a field
|
|
86
|
+
* renamed underneath this boundary, a schema changed by the tracker's
|
|
87
|
+
* own maintainers, entirely ordinary events for a system this boundary
|
|
88
|
+
* does not control. Folding that into `absent` would tell a caller a
|
|
89
|
+
* record was deleted when it is actually sitting there, broken. Folding
|
|
90
|
+
* it into `unreachable` would suggest retrying fixes it, when no retry
|
|
91
|
+
* changes what is already stored. Both would destroy the one thing a
|
|
92
|
+
* caller could act on: which record, and why it could not be read.
|
|
93
|
+
*/
|
|
94
|
+
export type GetResult = {
|
|
95
|
+
readonly outcome: 'found';
|
|
96
|
+
readonly card: Card;
|
|
97
|
+
} | {
|
|
98
|
+
readonly outcome: 'absent';
|
|
99
|
+
} | {
|
|
100
|
+
readonly outcome: 'unreachable';
|
|
101
|
+
readonly reason: string;
|
|
102
|
+
} | {
|
|
103
|
+
readonly outcome: 'unparseable';
|
|
104
|
+
readonly id: string;
|
|
105
|
+
readonly problems: readonly Problem[];
|
|
106
|
+
};
|
|
107
|
+
/**
|
|
108
|
+
* `empty` and `unreachable` are kept apart for the same reason `absent`
|
|
109
|
+
* and `unreachable` are on `get`: an empty board is a real, ordinary
|
|
110
|
+
* answer — a search that finds nothing must say what it searched, not
|
|
111
|
+
* report the same shape a broken connection would. A listing that
|
|
112
|
+
* cannot reach the tracker at all has found out nothing about the board,
|
|
113
|
+
* which is not the same fact as the board having nothing on it.
|
|
114
|
+
*/
|
|
115
|
+
/**
|
|
116
|
+
* `cards` carries an `unparseable` list alongside the good ones, rather
|
|
117
|
+
* than either extreme a listing over records that can individually fail
|
|
118
|
+
* to parse might otherwise reach. Refusing the whole listing because one
|
|
119
|
+
* record among ten is broken would lose nine good cards to one bad one —
|
|
120
|
+
* a single renamed field taking down every other card on the board.
|
|
121
|
+
* Silently dropping the broken record would be a lie by omission: a
|
|
122
|
+
* caller counting cards, or looking for one that used to be there, would
|
|
123
|
+
* see a smaller, quieter board than the tracker actually holds, with no
|
|
124
|
+
* sign anything was withheld. Neither loss is necessary — a source that
|
|
125
|
+
* knows exactly which records did not parse, and why, can say so and
|
|
126
|
+
* still hand over everything it could read. So `cards` reports both: the
|
|
127
|
+
* ones that parsed, and the ones that did not, each individually.
|
|
128
|
+
*
|
|
129
|
+
* `danglingIds` is a third, different kind of gap, alongside
|
|
130
|
+
* `unparseable` rather than folded into it. `unparseable` means a record
|
|
131
|
+
* exists and was read, but its content does not parse. `danglingIds`
|
|
132
|
+
* means a source that lists by consulting a separately-maintained index
|
|
133
|
+
* (see `store-board.ts`) found an id the index names with no record
|
|
134
|
+
* behind it at all — not broken content, no content. Conflating the two
|
|
135
|
+
* would describe a missing record as a malformed one, a different and
|
|
136
|
+
* misleading repair instruction. Silently dropping a dangling id would
|
|
137
|
+
* be the same lie by omission `unparseable` was created to rule out,
|
|
138
|
+
* applied to referential inconsistency instead of parse failure. A
|
|
139
|
+
* source with no such index — `InMemoryBoard`, `PayloadBoard` — always
|
|
140
|
+
* reports `danglingIds: []`, for the same reason they always report
|
|
141
|
+
* `unparseable: []` where they cannot produce it: the field exists
|
|
142
|
+
* because `ListResult` is shared with a source that can, not because
|
|
143
|
+
* every source can.
|
|
144
|
+
*
|
|
145
|
+
* `empty` still means what it always meant: nothing stored at all, not
|
|
146
|
+
* even a broken record. A board holding only unparseable records is not
|
|
147
|
+
* `empty` — it is `cards` with an empty `cards` array and a non-empty
|
|
148
|
+
* `unparseable` one, because the tracker did answer with something.
|
|
149
|
+
*/
|
|
150
|
+
export type ListResult = {
|
|
151
|
+
readonly outcome: 'cards';
|
|
152
|
+
readonly cards: readonly Card[];
|
|
153
|
+
readonly unparseable: readonly UnparseableRecord[];
|
|
154
|
+
readonly danglingIds: readonly string[];
|
|
155
|
+
} | {
|
|
156
|
+
readonly outcome: 'empty';
|
|
157
|
+
} | {
|
|
158
|
+
readonly outcome: 'unreachable';
|
|
159
|
+
readonly reason: string;
|
|
160
|
+
};
|
|
161
|
+
/**
|
|
162
|
+
* Options threading an optimistic-concurrency guard through a write.
|
|
163
|
+
* `expectedRevision` is compared against whatever the resolved board
|
|
164
|
+
* considers a card's current revision (see `Card.revision`); a
|
|
165
|
+
* mismatch is reported as the `stale` outcome, naming the id and the
|
|
166
|
+
* board's current revision when it knows it, never a throw. Omitting
|
|
167
|
+
* it is last-write-wins — the behaviour every board had before this
|
|
168
|
+
* option existed, so every caller that never supplies it is unaffected
|
|
169
|
+
* by the guard itself.
|
|
170
|
+
*
|
|
171
|
+
* A board with no compare-and-set primitive underneath it to make this
|
|
172
|
+
* guard genuine at all — see `payload-board.ts` — must not pretend to
|
|
173
|
+
* honour it with a counter nothing could ever really lose a race on.
|
|
174
|
+
* Such a board answers ANY write that supplies `expectedRevision` with
|
|
175
|
+
* the `unsupported` outcome (see `WriteResult` below), naming
|
|
176
|
+
* explicitly that the guard is not supported there, never a silent
|
|
177
|
+
* `applied`/`stale` that looks like a real check, and never the
|
|
178
|
+
* unrelated `refused`, which means something else entirely: a card was
|
|
179
|
+
* looked for and not found.
|
|
180
|
+
*/
|
|
181
|
+
export interface WriteOptions {
|
|
182
|
+
readonly expectedRevision?: string;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* The patch `CardSink.annotate` applies: a flat string-to-string bag
|
|
186
|
+
* merged into a card's own `properties`, never touching `state`. Used
|
|
187
|
+
* for facts about a card's history that are not a column — a block or
|
|
188
|
+
* retract reason, a recorded PR url.
|
|
189
|
+
*/
|
|
190
|
+
export interface AnnotatePatch {
|
|
191
|
+
readonly properties: Readonly<Record<string, string>>;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* The write half: changes a card's state, creates cards, and patches a
|
|
195
|
+
* card's properties. Nothing else about a card is writable through it.
|
|
196
|
+
*
|
|
197
|
+
* `refused` and `unreachable` are kept apart because they are different
|
|
198
|
+
* facts a caller needs to react to differently. `refused` means the
|
|
199
|
+
* tracker was reached, heard the request, and said no — a transition its
|
|
200
|
+
* workflow doesn't allow, a permission this credential doesn't have. The
|
|
201
|
+
* request is known to have failed.
|
|
202
|
+
*
|
|
203
|
+
* `refused` itself covers (at least) two distinct facts, told apart only
|
|
204
|
+
* by reading `reason`, not by a further variant: a board can refuse
|
|
205
|
+
* because the card simply does not exist (`writeState`/`annotate` on an
|
|
206
|
+
* id with no card behind it — see `createCard`'s own `applied`/`refused`
|
|
207
|
+
* doc for the symmetric "id already exists" case), or because the card
|
|
208
|
+
* exists but cannot be safely written to at all (`PayloadBoard`'s stored
|
|
209
|
+
* payload does not parse, or its `properties` is a tracker-shaped object
|
|
210
|
+
* `annotate` would overwrite — see `payload-board.ts`). Both are "no",
|
|
211
|
+
* for different reasons; a caller that only checks `outcome === 'refused'`
|
|
212
|
+
* cannot tell them apart and does not need to for most purposes, but a
|
|
213
|
+
* caller that does should read `reason`, not add a third outcome for a
|
|
214
|
+
* distinction this boundary has not needed to make load-bearing. `unreachable` means nobody knows what
|
|
215
|
+
* the tracker thinks, because the tracker was never asked — a timeout, a
|
|
216
|
+
* network failure, an outage. Retrying a `refused` write blindly repeats
|
|
217
|
+
* a request that was already answered; retrying an `unreachable` one is
|
|
218
|
+
* usually the right move. Collapsing the two into one "write failed"
|
|
219
|
+
* outcome would make that decision for every caller, always, and would
|
|
220
|
+
* get it wrong half the time.
|
|
221
|
+
*
|
|
222
|
+
* `contentionExhausted` is a fourth fact, distinct from both: a sink
|
|
223
|
+
* backed by a compare-and-set store (see `store-board.ts`) can be
|
|
224
|
+
* reached, again and again, and each time lose a race to a concurrent
|
|
225
|
+
* writer changing the same record, its own `expectedRevision` guard (if
|
|
226
|
+
* any) matching every time it checked — never told no outright the way
|
|
227
|
+
* `refused` means, and never unable to reach the tracker at all the way
|
|
228
|
+
* `unreachable` means. It was first reported as `refused`, carrying a
|
|
229
|
+
* distinguishing string prefix in `reason` that was checkable only by
|
|
230
|
+
* convention — exactly the collapse this boundary refuses everywhere
|
|
231
|
+
* else it has two different facts to report. This variant is the fix: a
|
|
232
|
+
* caller can switch on `outcome` and get a compile error if it forgets
|
|
233
|
+
* this case, rather than trusting every caller to read `reason`
|
|
234
|
+
* correctly. The remedy is to back off and retry the same request —
|
|
235
|
+
* nothing about the request was wrong, the record was just too hot.
|
|
236
|
+
*
|
|
237
|
+
* `stale` is a fifth, different fact: the board compared a caller-
|
|
238
|
+
* supplied `expectedRevision` against its own and found they disagreed
|
|
239
|
+
* — the board was reached and made a real decision, but the decision
|
|
240
|
+
* was "you are holding an old revision", not "I kept losing a race".
|
|
241
|
+
* The remedy is the opposite of `contentionExhausted`'s: re-read the
|
|
242
|
+
* card and decide again, because retrying the exact same stale
|
|
243
|
+
* `expectedRevision` will never succeed no matter how many times it is
|
|
244
|
+
* tried. Before this variant existed, a stale guess and an exhausted
|
|
245
|
+
* retry loop were both reported as `contentionExhausted`,
|
|
246
|
+
* distinguishable only by reading `reason` as a string — exactly the
|
|
247
|
+
* problem `contentionExhausted` itself was introduced to solve for
|
|
248
|
+
* `refused`, recurring one level up.
|
|
249
|
+
*
|
|
250
|
+
* `unsupported` is a sixth fact, orthogonal to all of the above: the
|
|
251
|
+
* board was reached and understood the request, but has no way to
|
|
252
|
+
* honour the `expectedRevision` guard at all — no compare-and-set
|
|
253
|
+
* primitive underneath it that could ever make the guard genuine (see
|
|
254
|
+
* `payload-board.ts`). It means "don't retry here": retrying the same
|
|
255
|
+
* guarded write against the same board only ever gets `unsupported`
|
|
256
|
+
* again, no matter what revision is supplied. The remedy is to use a
|
|
257
|
+
* board that actually supports the guard, or to drop the guard
|
|
258
|
+
* deliberately and accept last-write-wins. Collapsing this into
|
|
259
|
+
* `refused` would make it indistinguishable from any other refusal
|
|
260
|
+
* except by reading `reason` as a string — exactly the collapse every
|
|
261
|
+
* other variant here exists to avoid.
|
|
262
|
+
*/
|
|
263
|
+
export interface CardSink {
|
|
264
|
+
writeState(id: string, state: State, options?: WriteOptions): Promise<WriteResult>;
|
|
265
|
+
/**
|
|
266
|
+
* Creates a card that does not yet exist.
|
|
267
|
+
*
|
|
268
|
+
* `applied` means the card now exists and `get(card.id)` returns it.
|
|
269
|
+
* An id that is already taken is `refused`, with a reason naming the
|
|
270
|
+
* id, never a throw and never an overwrite. That keeps `refused` (the
|
|
271
|
+
* tracker was reached and said no) distinct from `unreachable` (nobody
|
|
272
|
+
* could find out). `unreachable` and `contentionExhausted` keep the
|
|
273
|
+
* meanings documented above.
|
|
274
|
+
*/
|
|
275
|
+
createCard(card: Card): Promise<WriteResult>;
|
|
276
|
+
/**
|
|
277
|
+
* Patches a card's `properties` without touching `state` — a block
|
|
278
|
+
* or retract reason, a recorded PR url, anything that is a fact
|
|
279
|
+
* about the card rather than its column. `applied` means the patch
|
|
280
|
+
* landed; an id with no card behind it is `refused`, naming the id,
|
|
281
|
+
* never a throw. A board that genuinely cannot annotate (nothing to
|
|
282
|
+
* patch, no concept of extra properties) returns a named `refused`
|
|
283
|
+
* saying so explicitly, rather than silently doing nothing or
|
|
284
|
+
* throwing. `expectedRevision` is honoured exactly as `writeState`
|
|
285
|
+
* honours it.
|
|
286
|
+
*/
|
|
287
|
+
annotate(id: string, patch: AnnotatePatch, options?: WriteOptions): Promise<WriteResult>;
|
|
288
|
+
}
|
|
289
|
+
export type WriteResult = {
|
|
290
|
+
readonly outcome: 'applied';
|
|
291
|
+
} | {
|
|
292
|
+
readonly outcome: 'refused';
|
|
293
|
+
readonly reason: string;
|
|
294
|
+
} | {
|
|
295
|
+
readonly outcome: 'unreachable';
|
|
296
|
+
readonly reason: string;
|
|
297
|
+
} | {
|
|
298
|
+
readonly outcome: 'contentionExhausted';
|
|
299
|
+
readonly reason: string;
|
|
300
|
+
} | {
|
|
301
|
+
readonly outcome: 'stale';
|
|
302
|
+
readonly id: string;
|
|
303
|
+
readonly reason: string;
|
|
304
|
+
readonly currentRevision?: string;
|
|
305
|
+
} | {
|
|
306
|
+
readonly outcome: 'unsupported';
|
|
307
|
+
readonly id: string;
|
|
308
|
+
readonly reason: string;
|
|
309
|
+
};
|
|
310
|
+
/**
|
|
311
|
+
* A queue claim ({@link CardClaimer.claimNext}) or a nominate claim
|
|
312
|
+
* ({@link CardClaimer.claim}) succeeded: the tracker minted a run and moved
|
|
313
|
+
* the task's card, in one transaction. `runId` is the tracker's own opaque
|
|
314
|
+
* run id -- pass it back to {@link CardClaimer.completeRun} to close it.
|
|
315
|
+
*
|
|
316
|
+
* TWO DIFFERENT "claimed" SHAPES, not one. `card` is mapped exactly as a
|
|
317
|
+
* `CardSource` read maps the same task -- WHEN that read-back succeeded.
|
|
318
|
+
* When the claim itself landed (ASF minted the run, moved the card) but the
|
|
319
|
+
* follow-up read of the claimed task failed or would not parse, this is
|
|
320
|
+
* reported as `card: undefined` with `cardReadFailed` naming why, never as
|
|
321
|
+
* a fabricated card standing in for one that was never actually read. A
|
|
322
|
+
* caller that destructures `card` as always-present must handle this case
|
|
323
|
+
* explicitly; there is no silent substitute to miss it on.
|
|
324
|
+
*
|
|
325
|
+
* `claimed-unverified` is a THIRD, distinct outcome from `claimed`: the
|
|
326
|
+
* claim's own `201` response body did not parse as a `Run` at all. ASF has
|
|
327
|
+
* ALREADY COMMITTED the claim by the time this is reported -- the run was
|
|
328
|
+
* minted and the card moved on ASF's side -- so this is never collapsed
|
|
329
|
+
* into `unreachable`, which would read as "nothing happened" and invite a
|
|
330
|
+
* caller to retry, claiming a second task for work ASF already assigned.
|
|
331
|
+
* `runId` is present only if SOME id could still be read loosely out of the
|
|
332
|
+
* unparseable body; `reason` always explains what failed. DO NOT RETRY a
|
|
333
|
+
* `claimed-unverified` result: reconcile (re-read the task, or list runs)
|
|
334
|
+
* instead.
|
|
335
|
+
*
|
|
336
|
+
* `none` is ASF's own two "nothing claimed" answers (an empty board; a
|
|
337
|
+
* board with ready work that is all spoken for) collapsed into one: this
|
|
338
|
+
* boundary has nothing distinct to do with either -- a caller here only
|
|
339
|
+
* ever needs "nothing was claimed, try again later".
|
|
340
|
+
*/
|
|
341
|
+
export type ClaimResult = {
|
|
342
|
+
readonly outcome: 'claimed';
|
|
343
|
+
readonly card: Card;
|
|
344
|
+
readonly runId: string;
|
|
345
|
+
} | {
|
|
346
|
+
readonly outcome: 'claimed';
|
|
347
|
+
readonly card: undefined;
|
|
348
|
+
readonly runId: string;
|
|
349
|
+
readonly cardReadFailed: {
|
|
350
|
+
readonly reason: string;
|
|
351
|
+
};
|
|
352
|
+
} | {
|
|
353
|
+
readonly outcome: 'claimed-unverified';
|
|
354
|
+
readonly runId?: string;
|
|
355
|
+
readonly reason: string;
|
|
356
|
+
} | {
|
|
357
|
+
readonly outcome: 'none';
|
|
358
|
+
} | {
|
|
359
|
+
readonly outcome: 'unreachable';
|
|
360
|
+
readonly reason: string;
|
|
361
|
+
} | {
|
|
362
|
+
readonly outcome: 'refused';
|
|
363
|
+
readonly reason: string;
|
|
364
|
+
};
|
|
365
|
+
/**
|
|
366
|
+
* A nominate claim's conflict taxonomy is richer than the queue claim's: a
|
|
367
|
+
* SPECIFIC task was named, and the tracker refused to claim it for one of a
|
|
368
|
+
* closed set of named reasons rather than silently passing it over. `reason`
|
|
369
|
+
* carries that name verbatim -- for ASF: `alreadyClaimed` | `diverged` |
|
|
370
|
+
* `faulted` | `requested` | `unbound`.
|
|
371
|
+
*
|
|
372
|
+
* The `claimed` (including its `card: undefined`/`cardReadFailed` shape)
|
|
373
|
+
* and `claimed-unverified` variants carry exactly the same meaning, for
|
|
374
|
+
* exactly the same reason, as {@link ClaimResult}'s own -- see that type's
|
|
375
|
+
* doc. In short: `claimed-unverified` and a `cardReadFailed` claim both mean
|
|
376
|
+
* the claim already happened on ASF's side; never retry either blindly.
|
|
377
|
+
*/
|
|
378
|
+
export type NominateClaimResult = {
|
|
379
|
+
readonly outcome: 'claimed';
|
|
380
|
+
readonly card: Card;
|
|
381
|
+
readonly runId: string;
|
|
382
|
+
} | {
|
|
383
|
+
readonly outcome: 'claimed';
|
|
384
|
+
readonly card: undefined;
|
|
385
|
+
readonly runId: string;
|
|
386
|
+
readonly cardReadFailed: {
|
|
387
|
+
readonly reason: string;
|
|
388
|
+
};
|
|
389
|
+
} | {
|
|
390
|
+
readonly outcome: 'claimed-unverified';
|
|
391
|
+
readonly runId?: string;
|
|
392
|
+
readonly reason: string;
|
|
393
|
+
} | {
|
|
394
|
+
readonly outcome: 'conflict';
|
|
395
|
+
readonly reason: string;
|
|
396
|
+
} | {
|
|
397
|
+
readonly outcome: 'refused';
|
|
398
|
+
readonly reason: string;
|
|
399
|
+
} | {
|
|
400
|
+
readonly outcome: 'unreachable';
|
|
401
|
+
readonly reason: string;
|
|
402
|
+
};
|
|
403
|
+
export type RunOutcome = 'completed' | 'failed';
|
|
404
|
+
export interface CompletionOptions {
|
|
405
|
+
readonly outcome: RunOutcome;
|
|
406
|
+
/** Only meaningful for `outcome: 'failed'` -- the tracker stores it as
|
|
407
|
+
* the card's failure marker. Never sent for `'completed'`. */
|
|
408
|
+
readonly reason?: string;
|
|
409
|
+
}
|
|
410
|
+
export type CompletionResult = {
|
|
411
|
+
readonly outcome: 'applied';
|
|
412
|
+
} | {
|
|
413
|
+
readonly outcome: 'refused';
|
|
414
|
+
readonly reason: string;
|
|
415
|
+
} | {
|
|
416
|
+
readonly outcome: 'unreachable';
|
|
417
|
+
readonly reason: string;
|
|
418
|
+
};
|
|
419
|
+
export interface CardClaimer {
|
|
420
|
+
/** The QUEUE claim: the tracker picks any ready task nothing else holds,
|
|
421
|
+
* atomically, mints a run, and moves the card. */
|
|
422
|
+
claimNext(): Promise<ClaimResult>;
|
|
423
|
+
/** The NOMINATE claim: claims the one named task, or answers `conflict`
|
|
424
|
+
* naming the tracker's own reason. */
|
|
425
|
+
claim(id: string): Promise<NominateClaimResult>;
|
|
426
|
+
/** Closes a run this claimer minted, as completed or failed. */
|
|
427
|
+
completeRun(runId: string, options: CompletionOptions): Promise<CompletionResult>;
|
|
428
|
+
}
|
package/dist/board.js
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
// The two halves of the tracker boundary: something that reads cards from
|
|
2
|
+
// a tracker, and something that writes back. Neither type here reaches
|
|
3
|
+
// into a specific tracker's SDK — that is `sources`' job and a concrete
|
|
4
|
+
// adapter's job, not this file's. This is the shape both halves share,
|
|
5
|
+
// whatever backs them.
|
|
6
|
+
export {};
|
package/dist/card.d.ts
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `state` is deliberately not a union, and it must not become one.
|
|
3
|
+
*
|
|
4
|
+
* A column means something different in every tracker this boundary
|
|
5
|
+
* fronts: one unordered list of lists in Trello, two separate axes in
|
|
6
|
+
* Backlog, whichever property a given Notion board happened to be
|
|
7
|
+
* configured with, possibly nothing at all in Obsidian. There is no closed
|
|
8
|
+
* set of states true of all of them — and this boundary owns no state of
|
|
9
|
+
* its own; the tracker does (see README). A union here would be a guess at
|
|
10
|
+
* a taxonomy that does not exist, dressed up as a type that looks checked.
|
|
11
|
+
* Leave it a string.
|
|
12
|
+
*/
|
|
13
|
+
export type State = string;
|
|
14
|
+
export interface Card {
|
|
15
|
+
readonly id: string;
|
|
16
|
+
readonly state: State;
|
|
17
|
+
readonly reference: string;
|
|
18
|
+
readonly source: string;
|
|
19
|
+
/**
|
|
20
|
+
* Required as a field, but explicitly *not* required to be non-empty.
|
|
21
|
+
* A newly created card legitimately has nothing extra to carry yet —
|
|
22
|
+
* that is not an inconsistency with `id`/`reference`/`source` being
|
|
23
|
+
* required and non-empty below, even though it looks like one at first
|
|
24
|
+
* glance. Those three are identity: an empty one is a missing one
|
|
25
|
+
* wearing a costume. This one is a bag for whatever a specific adapter
|
|
26
|
+
* needs beyond the common shape, and an empty bag is a legitimate state
|
|
27
|
+
* for that bag to be in.
|
|
28
|
+
*/
|
|
29
|
+
readonly unknownFields: Readonly<Record<string, unknown>>;
|
|
30
|
+
/**
|
|
31
|
+
* An opaque token a board bumps every time it accepts a write to this
|
|
32
|
+
* card. Pass it back as `WriteOptions.expectedRevision` (see
|
|
33
|
+
* `board.ts`) to make a write conditional on nothing else having
|
|
34
|
+
* changed the card first — a revision mismatch is reported as the
|
|
35
|
+
* `stale` outcome (see `board.ts`'s `WriteResult` doc: re-read and
|
|
36
|
+
* decide again, never `contentionExhausted`, which means something
|
|
37
|
+
* else — the board's own compare-and-set retry budget ran out), and
|
|
38
|
+
* never a throw. Opaque means
|
|
39
|
+
* exactly that: send it back verbatim, never parse it, never compare
|
|
40
|
+
* it to anything but another revision string for equality. A board's
|
|
41
|
+
* revision scheme is private to that board — two boards' revisions are
|
|
42
|
+
* not comparable to each other, and nothing here assumes they are.
|
|
43
|
+
* Optional because not every board tracks one; a `Card` from a board
|
|
44
|
+
* that doesn't carries no opinion about it at all, rather than a
|
|
45
|
+
* placeholder value pretending to be real.
|
|
46
|
+
*/
|
|
47
|
+
readonly revision?: string;
|
|
48
|
+
/**
|
|
49
|
+
* A flat string-to-string bag a board can patch without touching
|
|
50
|
+
* `state` — a block or retract reason, a recorded PR url, anything
|
|
51
|
+
* that is a fact about the card rather than its column (see
|
|
52
|
+
* `CardSink.annotate`). Distinct from `unknownFields`: `unknownFields`
|
|
53
|
+
* is whatever a specific adapter cannot map into this shape at all;
|
|
54
|
+
* `properties` is this boundary's own surface, explicitly annotatable
|
|
55
|
+
* through the shared contract rather than left to each adapter's own
|
|
56
|
+
* extension fields.
|
|
57
|
+
*/
|
|
58
|
+
readonly properties?: Readonly<Record<string, string>>;
|
|
59
|
+
}
|
|
60
|
+
export interface Problem {
|
|
61
|
+
readonly field: string;
|
|
62
|
+
readonly message: string;
|
|
63
|
+
}
|
|
64
|
+
export type ParseResult = {
|
|
65
|
+
readonly ok: true;
|
|
66
|
+
readonly card: Card;
|
|
67
|
+
} | {
|
|
68
|
+
readonly ok: false;
|
|
69
|
+
readonly problems: readonly Problem[];
|
|
70
|
+
};
|
|
71
|
+
/**
|
|
72
|
+
* `Card.properties`'s own contract is a flat string-to-string bag (see
|
|
73
|
+
* its doc above) — this is the one check that decides whether a given
|
|
74
|
+
* value actually is one. Exported because `payload.ts` needs the exact
|
|
75
|
+
* same decision to decide whether a payload's `properties` key is this
|
|
76
|
+
* boundary's own known field at all, or merely shares its name (a
|
|
77
|
+
* Notion page's nested `{select: {...}}` shape, for instance) and
|
|
78
|
+
* belongs in `unknownFields` instead of being cast into a shape it does
|
|
79
|
+
* not have.
|
|
80
|
+
*/
|
|
81
|
+
export declare function isStringRecord(value: unknown): value is Record<string, string>;
|
|
82
|
+
/**
|
|
83
|
+
* Parses an untrusted shape into a `Card`, or refuses it.
|
|
84
|
+
*
|
|
85
|
+
* The refusal names every problem it can find, not the first one. A caller
|
|
86
|
+
* fixing one field at a time, told about only the first problem on each
|
|
87
|
+
* attempt, is a failure this repository has already decided against
|
|
88
|
+
* elsewhere: `inMemoryLog`'s append refuses a caller-supplied sequence
|
|
89
|
+
* outright rather than validating it late, on the reasoning that a check
|
|
90
|
+
* applied after the fact is a worse check than one that cannot be
|
|
91
|
+
* bypassed. Here the equivalent discipline is: check every field, every
|
|
92
|
+
* time, and report the whole list, not the first entry in it.
|
|
93
|
+
*/
|
|
94
|
+
export declare function parseCard(shape: unknown): ParseResult;
|
package/dist/card.js
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
// Card: the shape common across trackers, and it decides as little as
|
|
2
|
+
// possible on purpose. Anything a specific tracker needs beyond this is
|
|
3
|
+
// carried in `unknownFields`, not added here.
|
|
4
|
+
function isPlainObject(value) {
|
|
5
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
6
|
+
}
|
|
7
|
+
function isNonEmptyString(value) {
|
|
8
|
+
return typeof value === 'string' && value.length > 0;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* `Card.properties`'s own contract is a flat string-to-string bag (see
|
|
12
|
+
* its doc above) — this is the one check that decides whether a given
|
|
13
|
+
* value actually is one. Exported because `payload.ts` needs the exact
|
|
14
|
+
* same decision to decide whether a payload's `properties` key is this
|
|
15
|
+
* boundary's own known field at all, or merely shares its name (a
|
|
16
|
+
* Notion page's nested `{select: {...}}` shape, for instance) and
|
|
17
|
+
* belongs in `unknownFields` instead of being cast into a shape it does
|
|
18
|
+
* not have.
|
|
19
|
+
*/
|
|
20
|
+
export function isStringRecord(value) {
|
|
21
|
+
return isPlainObject(value) && Object.values(value).every((entry) => typeof entry === 'string');
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Parses an untrusted shape into a `Card`, or refuses it.
|
|
25
|
+
*
|
|
26
|
+
* The refusal names every problem it can find, not the first one. A caller
|
|
27
|
+
* fixing one field at a time, told about only the first problem on each
|
|
28
|
+
* attempt, is a failure this repository has already decided against
|
|
29
|
+
* elsewhere: `inMemoryLog`'s append refuses a caller-supplied sequence
|
|
30
|
+
* outright rather than validating it late, on the reasoning that a check
|
|
31
|
+
* applied after the fact is a worse check than one that cannot be
|
|
32
|
+
* bypassed. Here the equivalent discipline is: check every field, every
|
|
33
|
+
* time, and report the whole list, not the first entry in it.
|
|
34
|
+
*/
|
|
35
|
+
export function parseCard(shape) {
|
|
36
|
+
const problems = [];
|
|
37
|
+
const candidate = isPlainObject(shape) ? shape : {};
|
|
38
|
+
if (!isPlainObject(shape)) {
|
|
39
|
+
problems.push({ field: 'shape', message: 'must be an object' });
|
|
40
|
+
}
|
|
41
|
+
if (!isNonEmptyString(candidate.id)) {
|
|
42
|
+
problems.push({ field: 'id', message: 'id is required and must be a non-empty string' });
|
|
43
|
+
}
|
|
44
|
+
if (typeof candidate.state !== 'string') {
|
|
45
|
+
problems.push({ field: 'state', message: 'state is required and must be a string' });
|
|
46
|
+
}
|
|
47
|
+
if (!isNonEmptyString(candidate.reference)) {
|
|
48
|
+
problems.push({
|
|
49
|
+
field: 'reference',
|
|
50
|
+
message: 'reference is required and must be a non-empty string',
|
|
51
|
+
});
|
|
52
|
+
}
|
|
53
|
+
if (!isNonEmptyString(candidate.source)) {
|
|
54
|
+
problems.push({
|
|
55
|
+
field: 'source',
|
|
56
|
+
message: 'source is required and must be a non-empty string',
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
if (!isPlainObject(candidate.unknownFields)) {
|
|
60
|
+
problems.push({
|
|
61
|
+
field: 'unknownFields',
|
|
62
|
+
message: 'unknownFields is required and must be an object (an empty one is fine)',
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
if (candidate.revision !== undefined && typeof candidate.revision !== 'string') {
|
|
66
|
+
problems.push({ field: 'revision', message: 'revision must be a string when present' });
|
|
67
|
+
}
|
|
68
|
+
if (candidate.properties !== undefined && !isStringRecord(candidate.properties)) {
|
|
69
|
+
problems.push({
|
|
70
|
+
field: 'properties',
|
|
71
|
+
message: 'properties must be an object with only string values when present',
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
if (problems.length > 0) {
|
|
75
|
+
return { ok: false, problems };
|
|
76
|
+
}
|
|
77
|
+
return {
|
|
78
|
+
ok: true,
|
|
79
|
+
card: {
|
|
80
|
+
id: candidate.id,
|
|
81
|
+
state: candidate.state,
|
|
82
|
+
reference: candidate.reference,
|
|
83
|
+
source: candidate.source,
|
|
84
|
+
unknownFields: candidate.unknownFields,
|
|
85
|
+
...(typeof candidate.revision === 'string' ? { revision: candidate.revision } : {}),
|
|
86
|
+
...(isStringRecord(candidate.properties) ? { properties: candidate.properties } : {}),
|
|
87
|
+
},
|
|
88
|
+
};
|
|
89
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { Card } from './card.js';
|
|
2
|
+
import type { CardSource, CardSink } from './board.js';
|
|
3
|
+
export interface InMemoryBoard extends CardSource, CardSink {
|
|
4
|
+
/**
|
|
5
|
+
* Makes every subsequent `get`, `list`, `writeState`, `createCard` and
|
|
6
|
+
* `annotate` call report `unreachable` with this reason, regardless of
|
|
7
|
+
* what the board actually holds — reachability is checked
|
|
8
|
+
* independently of content, never inferred from it.
|
|
9
|
+
*/
|
|
10
|
+
setUnreachable(reason: string): void;
|
|
11
|
+
/** Undoes `setUnreachable`. */
|
|
12
|
+
setReachable(): void;
|
|
13
|
+
/** Puts a card directly into the fake board, for setting up a scenario. */
|
|
14
|
+
put(card: Card): void;
|
|
15
|
+
}
|
|
16
|
+
export declare function createInMemoryBoard(initial?: readonly Card[]): InMemoryBoard;
|