@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.
@@ -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;