@otea/cli 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (243) hide show
  1. package/LICENSE +661 -0
  2. package/README.es.md +151 -0
  3. package/README.md +251 -3
  4. package/THIRD_PARTY_NOTICES.md +114 -0
  5. package/bin/otea.mjs +28 -0
  6. package/dist/app/agent-detail.js +26 -0
  7. package/dist/app/agent-draft.js +429 -0
  8. package/dist/app/agent-prompts.js +52 -0
  9. package/dist/app/agents.js +77 -0
  10. package/dist/app/asking.js +43 -0
  11. package/dist/app/board-archive.js +243 -0
  12. package/dist/app/board-migration.js +272 -0
  13. package/dist/app/boards.js +870 -0
  14. package/dist/app/branch-owner.js +48 -0
  15. package/dist/app/brief.js +53 -0
  16. package/dist/app/choices.js +61 -0
  17. package/dist/app/collections.js +101 -0
  18. package/dist/app/context.js +1 -0
  19. package/dist/app/crop.js +56 -0
  20. package/dist/app/devices.js +62 -0
  21. package/dist/app/draft-request.js +82 -0
  22. package/dist/app/events.js +12 -0
  23. package/dist/app/evidence.js +287 -0
  24. package/dist/app/gates.js +610 -0
  25. package/dist/app/guide.js +37 -0
  26. package/dist/app/home.js +145 -0
  27. package/dist/app/init-boards.js +36 -0
  28. package/dist/app/intake.js +25 -0
  29. package/dist/app/item-search.js +141 -0
  30. package/dist/app/items.js +318 -0
  31. package/dist/app/keep-waiting.js +44 -0
  32. package/dist/app/land-order.js +107 -0
  33. package/dist/app/language.js +52 -0
  34. package/dist/app/launcher.js +56 -0
  35. package/dist/app/lease-take.js +54 -0
  36. package/dist/app/leases.js +86 -0
  37. package/dist/app/machine.js +39 -0
  38. package/dist/app/merged.js +89 -0
  39. package/dist/app/migrate.js +171 -0
  40. package/dist/app/next.js +1637 -0
  41. package/dist/app/notes.js +319 -0
  42. package/dist/app/notify-targets.js +113 -0
  43. package/dist/app/opened.js +25 -0
  44. package/dist/app/owner-only.js +34 -0
  45. package/dist/app/performance.js +28 -0
  46. package/dist/app/phone.js +97 -0
  47. package/dist/app/presence.js +596 -0
  48. package/dist/app/preset-views.js +25 -0
  49. package/dist/app/presets.js +129 -0
  50. package/dist/app/priority.js +156 -0
  51. package/dist/app/profile.js +86 -0
  52. package/dist/app/project.js +247 -0
  53. package/dist/app/proofs.js +179 -0
  54. package/dist/app/questions.js +215 -0
  55. package/dist/app/reader-filter.js +58 -0
  56. package/dist/app/relations.js +164 -0
  57. package/dist/app/relay.js +98 -0
  58. package/dist/app/repos.js +176 -0
  59. package/dist/app/restart.js +92 -0
  60. package/dist/app/set-aside.js +64 -0
  61. package/dist/app/system-locale.js +6 -0
  62. package/dist/app/tailscale-cli.js +77 -0
  63. package/dist/app/tailscale-testing.js +41 -0
  64. package/dist/app/tailscale.js +177 -0
  65. package/dist/app/tips.js +30 -0
  66. package/dist/app/topics-everywhere.js +53 -0
  67. package/dist/app/topics.js +453 -0
  68. package/dist/app/undo.js +52 -0
  69. package/dist/app/validate.js +131 -0
  70. package/dist/app/watch.js +48 -0
  71. package/dist/cli/command.js +44 -0
  72. package/dist/cli/commands.js +3303 -0
  73. package/dist/cli/exit-codes.js +70 -0
  74. package/dist/cli/forge.js +176 -0
  75. package/dist/cli/format.js +340 -0
  76. package/dist/cli/gh.js +17 -0
  77. package/dist/cli/gitrepo.js +489 -0
  78. package/dist/cli/help.js +101 -0
  79. package/dist/cli/hooks.js +232 -0
  80. package/dist/cli/main.js +37 -0
  81. package/dist/cli/merged-outside.js +58 -0
  82. package/dist/cli/names.js +154 -0
  83. package/dist/cli/opener.js +21 -0
  84. package/dist/cli/owner.js +154 -0
  85. package/dist/cli/phone.js +221 -0
  86. package/dist/cli/ports.js +24 -0
  87. package/dist/cli/probe.js +18 -0
  88. package/dist/cli/run.js +246 -0
  89. package/dist/cli/serve-file.js +21 -0
  90. package/dist/cli/stats.js +55 -0
  91. package/dist/cli/version.js +3 -0
  92. package/dist/core/agent-guide.js +31 -0
  93. package/dist/core/agent-prompts.js +139 -0
  94. package/dist/core/authority.js +94 -0
  95. package/dist/core/board/analysis.js +86 -0
  96. package/dist/core/board/choices.js +100 -0
  97. package/dist/core/board/compile.js +362 -0
  98. package/dist/core/board/engine.js +523 -0
  99. package/dist/core/board/hints.js +46 -0
  100. package/dist/core/board/history.js +146 -0
  101. package/dist/core/board/ids.js +87 -0
  102. package/dist/core/board/joins.js +30 -0
  103. package/dist/core/board/mentions.js +68 -0
  104. package/dist/core/board/merged.js +18 -0
  105. package/dist/core/board/model.js +135 -0
  106. package/dist/core/board/next.js +1116 -0
  107. package/dist/core/board/notes.js +298 -0
  108. package/dist/core/board/performance.js +218 -0
  109. package/dist/core/board/plan.js +299 -0
  110. package/dist/core/board/problems.js +232 -0
  111. package/dist/core/board/proofs.js +84 -0
  112. package/dist/core/board/questions.js +114 -0
  113. package/dist/core/board/reading.js +220 -0
  114. package/dist/core/board/readings.js +534 -0
  115. package/dist/core/board/schema.js +335 -0
  116. package/dist/core/board/shape-words.js +179 -0
  117. package/dist/core/board/template-words.js +23 -0
  118. package/dist/core/board/templates-catalogue.js +965 -0
  119. package/dist/core/board/templates-coverage.js +261 -0
  120. package/dist/core/board/templates-flows.js +779 -0
  121. package/dist/core/board/templates.js +586 -0
  122. package/dist/core/brief.js +93 -0
  123. package/dist/core/diagram.js +80 -0
  124. package/dist/core/errors.js +12 -0
  125. package/dist/core/evidence.js +33 -0
  126. package/dist/core/fields.js +129 -0
  127. package/dist/core/hierarchy.js +30 -0
  128. package/dist/core/icons.js +181 -0
  129. package/dist/core/image-crop.js +166 -0
  130. package/dist/core/item.js +49 -0
  131. package/dist/core/lease.js +31 -0
  132. package/dist/core/modules.js +318 -0
  133. package/dist/core/notify/planner.js +117 -0
  134. package/dist/core/notify/signals.js +66 -0
  135. package/dist/core/notify/text.js +60 -0
  136. package/dist/core/path-key.js +22 -0
  137. package/dist/core/placement.js +161 -0
  138. package/dist/core/preset-labels.js +66 -0
  139. package/dist/core/preset-notes.js +109 -0
  140. package/dist/core/preset.js +541 -0
  141. package/dist/core/profile.js +55 -0
  142. package/dist/core/project-id.js +20 -0
  143. package/dist/core/refusal.js +1 -0
  144. package/dist/core/relations.js +208 -0
  145. package/dist/core/repo.js +54 -0
  146. package/dist/core/samples.js +161 -0
  147. package/dist/core/search-words.js +68 -0
  148. package/dist/core/test-report.js +120 -0
  149. package/dist/core/time.js +8 -0
  150. package/dist/core/validation.js +60 -0
  151. package/dist/core/views.js +171 -0
  152. package/dist/core/workflow.js +51 -0
  153. package/dist/mcp/commands.js +101 -0
  154. package/dist/mcp/server.js +239 -0
  155. package/dist/mcp/words.js +95 -0
  156. package/dist/server/boards.js +232 -0
  157. package/dist/server/changes.js +42 -0
  158. package/dist/server/diff-tip.js +83 -0
  159. package/dist/server/drift.js +87 -0
  160. package/dist/server/errors.js +87 -0
  161. package/dist/server/evidence.js +82 -0
  162. package/dist/server/hosts.js +6 -0
  163. package/dist/server/hub.js +98 -0
  164. package/dist/server/lan-access.js +62 -0
  165. package/dist/server/lan.js +164 -0
  166. package/dist/server/listen.js +70 -0
  167. package/dist/server/notifier.js +156 -0
  168. package/dist/server/notify-api.js +151 -0
  169. package/dist/server/pairing.js +124 -0
  170. package/dist/server/projects.js +191 -0
  171. package/dist/server/push.js +199 -0
  172. package/dist/server/server.js +960 -0
  173. package/dist/server/session.js +43 -0
  174. package/dist/server/stream.js +36 -0
  175. package/dist/server/test-push.js +38 -0
  176. package/dist/server/token.js +37 -0
  177. package/dist/server/transports.js +54 -0
  178. package/dist/server/ui.js +44 -0
  179. package/dist/server/writes.js +361 -0
  180. package/dist/server/wrong-address.js +36 -0
  181. package/dist/store/boards.js +111 -0
  182. package/dist/store/database.js +45 -0
  183. package/dist/store/machine.js +77 -0
  184. package/dist/store/migrations.js +493 -0
  185. package/dist/store/queries.js +585 -0
  186. package/dist/store/registry.js +72 -0
  187. package/package.json +72 -4
  188. package/presets/architecture/playbook.md +69 -0
  189. package/presets/architecture/preset.yaml +80 -0
  190. package/presets/architecture/samples.yaml +23 -0
  191. package/presets/bug-triage/playbook.md +129 -0
  192. package/presets/bug-triage/preset.yaml +127 -0
  193. package/presets/bug-triage/samples/wall-slide-after.png +0 -0
  194. package/presets/bug-triage/samples/wall-slide-before.png +0 -0
  195. package/presets/bug-triage/samples.yaml +72 -0
  196. package/presets/change/playbook.md +115 -0
  197. package/presets/change/preset.yaml +141 -0
  198. package/presets/change/samples.yaml +62 -0
  199. package/presets/review/playbook.md +51 -0
  200. package/presets/review/preset.yaml +62 -0
  201. package/presets/review/samples.yaml +27 -0
  202. package/presets/tasks/playbook.md +78 -0
  203. package/presets/tasks/preset.yaml +61 -0
  204. package/presets/tasks/samples.yaml +46 -0
  205. package/schemas/board.schema.json +764 -0
  206. package/ui/dist/THIRD_PARTY_NOTICES.md +114 -0
  207. package/ui/dist/assets/dm-mono-latin-400-normal--0xN8mdc.woff +0 -0
  208. package/ui/dist/assets/dm-mono-latin-400-normal-4GdczIuU.woff2 +0 -0
  209. package/ui/dist/assets/dm-mono-latin-500-normal-CN8Miw6E.woff +0 -0
  210. package/ui/dist/assets/dm-mono-latin-500-normal-DRMDZjhP.woff2 +0 -0
  211. package/ui/dist/assets/dm-mono-latin-ext-400-normal-1aZr6b2b.woff +0 -0
  212. package/ui/dist/assets/dm-mono-latin-ext-400-normal-C2zvOubV.woff2 +0 -0
  213. package/ui/dist/assets/dm-mono-latin-ext-500-normal-BtRyHRi6.woff2 +0 -0
  214. package/ui/dist/assets/dm-mono-latin-ext-500-normal-Dw3M13d8.woff +0 -0
  215. package/ui/dist/assets/index-C3OzJope.js +103 -0
  216. package/ui/dist/assets/index-COdEjckQ.css +1 -0
  217. package/ui/dist/assets/newsreader-latin-ext-opsz-italic-CSPGnFdO.woff2 +0 -0
  218. package/ui/dist/assets/newsreader-latin-ext-opsz-normal-BQn1nviT.woff2 +0 -0
  219. package/ui/dist/assets/newsreader-latin-opsz-italic-kJKFiXvB.woff2 +0 -0
  220. package/ui/dist/assets/newsreader-latin-opsz-normal-s-izfB6B.woff2 +0 -0
  221. package/ui/dist/assets/newsreader-vietnamese-opsz-italic-DTr-ymY4.woff2 +0 -0
  222. package/ui/dist/assets/newsreader-vietnamese-opsz-normal-BjhtXyW2.woff2 +0 -0
  223. package/ui/dist/assets/pdf-YwugTw7Y.js +54 -0
  224. package/ui/dist/assets/pdf-engine-CkBopwck.js +1 -0
  225. package/ui/dist/assets/pdf-rELvHkft.js +56 -0
  226. package/ui/dist/assets/pdf.worker.min-B5Yc7dP4.mjs +27 -0
  227. package/ui/dist/assets/pdf.worker.min-B7U8ptvh.js +1 -0
  228. package/ui/dist/assets/pdf.worker.min-CIqJB0yW.mjs +28 -0
  229. package/ui/dist/assets/pdf.worker.min-UqOn5EDC.js +1 -0
  230. package/ui/dist/assets/schibsted-grotesk-latin-ext-wght-normal-hsMS0n0O.woff2 +0 -0
  231. package/ui/dist/assets/schibsted-grotesk-latin-wght-normal-Bb8VGrTG.woff2 +0 -0
  232. package/ui/dist/icons/apple-touch-icon.png +0 -0
  233. package/ui/dist/icons/otea-192.png +0 -0
  234. package/ui/dist/icons/otea-512.png +0 -0
  235. package/ui/dist/icons/otea-badge.png +0 -0
  236. package/ui/dist/icons/otea-maskable-512.png +0 -0
  237. package/ui/dist/index.html +25 -0
  238. package/ui/dist/manifest.webmanifest +24 -0
  239. package/ui/dist/otea-idle.svg +5 -0
  240. package/ui/dist/otea-working.svg +5 -0
  241. package/ui/dist/otea-yours-working.svg +5 -0
  242. package/ui/dist/otea-yours.svg +5 -0
  243. package/ui/dist/sw.js +1 -0
@@ -0,0 +1,335 @@
1
+ import { z } from 'zod';
2
+ import { ICON_NAMES } from '../icons.js';
3
+ import { KEY } from '../preset.js';
4
+ import { BOARD_SCHEMA, DONE, DROPPED, EVIDENCE_KINDS, FIELD_KINDS, PLACES, SAME, TITLE, WAITS, ZONES, } from './model.js';
5
+ import { placeOf, shapeProblems } from './shape-words.js';
6
+ // The shape of a board definition as it travels (PUT draft) and as it is stored (a version or a
7
+ // draft row): checked whole, so a malformed document never reaches the engine. Problems a person
8
+ // can fix in the editor (a duplicate name, a bad way) are not shape errors: problemsOf finds them.
9
+ // Every key says what it is for, with an example: the JSON Schema published for agents
10
+ // (schemas/board.schema.json) and the words of a shape error read them.
11
+ const about = (description, ...examples) => ({ description, examples });
12
+ // An id keys what the published board compiles to (a part its field, a step its states), so it
13
+ // reads by the same rule: a board.json that reads here also publishes (P5-R3-9).
14
+ const id = z
15
+ .string()
16
+ .regex(KEY, 'is not an id: lowercase letters, digits and _, starting with a letter, no dashes');
17
+ // An id: of the thing itself, or of the step or part it names.
18
+ const idOf = (description, ...examples) => id.meta(about(description, ...examples));
19
+ const ids = (description, ...examples) => z.array(id).meta(about(description, ...examples));
20
+ const text = (description, ...examples) => z.string().meta(about(description, ...examples));
21
+ const flag = (description, example) => z.boolean().meta(about(description, example));
22
+ // A motive names a closed state of its own (dropped__<id>), whose name takes no dash.
23
+ const STATE_KEY = /^[a-z][a-z0-9_]*$/;
24
+ const choice = z
25
+ .strictObject({
26
+ id: idOf('The hidden id of the choice', 'chigh'),
27
+ name: text('What the choice reads', 'High'),
28
+ })
29
+ .meta(about('A choice of the field', { id: 'chigh', name: 'High' }));
30
+ const part = z
31
+ .strictObject({
32
+ id: idOf('The hidden id of the part: its key in parts', 'fsteps'),
33
+ name: text('What the field or evidence is called', 'Steps to reproduce'),
34
+ kind: z
35
+ .enum([...FIELD_KINDS, ...EVIDENCE_KINDS])
36
+ .meta(about(`A field (${FIELD_KINDS.join(', ')}) or evidence (${EVIDENCE_KINDS.join(', ')})`, 'long', 'images')),
37
+ hint: text('What goes here: the line agents read', 'The commands that show the bug', ''),
38
+ options: z
39
+ .array(choice)
40
+ .meta(about('The choices of a choice, multi or check field; empty for any other kind', [{ id: 'chigh', name: 'High' }], [])),
41
+ show: text('How evidence shows: images as gallery, one or ba; video as strip or player', 'gallery').optional(),
42
+ initial: text('The value a new item starts with: a choice id, a level (low, medium, high, critical), yes or no', 'chigh').optional(),
43
+ guard: z
44
+ .strictObject({
45
+ push: ids('The steps (ids) during which the branch may be pushed', ['simplement']),
46
+ repo: idOf('The field (part id) the repository is read from', 'frepo').optional(),
47
+ base: text('The base branch Otea protects too: agents push or merge into it only to bring in an item that is Done', 'main').optional(),
48
+ })
49
+ .meta(about('A branch field only: Otea protects the branch', {
50
+ push: ['simplement'],
51
+ repo: 'frepo',
52
+ base: 'main',
53
+ }))
54
+ .optional(),
55
+ proof: z
56
+ .boolean()
57
+ .meta({
58
+ description: 'A checklist only ("pide prueba"): each ticked point needs a proof in the round (an attached file, a line of an attached log, or a test that passes in an attached report) before the step that hands it is handed off',
59
+ examples: [true],
60
+ })
61
+ .optional(),
62
+ })
63
+ .meta(about('A field (something to fill) or a piece of evidence (something to show)', {
64
+ id: 'fsteps',
65
+ name: 'Steps to reproduce',
66
+ kind: 'long',
67
+ hint: '',
68
+ options: [],
69
+ }));
70
+ const hand = z
71
+ .strictObject({
72
+ ref: idOf('The part (id) the step hands off, or title', 'fsteps'),
73
+ req: z
74
+ .enum(['always', 'when', 'no'], { error: 'must be "always", "when" or "no"' })
75
+ .meta(about('Whether it is required: always, only when another part has a value, or no', 'always')),
76
+ when: z
77
+ .strictObject({
78
+ part: idOf('The choice, multi, level or yesno part (id) it reads', 'fseverity'),
79
+ value: text('The value that makes it required: a choice id, a level, yes or no', 'high'),
80
+ })
81
+ .meta(about('With req "when": which part and value make it required', {
82
+ part: 'fseverity',
83
+ value: 'high',
84
+ }))
85
+ .optional(),
86
+ fresh: flag('Evidence only: new in each round, so a send-back empties it', false),
87
+ })
88
+ .meta(about('One thing the step hands off', { ref: 'fsteps', req: 'always', fresh: false }));
89
+ const step = z
90
+ .strictObject({
91
+ id: idOf('The hidden id of the step', 'sfix'),
92
+ name: text('What the step is called', 'Fix'),
93
+ doer: z
94
+ .enum(['you', 'any'], { error: 'must be "you" or "any"' })
95
+ .meta(about('Who does the step: "you" (the person) or "any" agent', 'any', 'you')),
96
+ reviewer: z
97
+ .enum(['none', 'you', 'any'], { error: 'must be "none", "you" or "any"' })
98
+ .meta(about('Who reviews the step: "none", "you" (the person) or "any" agent, never the one that did it in that round', 'you', 'any')),
99
+ hand: z
100
+ .array(hand)
101
+ .meta(about('What the step hands off', [{ ref: 'fsteps', req: 'always', fresh: false }])),
102
+ ways: ids('Ways out besides the next step: a later step (id) or done, or an earlier step to take the item back to', ['done'], []),
103
+ back: idOf('Where a send-back lands: same (this step) or an earlier step id', 'same'),
104
+ instructions: z
105
+ .strictObject({
106
+ take: text('What an agent reads when it takes the step', 'Reproduce it first.'),
107
+ before: text('What an agent reads before it hands the step off', 'Run the tests.'),
108
+ review: text('What an agent reviewing the step reads', 'Check the test fails first.'),
109
+ })
110
+ .meta(about('The instructions agents read on the step; mention a step or part as @[id], its id, which agents read as its name', {
111
+ take: 'Reproduce it first.',
112
+ before: 'Run the tests.',
113
+ review: '',
114
+ })),
115
+ note: z
116
+ .strictObject({
117
+ req: z
118
+ .enum(['no', 'always'], { error: 'must be "no" or "always"' })
119
+ .meta(about('Whether each handoff needs a note', 'always')),
120
+ hint: text('What goes in the note', 'What you ran and what you saw'),
121
+ })
122
+ .default({ req: 'no', hint: '' })
123
+ .meta(about('The note the doer writes with each handoff', { req: 'no', hint: '' })),
124
+ waits: z
125
+ .array(z.enum(WAITS, { error: 'must be "parts" or "blockers"' }))
126
+ .default([])
127
+ .meta(about('What the step waits for before it is handed off: its parts closed, its blockers closed', ['blockers'], [])),
128
+ skipWhenReady: flag('First step nobody reviews only: an item created with all it hands off starts at the next step', false).default(false),
129
+ doerMayDrop: flag('Whether an agent doing it may drop the item, saying why', false).default(false),
130
+ lead: z
131
+ .strictObject({
132
+ to: idOf('Where it leads instead of the next step: a later step id or done', 'done'),
133
+ when: z
134
+ .strictObject({
135
+ part: idOf('The choice, multi, level or yesno part (id) it reads', 'fmine'),
136
+ value: text('The value that makes it lead there: a choice id, a level, yes or no', 'yes'),
137
+ })
138
+ .meta(about('Which part and value make it lead there', { part: 'fmine', value: 'yes' })),
139
+ })
140
+ .meta(about('While a part holds a value, the way the step takes instead of the next step; the next step is then a way only if ways lists it', { to: 'done', when: { part: 'fmine', value: 'yes' } }))
141
+ .optional(),
142
+ })
143
+ .meta(about('A step of the board, in order'));
144
+ export const definitionSchema = z
145
+ .strictObject({
146
+ // A version 1 definition reads as version 2, every later setting at its default.
147
+ schema: z
148
+ .union([z.literal(1), z.literal(BOARD_SCHEMA)], { error: `must be ${BOARD_SCHEMA}` })
149
+ .meta(about(`The version of the board format: write ${BOARD_SCHEMA}`, BOARD_SCHEMA))
150
+ .transform(() => BOARD_SCHEMA),
151
+ name: text('The name of the board', 'Bugs'),
152
+ item: text('What one item of the board is called', 'Bug'),
153
+ icon: text(`The icon of the board and its items, one of: ${ICON_NAMES.join(', ')}`, 'bug'),
154
+ title: text('The name of the title field every item has', 'Title'),
155
+ parts: z.record(id, part).meta(about('The fields and evidence of the board, by id', {
156
+ fsteps: { id: 'fsteps', name: 'Steps to reproduce', kind: 'long', hint: '', options: [] },
157
+ })),
158
+ form: z
159
+ .array(z
160
+ .strictObject({
161
+ ref: idOf('A field (id) the creation form asks for', 'fsteps'),
162
+ required: flag('Whether the form requires it', true),
163
+ })
164
+ .meta(about('A field of the creation form', { ref: 'fsteps', required: true })))
165
+ .meta(about('The creation form besides the title, in order', [{ ref: 'fsteps', required: true }])),
166
+ steps: z
167
+ .array(step)
168
+ .meta(about('The steps, in order: the default way out of each is the next one, and done after the last')),
169
+ anytime: ids('Parts (ids) that can be filled at any step', ['fbranch'], []),
170
+ layout: z.record(id, z.enum(ZONES)).meta(about(`Where each part (or rounds, or parts) shows on the item page: ${ZONES.join(', ')}`, {
171
+ fsteps: 'main',
172
+ rounds: 'side',
173
+ })),
174
+ row: ids('The parts (ids) the list row shows, in order', ['fseverity'], []),
175
+ about: text('About this board: what it is for', 'Bugs found in the app, until fixed.'),
176
+ idle: text('What an agent does when the board has nothing for it', 'Look for new bugs.'),
177
+ cap: z
178
+ .strictObject({
179
+ on: flag('Whether agents add items only while few wait for the person', false),
180
+ n: z.number().meta(about('How many may wait for the person', 3)),
181
+ })
182
+ .meta(about('The cap on the items agents add', { on: false, n: 3 })),
183
+ samples: z
184
+ .array(z.string())
185
+ .meta(about('Titles of the sample items previews draw', ['Login fails on Safari'], [])),
186
+ template: text('The template it was copied from, for the record', 'bugs').optional(),
187
+ split: z
188
+ .strictObject({
189
+ board: idOf('The board (hidden id) its items divide into, or same', 'same'),
190
+ always: flag('Whether a part is never created alone', false),
191
+ })
192
+ .meta(about('"Se divide en": the board each item divides into', { board: 'same', always: false }))
193
+ .optional(),
194
+ madeWith: ids('The boards (hidden ids) a template made with this one', ['bbugs']).optional(),
195
+ analysis: z
196
+ .strictObject({
197
+ effort: idOf('The field (part id) that says how much work an item is', 'feffort').optional(),
198
+ risk: idOf('The field (part id) that says how risky an item is to do', 'frisk').optional(),
199
+ impact: idOf('The field (part id) that says how much an item matters', 'fseverity').optional(),
200
+ area: idOf('The field (part id) that says where an item belongs', 'farea').optional(),
201
+ due: idOf('The date field (part id) an item is due by', 'fdue').optional(),
202
+ })
203
+ .meta(about('Which field plays each role of the analysis views: effort, risk and impact read a level, a number or a choice (its options in order are the scale); area a choice, several or a short text; due a date. The matrix shows once two of effort, risk and impact are mapped', { effort: 'feffort', risk: 'frisk', impact: 'fseverity' }))
204
+ .optional(),
205
+ drop: z
206
+ .strictObject({
207
+ by: z
208
+ .enum(['page', 'anyone'], { error: 'must be "page" or "anyone"' })
209
+ .meta(about('Who may drop an item: only from its page, or anyone (an agent too, asked to)', 'anyone')),
210
+ motives: z
211
+ .array(z
212
+ .strictObject({
213
+ id: z
214
+ .string()
215
+ .regex(STATE_KEY, 'is not a motive id: lowercase letters, digits and _, starting with a letter')
216
+ .meta(about('The hidden id of the motive', 'wont_fix')),
217
+ name: text('What the motive reads', "Won't fix"),
218
+ })
219
+ .meta(about('A motive a drop names', { id: 'wont_fix', name: "Won't fix" })))
220
+ .meta(about('The motives a drop names', [{ id: 'duplicate', name: 'Duplicate' }], [])),
221
+ })
222
+ .default({ by: 'anyone', motives: [] })
223
+ .meta(about('Who may drop an item, and the motives a drop names', { by: 'anyone', motives: [] })),
224
+ list: z
225
+ .strictObject({
226
+ as: z.enum(['list', 'table']).meta(about('How the published list shows its items', 'list')),
227
+ group: idOf('What it groups by: a choice, level or yesno part (id), step or motive', 'step').optional(),
228
+ })
229
+ .default({ as: 'list' })
230
+ .meta(about('How the published list shows its items', { as: 'list' })),
231
+ })
232
+ .meta({
233
+ title: 'Otea board',
234
+ description: 'A board definition (board.json): what `otea board draft <id>` prints and `otea board draft <id> --file board.json` reads.',
235
+ });
236
+ // The JSON Schema of board.json, published as schemas/board.schema.json: what an agent writes, so
237
+ // a setting that has a default may be left out.
238
+ export function boardJsonSchema() {
239
+ return z.toJSONSchema(definitionSchema, { io: 'input' });
240
+ }
241
+ let published;
242
+ export function parseDefinition(input) {
243
+ const { raw, notes } = anyAgent(input);
244
+ const result = definitionSchema.safeParse(raw);
245
+ if (!result.success) {
246
+ published ??= boardJsonSchema();
247
+ return { ok: false, problems: shapeProblems(raw, result.error.issues, published) };
248
+ }
249
+ const definition = result.data;
250
+ const misfiled = Object.entries(definition.parts)
251
+ .filter(([key, value]) => key !== value.id)
252
+ .map(([key, value]) => problem(raw, ['parts', key, 'id'], `the part says its id is ${value.id}`));
253
+ if (misfiled.length > 0)
254
+ return { ok: false, problems: misfiled };
255
+ const clashes = idClashes(raw, definition);
256
+ if (clashes.length > 0)
257
+ return { ok: false, problems: clashes };
258
+ return notes.length > 0 ? { ok: true, definition, notes } : { ok: true, definition };
259
+ }
260
+ const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
261
+ // A board written before a step's doer was you or any agent, and its reviewer you, any agent or
262
+ // nobody, named one agent: {"agent": "claude-b"}. It reads as "any" (any agent does it; any agent
263
+ // but the one that did it reviews it), nothing else changing, with a note for each step it touched.
264
+ function anyAgent(input) {
265
+ if (!isRecord(input) || !Array.isArray(input.steps))
266
+ return { raw: input, notes: [] };
267
+ const notes = [];
268
+ const steps = input.steps.map((step, index) => {
269
+ if (!isRecord(step))
270
+ return step;
271
+ const out = { ...step };
272
+ for (const key of ['doer', 'reviewer']) {
273
+ const who = step[key];
274
+ if (!isRecord(who) || typeof who.agent !== 'string')
275
+ continue;
276
+ out[key] = 'any';
277
+ const name = typeof step.name === 'string' ? ` "${step.name}"` : '';
278
+ const now = key === 'doer'
279
+ ? `${who.agent} no longer does it: any agent does`
280
+ : `${who.agent} no longer reviews it: any agent does, never the one that did it`;
281
+ notes.push(`step ${index + 1}${name}: ${now} [steps.${index}.${key}]`);
282
+ }
283
+ return out;
284
+ });
285
+ return notes.length > 0 ? { raw: { ...input, steps }, notes } : { raw: input, notes };
286
+ }
287
+ // A problem at a place of the board, in the words of a shape error.
288
+ function problem(raw, path, words) {
289
+ return `${placeOf(raw, path)}: ${words} [${path.join('.')}]`;
290
+ }
291
+ // Ids the engine gives a meaning of its own: where a way or a send-back leads, the title, and the
292
+ // suffixes of a step's review states.
293
+ const RESERVED = new Set([DONE, DROPPED, SAME, TITLE, ...PLACES]);
294
+ const REVIEW_SUFFIX = /__(review|yours)$/;
295
+ // Ids a step or a part cannot take, though they have the shape of one: a reserved word, a state
296
+ // suffix, or a step id another step already has. The editor never makes them; a hand-written or an
297
+ // agent's board.json can.
298
+ function idClashes(raw, definition) {
299
+ const problems = [];
300
+ const seen = new Set();
301
+ definition.steps.forEach(({ id }, index) => {
302
+ const at = (words) => problems.push(problem(raw, ['steps', index, 'id'], words));
303
+ if (RESERVED.has(id))
304
+ at(`${id} is a word the board keeps for itself`);
305
+ else if (REVIEW_SUFFIX.test(id))
306
+ at('a step id cannot end in __review or __yours');
307
+ else if (seen.has(id))
308
+ at(`another step already has the id ${id}`);
309
+ else if (id in definition.parts)
310
+ at(`a field or evidence already has the id ${id}`);
311
+ seen.add(id);
312
+ });
313
+ for (const [id, part] of Object.entries(definition.parts)) {
314
+ if (RESERVED.has(id))
315
+ problems.push(problem(raw, ['parts', id], `${id} is a word the board keeps for itself`));
316
+ if (part.guard && part.kind !== 'branch')
317
+ problems.push(problem(raw, ['parts', id, 'guard'], 'only a branch field is protected'));
318
+ if (part.proof && part.kind !== 'check')
319
+ problems.push(problem(raw, ['parts', id, 'proof'], 'only a checklist asks for proof'));
320
+ }
321
+ const motives = new Set();
322
+ definition.drop.motives.forEach(({ id }, index) => {
323
+ if (motives.has(id))
324
+ problems.push(problem(raw, ['drop', 'motives', index, 'id'], `another motive already has the id ${id}`));
325
+ motives.add(id);
326
+ });
327
+ return problems;
328
+ }
329
+ // Reads a stored definition, which was checked when written: a failure here is a corrupt row.
330
+ export function readDefinition(json) {
331
+ const reading = parseDefinition(JSON.parse(json));
332
+ if (!reading.ok)
333
+ throw new Error(`Corrupt board definition: ${reading.problems.join('; ')}`);
334
+ return reading.definition;
335
+ }
@@ -0,0 +1,179 @@
1
+ import { isEvidenceKind } from './model.js';
2
+ const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
3
+ function child(node, key) {
4
+ if (!node)
5
+ return undefined;
6
+ if (typeof key === 'number')
7
+ return node.items;
8
+ const own = node.properties?.[key];
9
+ if (own)
10
+ return own;
11
+ if (isRecord(node.additionalProperties))
12
+ return node.additionalProperties;
13
+ for (const branch of node.anyOf ?? []) {
14
+ const found = child(branch, key);
15
+ if (found)
16
+ return found;
17
+ }
18
+ return undefined;
19
+ }
20
+ function nodeAt(schema, path) {
21
+ return path.reduce((node, key) => child(node, key), schema);
22
+ }
23
+ function valueAt(raw, path) {
24
+ return path.reduce((value, key) => Array.isArray(value) || isRecord(value)
25
+ ? value[key]
26
+ : undefined, raw);
27
+ }
28
+ function present(raw, path) {
29
+ const parent = valueAt(raw, path.slice(0, -1));
30
+ const key = path.at(-1);
31
+ if (key === undefined)
32
+ return raw !== undefined;
33
+ return (Array.isArray(parent) || isRecord(parent)) && Object.hasOwn(parent, key);
34
+ }
35
+ const named = (value) => {
36
+ const name = isRecord(value) ? value.name : undefined;
37
+ return typeof name === 'string' && name.trim() !== '' ? ` "${name}"` : '';
38
+ };
39
+ // One step of a path in the board's terms: step 2 "Fix", field "Steps" (fsteps), handoff 1.
40
+ function placeWord(raw, path, index) {
41
+ const key = path[index];
42
+ const parentKey = path[index - 1];
43
+ const value = valueAt(raw, path.slice(0, index + 1));
44
+ if (typeof key === 'number') {
45
+ const n = key + 1;
46
+ if (parentKey === 'steps')
47
+ return `step ${n}${named(value)}`;
48
+ if (parentKey === 'hand') {
49
+ const handed = isRecord(value) && typeof value.ref === 'string' ? ` (${value.ref})` : '';
50
+ return `handoff ${n}${handed}`;
51
+ }
52
+ if (parentKey === 'form')
53
+ return `form entry ${n}`;
54
+ if (parentKey === 'options')
55
+ return `choice ${n}${named(value)}`;
56
+ if (parentKey === 'motives')
57
+ return `motive ${n}${named(value)}`;
58
+ return `${String(parentKey)} entry ${n}`;
59
+ }
60
+ if (parentKey === 'parts' && index === 1) {
61
+ const kind = isRecord(value) ? value.kind : undefined;
62
+ const what = typeof kind === 'string' && isEvidenceKind(kind) ? 'evidence' : 'field';
63
+ return `${what}${named(value)} (${key})`;
64
+ }
65
+ return key;
66
+ }
67
+ // The place a path names, in the board's terms; the board itself for the root.
68
+ export function placeOf(raw, path) {
69
+ const words = [];
70
+ path.forEach((key, index) => {
71
+ // A list's own key reads through its entry: steps.1 is "step 2", not "steps › step 2".
72
+ const next = path[index + 1];
73
+ if (typeof key === 'string' && typeof next === 'number')
74
+ return;
75
+ if (key === 'parts' && index === 0 && path.length > 1)
76
+ return;
77
+ words.push(placeWord(raw, path, index));
78
+ });
79
+ return words.length === 0 ? 'the board' : words.join(' › ');
80
+ }
81
+ const quoted = (value) => {
82
+ const text = JSON.stringify(value) ?? String(value);
83
+ return text.length > 40 ? `${text.slice(0, 37)}...` : text;
84
+ };
85
+ function received(value) {
86
+ if (value === null)
87
+ return 'null';
88
+ if (Array.isArray(value))
89
+ return 'a list';
90
+ if (isRecord(value))
91
+ return 'an object';
92
+ return quoted(value);
93
+ }
94
+ const EXPECTED = {
95
+ string: 'a text',
96
+ number: 'a number',
97
+ boolean: 'true or false',
98
+ array: 'a list',
99
+ object: 'an object',
100
+ record: 'an object',
101
+ };
102
+ function oneOf(values) {
103
+ const words = values.map((value) => quoted(value));
104
+ return words.length < 2
105
+ ? (words[0] ?? '')
106
+ : `${words.slice(0, -1).join(', ')} or ${words.at(-1)}`;
107
+ }
108
+ // What the key is for and an example of it, from the published schema.
109
+ function aboutKey(node) {
110
+ if (!node?.description)
111
+ return '';
112
+ const example = node.examples?.find((value) => value !== '');
113
+ const shown = example === undefined ? '' : `, e.g. ${JSON.stringify(example)}`;
114
+ const description = node.description.charAt(0).toLowerCase() + node.description.slice(1);
115
+ return ` (${description}${shown})`;
116
+ }
117
+ function wrongValue(issue, value) {
118
+ // The schema's own words first: "is not an id: ..." or "must be ...".
119
+ if (issue.message.startsWith('is not'))
120
+ return `${received(value)} ${issue.message}`;
121
+ if (issue.message.startsWith('must'))
122
+ return `${issue.message}, not ${received(value)}`;
123
+ if (issue.code === 'invalid_type') {
124
+ const expected = EXPECTED[issue.expected ?? ''] ?? issue.expected ?? 'something else';
125
+ return `must be ${expected}, not ${received(value)}`;
126
+ }
127
+ if (issue.code === 'invalid_value' && issue.values) {
128
+ const choices = issue.values.length === 1 ? quoted(issue.values[0]) : `one of ${oneOf(issue.values)}`;
129
+ return `must be ${choices}, not ${received(value)}`;
130
+ }
131
+ if (issue.code === 'too_small')
132
+ return 'must not be empty';
133
+ return issue.message;
134
+ }
135
+ function knownKeys(node) {
136
+ const keys = Object.keys(node?.properties ?? {});
137
+ return keys.length === 0 ? '' : ` (it takes ${keys.join(', ')})`;
138
+ }
139
+ const listed = (words) => words.length < 2 ? (words[0] ?? '') : `${words.slice(0, -1).join(', ')} and ${words.at(-1)}`;
140
+ const at = (path) => (path.length === 0 ? '' : ` [${path.join('.')}]`);
141
+ // The issues of a parse, one line each; the keys missing from one object read as one line.
142
+ export function shapeProblems(raw, issues, schema) {
143
+ const root = schema;
144
+ const lines = [];
145
+ const missing = new Map();
146
+ for (const issue of issues) {
147
+ const path = issue.path.map((key) => (typeof key === 'symbol' ? String(key) : key));
148
+ if (issue.code === 'unrecognized_keys') {
149
+ const keys = (issue.keys ?? []).map((key) => `"${key}"`);
150
+ lines.push(`${placeOf(raw, path)}: ${keys.length === 1 ? 'a key' : 'keys'} a board does not know: ${listed(keys)}${knownKeys(nodeAt(root, path))}${at(path)}`);
151
+ continue;
152
+ }
153
+ const key = path.at(-1);
154
+ // A part keyed by an id that is not one: said as its id, which the key repeats.
155
+ const [keyIssue] = issue.code === 'invalid_key' ? (issue.issues ?? []) : [];
156
+ if (keyIssue) {
157
+ const id = [...path, 'id'];
158
+ lines.push(`${placeOf(raw, path)} › id: ${received(key)} ${keyIssue.message}${aboutKey(nodeAt(root, id))}${at(id)}`);
159
+ continue;
160
+ }
161
+ if (typeof key === 'string' && !present(raw, path)) {
162
+ const parent = path.slice(0, -1);
163
+ const group = missing.get(parent.join('.')) ?? { path: parent, keys: [] };
164
+ group.keys.push(key);
165
+ missing.set(parent.join('.'), group);
166
+ continue;
167
+ }
168
+ const value = valueAt(raw, path);
169
+ const what = path.length === 0 ? '' : aboutKey(nodeAt(root, path));
170
+ lines.push(`${placeOf(raw, path)}: ${wrongValue(issue, value)}${what}${at(path)}`);
171
+ }
172
+ const lacking = [...missing.values()].map(({ path, keys }) => {
173
+ const [only] = keys;
174
+ if (keys.length === 1 && only !== undefined)
175
+ return `${placeOf(raw, path)} lacks ${only}${aboutKey(nodeAt(root, [...path, only]))}${at([...path, only])}`;
176
+ return `${placeOf(raw, path)} lacks ${listed(keys)}${at(path)}`;
177
+ });
178
+ return [...lacking, ...lines];
179
+ }
@@ -0,0 +1,23 @@
1
+ // The two languages a template speaks, and the helpers its data is written with.
2
+ export const LANGS = ['en', 'es'];
3
+ export const w = (en, es) => ({ en, es });
4
+ export const EMPTY = w('', '');
5
+ export const TITLE_NAME = w('Title', 'Título');
6
+ // A level's values as a board in each language says them (Severidad: media), keyed as stored.
7
+ export const LEVEL_SAID = {
8
+ en: { low: 'low', medium: 'medium', high: 'high', critical: 'critical' },
9
+ es: { low: 'baja', medium: 'media', high: 'alta', critical: 'crítica' },
10
+ };
11
+ // An effort as the Matrix weighs it: a size, in order, never a level («crítica» reads as a
12
+ // priority). Its options and their keys, for a choice part.
13
+ export const EFFORT_SIZES = {
14
+ options: [
15
+ w('Small', 'Pequeño'),
16
+ w('Medium', 'Mediano'),
17
+ w('Large', 'Grande'),
18
+ w('Huge', 'Enorme'),
19
+ ],
20
+ optionKeys: ['s', 'm', 'l', 'xl'],
21
+ };
22
+ // A yes-or-no field's values, as the board says them.
23
+ export const YES_NO_SAID = { en: 'yes or no', es: 'sí or no' };