@verevoir/aigency-work 0.2.1 → 0.3.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/CHANGELOG.md +114 -0
- package/dist/asf-board.js +112 -39
- package/dist/backlog-board.d.ts +21 -0
- package/dist/backlog-board.js +383 -0
- package/dist/card.d.ts +61 -17
- package/dist/card.js +38 -8
- package/dist/in-memory-board.d.ts +13 -1
- package/dist/in-memory-board.js +17 -2
- package/dist/index.d.ts +8 -2
- package/dist/index.js +4 -1
- package/dist/notion-board.d.ts +33 -0
- package/dist/notion-board.js +515 -4
- package/dist/status.d.ts +24 -0
- package/dist/status.js +36 -0
- package/dist/trello-board.d.ts +41 -0
- package/dist/trello-board.js +337 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,120 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.3.0] - 2026-11-05
|
|
9
|
+
|
|
10
|
+
0.2.2 was never published to npm (the latest published version is 0.2.1), so
|
|
11
|
+
0.3.0 is the first release to carry the 0.2.2 changes below.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- `Card` gains optional fields (`src/card.ts`): `title` (string), `body`
|
|
16
|
+
(Markdown string), `requires` (array of prerequisite card ids in the
|
|
17
|
+
board's own id space), `parent` (a card id) and `status`. `parseCard`
|
|
18
|
+
validates each when present and refuses a wrong type by name.
|
|
19
|
+
- A normalized `Status` vocabulary (`backlog`, `ready`, `in-progress`,
|
|
20
|
+
`in-review`, `blocked`, `done`, `retracted`) with `StatusMap` and the
|
|
21
|
+
`normalizeStatus` / `nativeStateFor` helpers, exported from the package
|
|
22
|
+
entry. A board derives `Card.status` from its native `state` through a map
|
|
23
|
+
it owns; `state` stays the native name and `status` is never stored. A
|
|
24
|
+
state with no mapping leaves `status` absent. The in-memory board accepts
|
|
25
|
+
an optional status map.
|
|
26
|
+
- The BACKLOG.md board (`createBacklogBoard`, `BACKLOG_STATUS_MAP`,
|
|
27
|
+
`BacklogBoardOptions`): a `CardSource`/`CardSink` over a BACKLOG.md-style
|
|
28
|
+
markdown file, with all IO injected as `read`/`write`.
|
|
29
|
+
- Reads: the marker (` `, `~`, `x`, `!`, `R`) is the `state`; entries
|
|
30
|
+
map to `title`, `body`, `requires` (the `requires:` line plus any id
|
|
31
|
+
after "Blocked on" in the entry's text), `parent`, and a `retracted`
|
|
32
|
+
property for `[R]` entries. `list()` also reports `danglingIds`: ids
|
|
33
|
+
that are required but match no card (an `archived` option supplies ids
|
|
34
|
+
kept elsewhere).
|
|
35
|
+
- Nothing is dropped silently: an unknown marker, missing id, blank
|
|
36
|
+
title, malformed `requires:`/`parent:`/`retracted:` line, an `[R]` with
|
|
37
|
+
no reason, a duplicated id, or an indented line attached to no card is
|
|
38
|
+
reported in `unparseable`.
|
|
39
|
+
- Writes: `writeState` changes only the marker character, and refuses a
|
|
40
|
+
move into or out of `R`. `expectedRevision` is `unsupported`;
|
|
41
|
+
`createCard` and `annotate` are `unsupported` for now.
|
|
42
|
+
- The Notion board now carries the new `Card` fields: `title`, `body`,
|
|
43
|
+
`requires`, `parent` and a normalized `status` (`NOTION_DEFAULT_STATUS_MAP`
|
|
44
|
+
is exported).
|
|
45
|
+
- `get` renders the page's blocks to Markdown as `body` (paragraphs,
|
|
46
|
+
headings, lists, to-dos, quotes, code, dividers, nested children to a
|
|
47
|
+
depth limit). Blocks it cannot render, or children cut off at the depth
|
|
48
|
+
limit, are counted in `unknownFields.body`; a failed or malformed
|
|
49
|
+
block fetch fails the `get` rather than returning a shorter body.
|
|
50
|
+
`list` does not fetch bodies.
|
|
51
|
+
- Properties Notion truncates at 25 items (relation, title, rich text,
|
|
52
|
+
people) are paged in full; one that cannot be paged is named in
|
|
53
|
+
`unknownFields.propertiesIncomplete`.
|
|
54
|
+
- A configured title, requires or parent property that is missing from a
|
|
55
|
+
page, or of the wrong type, makes the page `unparseable`.
|
|
56
|
+
- A `unique_id` property is flattened into a string property
|
|
57
|
+
(`PREFIX-N`, or just the number when there is no prefix).
|
|
58
|
+
- The Trello board (`createTrelloBoard`, `TrelloBoard`, `TrelloBoardConfig`
|
|
59
|
+
and the `TrelloFetch*` types): a `CardSource`/`CardSink` over one Trello
|
|
60
|
+
board through Trello's REST API with raw `fetch` and no new dependency.
|
|
61
|
+
- A Trello list name is the card's `state`; `statusMap` optionally maps
|
|
62
|
+
list names to `status`, and `writeState` also accepts a normalized
|
|
63
|
+
status and resolves it back to a list name. A card in a list not on the
|
|
64
|
+
board is `unparseable`.
|
|
65
|
+
- Credentials come only from the injected `getAuth`, are asked for on
|
|
66
|
+
every call, and never appear in any outcome or reason.
|
|
67
|
+
- Trello is flat, so `requires` and `parent` are not set (each card
|
|
68
|
+
names them in `unknownFields.unsupported`). `createCard` and `annotate`
|
|
69
|
+
are `refused`, and `expectedRevision` is `unsupported`.
|
|
70
|
+
|
|
71
|
+
## [0.2.2] - 2026-11-01
|
|
72
|
+
|
|
73
|
+
Not published to npm; first released in 0.3.0.
|
|
74
|
+
|
|
75
|
+
### Fixed
|
|
76
|
+
|
|
77
|
+
- `asfBoard`'s raw-task to `Card` mapping no longer drops or misroutes
|
|
78
|
+
custom properties. Before 0.2.2, a task whose `ticket` or `builtBy` was
|
|
79
|
+
not a string, or whose `requires` was neither a string nor an array of
|
|
80
|
+
strings (for example a number), failed validation: it was reported
|
|
81
|
+
under `unparseable` with the failing field named, and left out of
|
|
82
|
+
`cards`, never silently dropped. A task that did validate had only its
|
|
83
|
+
string-valued properties copied into `Card.properties`; every
|
|
84
|
+
non-string value, including an array-valued `requires`, numbers,
|
|
85
|
+
booleans and objects, went to `Card.unknownFields` instead. From 0.2.2,
|
|
86
|
+
JSON-safe values are carried in `Card.properties` as they are.
|
|
87
|
+
- Exercised explicitly: a task whose `properties` field itself is not a
|
|
88
|
+
plain object is reported as `unparseable` by both `list()` and
|
|
89
|
+
`get()`, never silently dropped and never reported `absent`/missing —
|
|
90
|
+
this was already this file's behaviour for other schema violations,
|
|
91
|
+
now also proven for the properties shape itself.
|
|
92
|
+
- `asfBoard.createCard`'s write-path property reads now share one rule:
|
|
93
|
+
write paths refuse a present-but-wrong-type property by name instead
|
|
94
|
+
of replacing or forwarding it. In 0.2.1, `createCard` forwarded only
|
|
95
|
+
string-valued properties: non-string values never reached the write.
|
|
96
|
+
An absent or non-string `title` or `ticket` fell back to `card.id`;
|
|
97
|
+
a non-string `subtype` was written as `'task'`, and a non-string
|
|
98
|
+
`body` was omitted. Now that `Card.properties` carries JSON-safe
|
|
99
|
+
values (this release), `createCard` checks `title`, `ticket`,
|
|
100
|
+
`subtype` and `body` through one helper: a value that is present but
|
|
101
|
+
not a string is refused by name and nothing is sent; an absent value
|
|
102
|
+
keeps the previous fallback.
|
|
103
|
+
|
|
104
|
+
### Changed
|
|
105
|
+
|
|
106
|
+
- `Card.properties` (`src/card.ts`) is now typed
|
|
107
|
+
`Readonly<Record<string, PropertyValue>>` — `PropertyValue` being any
|
|
108
|
+
JSON-safe value (string, number, boolean, `null`, or an array/object
|
|
109
|
+
of those) — widened from `Readonly<Record<string, string>>`. This is
|
|
110
|
+
additive for every existing producer: a flat string record is still a
|
|
111
|
+
valid `PropertyValue` record. `parseCard`'s own validation, and so
|
|
112
|
+
every payload-sourced board (the in-memory/store/payload fixtures), is
|
|
113
|
+
UNCHANGED — it still only accepts a flat string-to-string bag on the
|
|
114
|
+
way in from an untrusted payload; only a board that builds a `Card`
|
|
115
|
+
directly from its own already-typed read (`asfBoard`) populates this
|
|
116
|
+
field with anything wider.
|
|
117
|
+
- `NotionBoard.createCard` now explicitly refuses, by name, a
|
|
118
|
+
`card.properties` entry whose value is not a string, since Notion's
|
|
119
|
+
own write mapping can only ever write a flat string regardless of
|
|
120
|
+
what `Card.properties` is now typed to allow.
|
|
121
|
+
|
|
8
122
|
## [0.2.1] - 2026-10-31
|
|
9
123
|
|
|
10
124
|
### Fixed
|
package/dist/asf-board.js
CHANGED
|
@@ -60,9 +60,11 @@
|
|
|
60
60
|
// instead of it. `get()` by native id is unaffected either way: each task
|
|
61
61
|
// is still found by its own unambiguous id.
|
|
62
62
|
//
|
|
63
|
-
// READ LOGIC (the one GET per read, the properties/column mapping,
|
|
64
|
-
//
|
|
65
|
-
//
|
|
63
|
+
// READ LOGIC (the one GET per read, the properties/column mapping, every
|
|
64
|
+
// JSON-safe property value -- strings, numbers, booleans, null, arrays,
|
|
65
|
+
// nested objects -- carried through `Card.properties` verbatim, NEVER
|
|
66
|
+
// demoted to `unknownFields` for not being a plain string) maps the API's
|
|
67
|
+
// task shape to this boundary's `CardSource`/`CardSink` shape. `Card.state` is
|
|
66
68
|
// deliberately the RAW column the API returns, never mapped onto a closed
|
|
67
69
|
// status union: board.ts's own `State` doc is explicit it "must not become
|
|
68
70
|
// a union" -- there is no tracker-independent taxonomy this boundary owns.
|
|
@@ -85,15 +87,27 @@
|
|
|
85
87
|
// with no `If-Match` at all, which would silently overwrite the resource's
|
|
86
88
|
// real properties with whatever this file guessed.
|
|
87
89
|
import { z } from 'zod';
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
90
|
+
// Before 0.2.2, a task whose `ticket` or `builtBy` was not a string, or
|
|
91
|
+
// whose `requires` was neither a string nor an array of strings (for
|
|
92
|
+
// example a number), failed validation: it was reported under
|
|
93
|
+
// `unparseable` with the failing field named, and left out of `cards`,
|
|
94
|
+
// never silently dropped. A task that did validate had only its
|
|
95
|
+
// string-valued properties copied into `Card.properties`; every
|
|
96
|
+
// non-string value, including an array-valued `requires`, numbers,
|
|
97
|
+
// booleans and objects, went to `Card.unknownFields` instead. From
|
|
98
|
+
// 0.2.2, JSON-safe values are carried in `Card.properties` as they are.
|
|
99
|
+
//
|
|
100
|
+
// Now every key's value is carried through verbatim into
|
|
101
|
+
// `Card.properties`, whatever its JSON shape -- a string, number,
|
|
102
|
+
// boolean, null, array or nested object -- never narrowed per key and
|
|
103
|
+
// never split off into `unknownFields` by type. ASF's own task API
|
|
104
|
+
// already hands back JSON, so every value already IS JSON-safe. Callers
|
|
105
|
+
// that need a specific key as a string (`ticketOf`, `cardFrom`'s
|
|
106
|
+
// ticket/title overrides) check that for themselves at the point of use,
|
|
107
|
+
// exactly as they did before; this schema's only remaining job is
|
|
108
|
+
// confirming `properties` itself is a plain object when present, not any
|
|
109
|
+
// one key's shape within it.
|
|
110
|
+
const PropertiesSchema = z.object({}).passthrough().optional().default({});
|
|
97
111
|
// No refine requiring a non-empty ticket-or-id: `id` alone is this file's
|
|
98
112
|
// identity now (see the file header), so it is the only field that must be
|
|
99
113
|
// non-empty.
|
|
@@ -131,25 +145,17 @@ function ticketOf(task) {
|
|
|
131
145
|
const ticket = task.properties.ticket;
|
|
132
146
|
return typeof ticket === 'string' && ticket.trim() !== '' ? ticket : undefined;
|
|
133
147
|
}
|
|
134
|
-
/** Splits a raw properties bag into the flat string record `Card.properties`
|
|
135
|
-
* can carry, and everything else -- arrays, numbers, nested objects -- which
|
|
136
|
-
* goes to `Card.unknownFields` instead of being silently dropped or coerced. */
|
|
137
|
-
function splitProperties(properties) {
|
|
138
|
-
const stringProps = {};
|
|
139
|
-
const nonStringProps = {};
|
|
140
|
-
for (const [key, value] of Object.entries(properties)) {
|
|
141
|
-
if (typeof value === 'string') {
|
|
142
|
-
stringProps[key] = value;
|
|
143
|
-
}
|
|
144
|
-
else {
|
|
145
|
-
nonStringProps[key] = value;
|
|
146
|
-
}
|
|
147
|
-
}
|
|
148
|
-
return { stringProps, nonStringProps };
|
|
149
|
-
}
|
|
150
148
|
function cardFrom(task, spaceId, baseUrl) {
|
|
151
|
-
|
|
152
|
-
|
|
149
|
+
// Every value ASF's task API handed back for `properties` is already
|
|
150
|
+
// JSON-safe by construction (it arrived as JSON) -- carried through
|
|
151
|
+
// verbatim into `Card.properties` rather than split off into
|
|
152
|
+
// `unknownFields` for not being a plain string. See the file header's
|
|
153
|
+
// note on non-string custom properties, and `Card.properties`'s own
|
|
154
|
+
// doc in card.ts for why this boundary is allowed to populate it with
|
|
155
|
+
// more than flat strings.
|
|
156
|
+
const properties = {
|
|
157
|
+
...task.properties,
|
|
158
|
+
};
|
|
153
159
|
// A real `properties.title` string ASF already set is never overwritten
|
|
154
160
|
// by the top-level `title` field below -- silently replacing one
|
|
155
161
|
// property's value with an unrelated field of the same name would be
|
|
@@ -187,7 +193,7 @@ function cardFrom(task, spaceId, baseUrl) {
|
|
|
187
193
|
reference: `${baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/tasks/${encodeURIComponent(task.id)}`,
|
|
188
194
|
source: `asf:${spaceId}`,
|
|
189
195
|
properties,
|
|
190
|
-
unknownFields:
|
|
196
|
+
unknownFields: extraTop,
|
|
191
197
|
...(typeof task.revision === 'string' ? { revision: task.revision } : {}),
|
|
192
198
|
};
|
|
193
199
|
}
|
|
@@ -349,6 +355,33 @@ function looseRunIdOf(body) {
|
|
|
349
355
|
return undefined;
|
|
350
356
|
return typeof body.id === 'string' && body.id.trim() !== '' ? body.id : undefined;
|
|
351
357
|
}
|
|
358
|
+
/**
|
|
359
|
+
* Reads `bag[key]` as an optional string, for the one rule every
|
|
360
|
+
* write-path property read in this file now follows: PRESENT but not a
|
|
361
|
+
* string is `wrongType` -- a case for the caller to refuse by name, never
|
|
362
|
+
* to silently substitute a fallback for it. `bag` is deliberately typed
|
|
363
|
+
* as any string-keyed record, not specifically `card.properties` --
|
|
364
|
+
* `createCard` calls this against both `card.properties` (`title`,
|
|
365
|
+
* `ticket`) and `card.unknownFields` (`subtype`, `body`), the two bags
|
|
366
|
+
* this file reads a typed value with a fallback out of.
|
|
367
|
+
*
|
|
368
|
+
* In 0.2.1, `createCard` forwarded only string-valued properties:
|
|
369
|
+
* non-string values never reached the write. An absent or non-string
|
|
370
|
+
* `title` or `ticket` fell back to `card.id`; a non-string `subtype` was
|
|
371
|
+
* written as `'task'`, and a non-string `body` was omitted. Now that
|
|
372
|
+
* `Card.properties` carries JSON-safe values (this release), `createCard`
|
|
373
|
+
* checks `title`, `ticket`, `subtype` and `body` through this helper: a
|
|
374
|
+
* value that is present but not a string is refused by name and nothing
|
|
375
|
+
* is sent; an absent value keeps the previous fallback.
|
|
376
|
+
*/
|
|
377
|
+
function readOptionalString(bag, key) {
|
|
378
|
+
const value = bag[key];
|
|
379
|
+
if (value === undefined)
|
|
380
|
+
return { kind: 'absent' };
|
|
381
|
+
if (typeof value !== 'string')
|
|
382
|
+
return { kind: 'wrongType' };
|
|
383
|
+
return { kind: 'value', value };
|
|
384
|
+
}
|
|
352
385
|
export function asfBoard(options) {
|
|
353
386
|
const fetchFn = options.fetchImpl;
|
|
354
387
|
async function authorizedFetch(url, init) {
|
|
@@ -485,19 +518,59 @@ export function asfBoard(options) {
|
|
|
485
518
|
return { outcome: 'applied' };
|
|
486
519
|
}
|
|
487
520
|
async function createCard(card) {
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
const
|
|
493
|
-
|
|
494
|
-
|
|
521
|
+
// Sent through verbatim, whatever JSON shape each value is -- same
|
|
522
|
+
// discipline as the read side's `cardFrom` (see its own comment):
|
|
523
|
+
// this boundary no longer splits `card.properties` into a
|
|
524
|
+
// string-only subset before sending it to ASF.
|
|
525
|
+
const propertiesToSend = { ...(card.properties ?? {}) };
|
|
526
|
+
// `title` and `ticket` are both read as typed values below, via the
|
|
527
|
+
// shared `readOptionalString` -- see its own doc for the one rule every
|
|
528
|
+
// write-path property read here follows: PRESENT but not a string is a
|
|
529
|
+
// named refusal, with NOTHING sent; ABSENT is the only case where the
|
|
530
|
+
// `card.id` fallback below applies.
|
|
531
|
+
//
|
|
532
|
+
// In 0.2.1, createCard forwarded only string-valued properties:
|
|
533
|
+
// non-string values never reached the write. An absent or non-string
|
|
534
|
+
// `title` or `ticket` fell back to `card.id`; a non-string `subtype`
|
|
535
|
+
// was written as `'task'`, and a non-string `body` was omitted. Now
|
|
536
|
+
// that `Card.properties` carries JSON-safe values (this release),
|
|
537
|
+
// createCard checks `title`, `ticket`, `subtype` and `body` through
|
|
538
|
+
// one helper: a value that is present but not a string is refused by
|
|
539
|
+
// name and nothing is sent; an absent value keeps the previous
|
|
540
|
+
// fallback.
|
|
541
|
+
const titleRead = readOptionalString(propertiesToSend, 'title');
|
|
542
|
+
if (titleRead.kind === 'wrongType') {
|
|
543
|
+
return { outcome: 'refused', reason: 'title must be a string' };
|
|
544
|
+
}
|
|
545
|
+
const ticketRead = readOptionalString(propertiesToSend, 'ticket');
|
|
546
|
+
if (ticketRead.kind === 'wrongType') {
|
|
547
|
+
return { outcome: 'refused', reason: 'ticket must be a string' };
|
|
548
|
+
}
|
|
549
|
+
// `subtype` and `body` live in `card.unknownFields`, not `properties`,
|
|
550
|
+
// but the same rule applies: PRESENT but not a string is a named
|
|
551
|
+
// refusal, never a silent substitute. A present-but-wrong-type
|
|
552
|
+
// `subtype` used to be silently written as the literal `'task'`; a
|
|
553
|
+
// present-but-wrong-type `body` used to be silently DROPPED from the
|
|
554
|
+
// request entirely -- both are exactly the "fallback stands in while
|
|
555
|
+
// the bad value either rides along or vanishes" trap `readOptionalString`
|
|
556
|
+
// exists to close, so they go through the same helper.
|
|
557
|
+
const subtypeRead = readOptionalString(card.unknownFields, 'subtype');
|
|
558
|
+
if (subtypeRead.kind === 'wrongType') {
|
|
559
|
+
return { outcome: 'refused', reason: 'subtype must be a string' };
|
|
560
|
+
}
|
|
561
|
+
const bodyRead = readOptionalString(card.unknownFields, 'body');
|
|
562
|
+
if (bodyRead.kind === 'wrongType') {
|
|
563
|
+
return { outcome: 'refused', reason: 'body must be a string' };
|
|
564
|
+
}
|
|
565
|
+
const subtype = subtypeRead.kind === 'value' ? subtypeRead.value : 'task';
|
|
566
|
+
const title = titleRead.kind === 'value' ? titleRead.value : card.id;
|
|
567
|
+
const bodyField = bodyRead.kind === 'value' ? bodyRead.value : undefined;
|
|
568
|
+
const key = ticketRead.kind === 'value' ? ticketRead.value : card.id;
|
|
495
569
|
// `title` is sent as its own top-level field above; `cardFrom` copies a
|
|
496
570
|
// read task's `title` into `Card.properties.title` purely as a read-side
|
|
497
571
|
// convenience (see cardFrom), so strip it back out here -- otherwise a
|
|
498
572
|
// round-tripped card writes the same title into ASF's properties bag a
|
|
499
573
|
// second time, alongside the dedicated `title` field.
|
|
500
|
-
const propertiesToSend = { ...stringProps };
|
|
501
574
|
delete propertiesToSend.title;
|
|
502
575
|
const fields = {
|
|
503
576
|
subtype,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { StatusMap } from './status.js';
|
|
2
|
+
import type { CardSink, CardSource } from './board.js';
|
|
3
|
+
/**
|
|
4
|
+
* Native marker character to normalized status. '~' is `in-progress`
|
|
5
|
+
* because the reference reads it as `assigned`; it is also written for
|
|
6
|
+
* planning and in-review work, which one marker cannot tell apart.
|
|
7
|
+
*/
|
|
8
|
+
export declare const BACKLOG_STATUS_MAP: StatusMap;
|
|
9
|
+
export interface BacklogBoardOptions {
|
|
10
|
+
readonly read: () => Promise<string>;
|
|
11
|
+
readonly write: (text: string) => Promise<void>;
|
|
12
|
+
readonly statusMap?: StatusMap;
|
|
13
|
+
/**
|
|
14
|
+
* Cards kept elsewhere (an archive file). Their ids resolve references that
|
|
15
|
+
* would otherwise be reported as dangling. Not listed, not writable.
|
|
16
|
+
*/
|
|
17
|
+
readonly archived?: readonly {
|
|
18
|
+
readonly id: string;
|
|
19
|
+
}[];
|
|
20
|
+
}
|
|
21
|
+
export declare function createBacklogBoard(options: BacklogBoardOptions): CardSource & CardSink;
|