@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 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
- // non-string properties landing in `unknownFields`) maps the API's task
65
- // shape to this boundary's `CardSource`/`CardSink` shape. `Card.state` is
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
- const PropertiesSchema = z
89
- .object({
90
- ticket: z.string().optional(),
91
- builtBy: z.string().optional(),
92
- requires: z.union([z.string(), z.array(z.string())]).optional(),
93
- })
94
- .passthrough()
95
- .optional()
96
- .default({});
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
- const { stringProps, nonStringProps } = splitProperties(task.properties);
152
- const properties = { ...stringProps };
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: { ...nonStringProps, ...extraTop },
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
- const { stringProps } = splitProperties(card.properties ?? {});
489
- const subtype = typeof card.unknownFields.subtype === 'string'
490
- ? card.unknownFields.subtype
491
- : 'task';
492
- const title = stringProps.title ?? card.id;
493
- const bodyField = typeof card.unknownFields.body === 'string' ? card.unknownFields.body : undefined;
494
- const key = stringProps.ticket ?? card.id;
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;