@otea/cli 0.0.0-stage → 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 +252 -2
  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 +73 -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,523 @@
1
+ import { CHOICE_KINDS, DONE, DROPPED, defaultWay, guardedBranch, isEvidence, motiveById, partOf, SAME, stepById, stepIndex, TITLE, } from './model.js';
2
+ const SUFFIX = { doing: '', review: '__review' };
3
+ // The person's review an older board kept apart (when its named agent reviewer had done the work
4
+ // itself): it reads as the step's review.
5
+ const YOURS = '__yours';
6
+ const MOTIVE_PREFIX = `${DROPPED}__`;
7
+ // The workflow state a position compiles to: the step id while doing, `<id>__review` for its
8
+ // review, `done` and `dropped` when closed, and `dropped__<motive>` for a discard with a motive.
9
+ export function stateOf(position) {
10
+ if ('closed' in position) {
11
+ if (position.closed === DROPPED && position.motive)
12
+ return MOTIVE_PREFIX + position.motive;
13
+ return position.closed;
14
+ }
15
+ return position.step + SUFFIX[position.phase];
16
+ }
17
+ export function positionOf(state) {
18
+ if (state === DONE || state === DROPPED)
19
+ return { closed: state };
20
+ if (state.startsWith(MOTIVE_PREFIX))
21
+ return { closed: DROPPED, motive: state.slice(MOTIVE_PREFIX.length) };
22
+ for (const suffix of [SUFFIX.review, YOURS]) {
23
+ if (state.endsWith(suffix))
24
+ return { step: state.slice(0, -suffix.length), phase: 'review' };
25
+ }
26
+ return { step: state, phase: 'doing' };
27
+ }
28
+ export function isClosed(position) {
29
+ return 'closed' in position;
30
+ }
31
+ function positionAt(target) {
32
+ return target === DONE ? { closed: DONE } : { step: target, phase: 'doing' };
33
+ }
34
+ // The ways out of a step: the default (the next step, or Hecho) first, then the alternatives that
35
+ // still lead somewhere later, each once. With the item's facts, a lead that holds is the default
36
+ // and the next step is left out unless the step lists it; without them, every way it may take.
37
+ export function waysOf(def, stepId, facts) {
38
+ const index = stepIndex(def, stepId);
39
+ const step = def.steps[index];
40
+ if (!step)
41
+ return [];
42
+ const later = (target) => target === DONE || stepIndex(def, target) > index;
43
+ const rest = step.ways.filter(later);
44
+ if (facts === undefined) {
45
+ const lead = step.lead && later(step.lead.to) ? [step.lead.to] : [];
46
+ return [...new Set([defaultWay(def, stepId), ...rest, ...lead])];
47
+ }
48
+ return [...new Set([leadOf(def, step, facts) ?? defaultWay(def, stepId), ...rest])];
49
+ }
50
+ // Where the step leads the item while its lead's value holds: a later step or Hecho.
51
+ export function leadOf(def, step, facts) {
52
+ const lead = step.lead;
53
+ if (!lead || !whenHolds(def, facts, lead.when.part, lead.when.value))
54
+ return undefined;
55
+ const later = lead.to === DONE || stepIndex(def, lead.to) > stepIndex(def, step.id);
56
+ return later ? lead.to : undefined;
57
+ }
58
+ // The earlier steps the doer may take the item back to ("o regresarlo a…"), in row order.
59
+ export function backWaysOf(def, stepId) {
60
+ const index = stepIndex(def, stepId);
61
+ const step = def.steps[index];
62
+ if (!step)
63
+ return [];
64
+ return def.steps
65
+ .slice(0, index)
66
+ .map(({ id }) => id)
67
+ .filter((id) => step.ways.includes(id));
68
+ }
69
+ export function turnAt(def, position) {
70
+ if (isClosed(position))
71
+ return { who: 'none' };
72
+ const step = stepById(def, position.step);
73
+ if (!step)
74
+ return { who: 'none' };
75
+ const who = position.phase === 'doing' ? step.doer : step.reviewer;
76
+ if (who === 'you')
77
+ return { who: 'you' };
78
+ if (who === 'any')
79
+ return { who: 'agent' };
80
+ return { who: 'none' };
81
+ }
82
+ // Whether the agent may take the step's work: any agent for an any-agent step, none for yours.
83
+ export function mayTake(def, stepId) {
84
+ return stepById(def, stepId)?.doer === 'any';
85
+ }
86
+ // Whether the performer may review the step where the item stands: the person always; an agent
87
+ // only on a step any agent reviews, and never a step it did in that round (`did`: the agents that
88
+ // did it), so another agent reviews it.
89
+ export function mayReview(def, position, by, did = []) {
90
+ if (isClosed(position) || position.phase === 'doing')
91
+ return false;
92
+ if (by.kind === 'human')
93
+ return true;
94
+ return stepById(def, position.step)?.reviewer === 'any' && !did.includes(by.name);
95
+ }
96
+ // The refs of what a handoff lacks besides parts: the note, the person's notes left unanswered, and
97
+ // each wait.
98
+ export const NOTE_REF = 'note';
99
+ export const NOTES_REF = 'notes';
100
+ export const WAIT_PARTS = 'wait:parts';
101
+ export const WAIT_BLOCKERS = 'wait:blockers';
102
+ function asList(value) {
103
+ if (Array.isArray(value))
104
+ return value.map(String);
105
+ if (typeof value !== 'string' || value.trim() === '')
106
+ return [];
107
+ try {
108
+ const parsed = JSON.parse(value);
109
+ if (Array.isArray(parsed))
110
+ return parsed.map(String);
111
+ }
112
+ catch {
113
+ // Not JSON: one value, or several joined by commas.
114
+ }
115
+ return value
116
+ .split(',')
117
+ .map((piece) => piece.trim())
118
+ .filter(Boolean);
119
+ }
120
+ function hasValue(part, value) {
121
+ if (value === undefined || value === null)
122
+ return false;
123
+ if (CHOICE_KINDS.includes(part.kind))
124
+ return asList(value).length > 0;
125
+ if (typeof value === 'string')
126
+ return value.trim() !== '';
127
+ if (typeof value === 'number')
128
+ return Number.isFinite(value);
129
+ return true;
130
+ }
131
+ // Whether a "required only when…" holds: the part it reads carries the value (one of them, for a
132
+ // multi). A yes-or-no reads `yes` and `no`.
133
+ export function whenHolds(def, facts, part, value) {
134
+ const read = partOf(def, part);
135
+ const given = facts.fields[part];
136
+ if (!read || given === undefined || given === null)
137
+ return false;
138
+ if (read.kind === 'yesno') {
139
+ const yes = given === true || given === 'yes' || given === 'true';
140
+ return value === 'yes' ? yes : !yes;
141
+ }
142
+ if (read.kind === 'multi')
143
+ return asList(given).includes(value);
144
+ return String(given) === value;
145
+ }
146
+ // A checklist that asks for proof with ticked points that have none, however the points were
147
+ // ticked (otea tick, or the field set by update).
148
+ function unprovedOf(part, facts, fresh) {
149
+ if (part.kind !== 'check' || !part.proof)
150
+ return [];
151
+ const value = facts.fields[part.id];
152
+ const ticked = new Set(hasValue(part, value) ? asList(value) : []);
153
+ const proved = new Set(facts.proofs?.[part.id] ?? []);
154
+ const points = part.options.filter(({ id }) => ticked.has(id) && !proved.has(id));
155
+ if (points.length === 0)
156
+ return [];
157
+ return [
158
+ { ref: part.id, part, reason: 'unproved', fresh, points: points.map(({ name }) => name) },
159
+ ];
160
+ }
161
+ // A part the step's handoff asks for: always, or when its condition holds.
162
+ function isAsked(def, facts, hand) {
163
+ if (hand.req === 'always')
164
+ return true;
165
+ return (hand.req === 'when' &&
166
+ hand.when !== undefined &&
167
+ whenHolds(def, facts, hand.when.part, hand.when.value));
168
+ }
169
+ function missingOf(def, step, facts) {
170
+ return step.hand.flatMap((hand) => {
171
+ const part = partOf(def, hand.ref);
172
+ if (!part)
173
+ return [];
174
+ // Not asked for here (optional, or its condition does not hold): nothing is missing, but a
175
+ // point ticked on a checklist that asks for proof still needs one.
176
+ if (!isAsked(def, facts, hand))
177
+ return unprovedOf(part, facts, false);
178
+ const fresh = hand.fresh && isEvidence(part);
179
+ if (isEvidence(part)) {
180
+ const attached = facts.evidence.filter((entry) => entry.part === part.id);
181
+ if (attached.length === 0)
182
+ return [{ ref: part.id, part, reason: 'missing', fresh }];
183
+ const since = facts.roundStartedAt;
184
+ if (fresh && since !== undefined && !attached.some((entry) => entry.at >= since))
185
+ return [{ ref: part.id, part, reason: 'not_new', fresh }];
186
+ return [];
187
+ }
188
+ const value = part.id === TITLE ? facts.fields.title : facts.fields[part.id];
189
+ if (!hasValue(part, value))
190
+ return [{ ref: part.id, part, reason: 'missing', fresh }];
191
+ if (part.kind === 'check') {
192
+ const ticked = new Set(asList(value));
193
+ if (part.options.some(({ id }) => !ticked.has(id)))
194
+ return [{ ref: part.id, part, reason: 'unchecked', fresh }];
195
+ return unprovedOf(part, facts, fresh);
196
+ }
197
+ return [];
198
+ });
199
+ }
200
+ // The waits of a step that still hold the item: its open parts, then what open blocks it.
201
+ export function openWaits(step, facts) {
202
+ const out = [];
203
+ if (step.waits.includes('parts')) {
204
+ const parts = facts.parts ?? [];
205
+ const open = parts.filter(({ closed }) => !closed);
206
+ if (open.length > 0)
207
+ out.push({
208
+ ref: WAIT_PARTS,
209
+ name: open[0]?.board ?? '',
210
+ reason: 'open',
211
+ fresh: false,
212
+ open,
213
+ total: parts.length,
214
+ });
215
+ }
216
+ if (step.waits.includes('blockers')) {
217
+ const open = (facts.blockers ?? []).filter(({ closed }) => !closed);
218
+ if (open.length > 0)
219
+ out.push({ ref: WAIT_BLOCKERS, name: '', reason: 'open', fresh: false, open });
220
+ }
221
+ return out;
222
+ }
223
+ // How many of the step's required handoff deliverables are in (`done`), of how many it asks for
224
+ // now (`of`): its parts required always, and those required when a value holds that does. The
225
+ // handoff note is not one: it is written at the handoff.
226
+ export function deliverables(def, stepId, facts) {
227
+ const step = stepById(def, stepId);
228
+ if (!step)
229
+ return { done: 0, of: 0 };
230
+ const asked = step.hand.filter((hand) => partOf(def, hand.ref) && isAsked(def, facts, hand));
231
+ const refs = new Set(asked.map(({ ref }) => ref));
232
+ const missing = missingOf(def, step, facts).filter(({ ref }) => refs.has(ref));
233
+ return { done: asked.length - missing.length, of: asked.length };
234
+ }
235
+ // What the step's handoff still lacks: the parts in the order the step lists them, then the note,
236
+ // then the person's notes still unanswered, then what it waits for.
237
+ export function handoffCheck(def, stepId, facts) {
238
+ const step = stepById(def, stepId);
239
+ if (!step)
240
+ return { ok: false, missing: [] };
241
+ const missing = missingOf(def, step, facts).map(({ ref, part, reason, fresh, points }) => ({
242
+ ref,
243
+ name: part.name,
244
+ reason,
245
+ fresh,
246
+ ...(points === undefined ? {} : { points }),
247
+ }));
248
+ const sentBack = step.note.req !== 'always' && facts.sentBack === true;
249
+ if ((step.note.req === 'always' || sentBack) && !facts.note?.trim())
250
+ missing.push({
251
+ ref: NOTE_REF,
252
+ name: NOTE_REF,
253
+ reason: 'missing',
254
+ fresh: true,
255
+ hint: step.note.hint,
256
+ ...(sentBack ? { sentBack } : {}),
257
+ });
258
+ if (facts.unanswered && facts.unanswered.length > 0)
259
+ missing.push({
260
+ ref: NOTES_REF,
261
+ name: NOTES_REF,
262
+ reason: 'missing',
263
+ fresh: false,
264
+ notes: [...facts.unanswered],
265
+ });
266
+ missing.push(...openWaits(step, facts));
267
+ return { ok: missing.length === 0, missing };
268
+ }
269
+ // How a refused handoff is answered: missing parts or the note lead (missing_fields); otherwise
270
+ // the open parts (children_open), else what blocks it (blockers_open).
271
+ export function refusalCode(missing) {
272
+ if (missing.some(({ reason }) => reason !== 'open'))
273
+ return 'missing_fields';
274
+ return missing.some(({ ref }) => ref === WAIT_PARTS) ? 'children_open' : 'blockers_open';
275
+ }
276
+ function mayDo(step, by) {
277
+ return step.doer === 'any' || by.kind === 'human';
278
+ }
279
+ // A handoff from the doing phase: refused while something required is missing; otherwise to the
280
+ // review, or, with no reviewer, along the way picked (the default when none is). A way back to an earlier step needs a reason and nothing else: giving up
281
+ // has nothing to hand, and nobody reviews it.
282
+ export function handoff(def, position, facts, options) {
283
+ if (isClosed(position) || position.phase !== 'doing')
284
+ return { ok: false, code: 'not_doing' };
285
+ const step = stepById(def, position.step);
286
+ if (!step)
287
+ return { ok: false, code: 'unknown_step' };
288
+ if (!mayDo(step, options.by))
289
+ return { ok: false, code: 'not_yours' };
290
+ if (options.way !== undefined && backWaysOf(def, step.id).includes(options.way)) {
291
+ if (!options.reason?.trim())
292
+ return { ok: false, code: 'reason_required' };
293
+ return { ok: true, to: { step: options.way, phase: 'doing' }, back: true };
294
+ }
295
+ const ways = waysOf(def, step.id, facts);
296
+ if (options.way !== undefined && !ways.includes(options.way))
297
+ return { ok: false, code: 'bad_way' };
298
+ const check = handoffCheck(def, step.id, facts);
299
+ if (!check.ok)
300
+ return { ok: false, code: 'missing', missing: check.missing };
301
+ if (step.reviewer === 'none')
302
+ return { ok: true, to: positionAt(options.way ?? ways[0] ?? DONE) };
303
+ return { ok: true, to: { step: step.id, phase: 'review' } };
304
+ }
305
+ // Whether the agent reviewing did the round itself: nobody reviews their own work.
306
+ function ownWork(by, did = []) {
307
+ return by?.kind === 'agent' && did.includes(by.name);
308
+ }
309
+ // An approval from a review: along the way picked, or the default. With the item's facts, what the
310
+ // step waits for is checked again: a part reopened during the review stops the approval. `by`: who
311
+ // approves; an agent that did the round (facts.did) is refused.
312
+ export function approve(def, position, way, facts, by) {
313
+ if (isClosed(position) || position.phase === 'doing')
314
+ return { ok: false, code: 'not_review' };
315
+ if (ownWork(by, facts?.did))
316
+ return { ok: false, code: 'own_work' };
317
+ const ways = waysOf(def, position.step, facts);
318
+ if (ways.length === 0)
319
+ return { ok: false, code: 'unknown_step' };
320
+ if (way !== undefined && !ways.includes(way))
321
+ return { ok: false, code: 'bad_way' };
322
+ const step = stepById(def, position.step);
323
+ const waits = step && facts ? openWaits(step, facts) : [];
324
+ if (waits.length > 0)
325
+ return { ok: false, code: 'missing', missing: waits };
326
+ return { ok: true, to: positionAt(way ?? ways[0] ?? DONE) };
327
+ }
328
+ // Where a send-back lands: the step's `back`, this step or an earlier one, as its next round.
329
+ export function backTarget(def, stepId) {
330
+ const step = stepById(def, stepId);
331
+ if (!step || step.back === SAME)
332
+ return stepId;
333
+ const back = stepIndex(def, step.back);
334
+ return back >= 0 && back <= stepIndex(def, stepId) ? step.back : stepId;
335
+ }
336
+ // A send-back (Devolver, or an agent reviewer's Pedir otra ronda) from a review; never by the agent
337
+ // that did the round.
338
+ export function sendBack(def, position, options = {}) {
339
+ if (isClosed(position) || position.phase === 'doing')
340
+ return { ok: false, code: 'not_review' };
341
+ if (ownWork(options.by, options.did))
342
+ return { ok: false, code: 'own_work' };
343
+ if (!stepById(def, position.step))
344
+ return { ok: false, code: 'unknown_step' };
345
+ return { ok: true, to: { step: backTarget(def, position.step), phase: 'doing' } };
346
+ }
347
+ // Where a new item starts: the first step, or the step after it when the first is skipped for an
348
+ // item created with everything its Entrega asks for (only a first step nobody reviews, and never
349
+ // while its lead holds: the item is that step's own). Only at creation: a send-back into that step
350
+ // never skips it.
351
+ export function initialPosition(def, facts) {
352
+ const first = def.steps[0];
353
+ if (!first)
354
+ return { position: { closed: DONE }, skipped: false };
355
+ const start = { step: first.id, phase: 'doing' };
356
+ if (!first.skipWhenReady || first.reviewer !== 'none')
357
+ return { position: start, skipped: false };
358
+ if (leadOf(def, first, facts) !== undefined)
359
+ return { position: start, skipped: false };
360
+ if (missingOf(def, first, facts).length > 0)
361
+ return { position: start, skipped: false };
362
+ return { position: positionAt(defaultWay(def, first.id)), skipped: true };
363
+ }
364
+ // A discard (Descartar): always with a reason, and with one of the board's motives when it has any.
365
+ // An agent drops only while doing a step that lets its doer drop; a relay only on a board where the
366
+ // person may discard through an agent.
367
+ export function drop(def, position, options) {
368
+ if (isClosed(position))
369
+ return { ok: false, code: 'not_open' };
370
+ if (options.via === 'agent') {
371
+ const step = stepById(def, position.step);
372
+ const may = step !== undefined &&
373
+ step.doerMayDrop &&
374
+ step.doer !== 'you' &&
375
+ position.phase === 'doing' &&
376
+ mayDo(step, { kind: 'agent', name: options.by.name });
377
+ if (!may)
378
+ return { ok: false, code: 'not_droppable' };
379
+ }
380
+ if (options.via === 'relay' && def.drop.by === 'page')
381
+ return { ok: false, code: 'not_relayable' };
382
+ if (!options.reason?.trim())
383
+ return { ok: false, code: 'reason_required' };
384
+ if (def.drop.motives.length === 0)
385
+ return { ok: true, to: { closed: DROPPED } };
386
+ if (!options.motive || !motiveById(def, options.motive))
387
+ return { ok: false, code: 'motive_required' };
388
+ return { ok: true, to: { closed: DROPPED, motive: options.motive } };
389
+ }
390
+ // A last step an agent does with nobody reviewing, reached only from steps the person closes
391
+ // (approves, or does with nobody reviewing): the person's approval already said the work is good,
392
+ // so the agent lands it (merges it) and closes the item as Done itself.
393
+ export function isLandStep(def, stepId) {
394
+ const step = stepById(def, stepId);
395
+ if (!step || step.doer === 'you' || step.reviewer !== 'none')
396
+ return false;
397
+ if (!waysOf(def, stepId).includes(DONE))
398
+ return false;
399
+ const into = def.steps.filter((other) => other.id !== stepId && waysOf(def, other.id).includes(stepId));
400
+ const closer = (other) => (other.reviewer === 'none' ? other.doer : other.reviewer);
401
+ return into.length > 0 && into.every((other) => closer(other) === 'you');
402
+ }
403
+ // The board's land step, when it has one: where an agent merges what the person approved, so on
404
+ // such a board a Done item's branch is in already.
405
+ export function landStepOf(def) {
406
+ return def.steps.find((step) => isLandStep(def, step.id));
407
+ }
408
+ // Where a Done item whose branch is not merged yet reopens: the last step, in board order, that
409
+ // pushes its protected branch, so the branch can change (a PR that conflicts after another merged)
410
+ // and the change goes through review again. Undefined on a board that protects no branch.
411
+ export function reopenStep(def) {
412
+ const pushes = new Set(guardedBranch(def)?.guard.push ?? []);
413
+ return def.steps.findLast((step) => pushes.has(step.id))?.id;
414
+ }
415
+ // Whether the item's protected branch may take the action where the item stands: a push only while
416
+ // one of the guard's steps is being done (never during its review), a merge only once it is Hecho.
417
+ export function gateAt(def, position, action) {
418
+ const branch = guardedBranch(def);
419
+ if (!branch)
420
+ return { allowed: true, why: 'unguarded' };
421
+ if (action === 'merge') {
422
+ const done = isClosed(position) && position.closed === DONE;
423
+ if (done)
424
+ return { allowed: true, why: 'done' };
425
+ const landing = !isClosed(position) && position.phase === 'doing' && isLandStep(def, position.step);
426
+ return landing ? { allowed: true, why: 'landing' } : { allowed: false, why: 'not_done' };
427
+ }
428
+ if (isClosed(position))
429
+ return { allowed: false, why: 'closed' };
430
+ if (!branch.guard.push.includes(position.step))
431
+ return { allowed: false, why: 'not_push_step' };
432
+ if (position.phase !== 'doing')
433
+ return { allowed: false, why: 'review' };
434
+ return { allowed: true, why: 'doing' };
435
+ }
436
+ export function roundsOf(def, initial, createdAt, transitions) {
437
+ const out = { rounds: {}, startedAt: {}, dips: [] };
438
+ const enter = (stepId, at) => {
439
+ out.rounds[stepId] = (out.rounds[stepId] ?? 0) + 1;
440
+ out.startedAt[stepId] = at;
441
+ };
442
+ const first = positionOf(initial);
443
+ if (!isClosed(first))
444
+ enter(first.step, createdAt);
445
+ for (const { from, to, at, quiet } of transitions) {
446
+ const target = positionOf(to);
447
+ if (isClosed(target) || target.phase !== 'doing')
448
+ continue;
449
+ if (quiet) {
450
+ if (out.rounds[target.step] === undefined)
451
+ enter(target.step, at);
452
+ continue;
453
+ }
454
+ const source = positionOf(from);
455
+ if (!isClosed(source) && source.step === target.step && source.phase === 'doing')
456
+ continue;
457
+ enter(target.step, at);
458
+ // A reopen: a closed item taken back to a step, a loop from Done for the route to draw.
459
+ if (isClosed(source))
460
+ out.dips.push({ from: DONE, to: target.step, at, reopened: true });
461
+ // A send-back from a review (to this step or an earlier one), or the doer taking it back.
462
+ if (!isClosed(source)) {
463
+ const from = stepIndex(def, source.step);
464
+ const to = stepIndex(def, target.step);
465
+ if (source.phase !== 'doing' ? to <= from : to < from)
466
+ out.dips.push({ from: source.step, to: target.step, at });
467
+ }
468
+ }
469
+ return out;
470
+ }
471
+ // The move that started the step's current round when it was a reopen (the item was closed and was
472
+ // taken back to the step), as its index in `transitions`; -1 when the round began any other way.
473
+ export function reopenedAt(transitions, stepId) {
474
+ for (let index = transitions.length - 1; index >= 0; index -= 1) {
475
+ const move = transitions[index];
476
+ if (!move || move.quiet)
477
+ continue;
478
+ const target = positionOf(move.to);
479
+ if (isClosed(target) || target.phase !== 'doing' || target.step !== stepId)
480
+ continue;
481
+ const source = positionOf(move.from);
482
+ if (!isClosed(source) && source.step === stepId && source.phase === 'doing')
483
+ continue;
484
+ return isClosed(source) ? index : -1;
485
+ }
486
+ return -1;
487
+ }
488
+ // The move that started the step's current round when it was a send-back (from a review of this
489
+ // step or a later one), as its index in `transitions`; -1 when the round began any other way.
490
+ export function sentBackAt(def, transitions, stepId) {
491
+ for (let index = transitions.length - 1; index >= 0; index -= 1) {
492
+ const move = transitions[index];
493
+ if (!move || move.quiet)
494
+ continue;
495
+ const target = positionOf(move.to);
496
+ if (isClosed(target) || target.phase !== 'doing' || target.step !== stepId)
497
+ continue;
498
+ const source = positionOf(move.from);
499
+ if (isClosed(source))
500
+ return -1;
501
+ if (source.step === stepId && source.phase === 'doing')
502
+ continue;
503
+ const review = source.phase !== 'doing';
504
+ return review && stepIndex(def, stepId) <= stepIndex(def, source.step) ? index : -1;
505
+ }
506
+ return -1;
507
+ }
508
+ // What a step starts with: the title, the creation form and everything handed off before it, each
509
+ // once, with the step that handed it off.
510
+ export function startsWith(def, stepId) {
511
+ const out = [
512
+ { ref: TITLE },
513
+ ...def.form.map(({ ref }) => ({ ref })),
514
+ ];
515
+ const index = stepIndex(def, stepId);
516
+ for (const step of def.steps.slice(0, Math.max(0, index))) {
517
+ for (const { ref } of step.hand) {
518
+ if (!out.some((entry) => entry.ref === ref))
519
+ out.push({ ref, from: step.id });
520
+ }
521
+ }
522
+ return out.filter(({ ref }) => partOf(def, ref) !== undefined);
523
+ }
@@ -0,0 +1,46 @@
1
+ import { startsWith } from './engine.js';
2
+ import { mentionedRefs } from './mentions.js';
3
+ import { isEvidence, partOf } from './model.js';
4
+ // Words that ask for something to be attached, in English and Spanish.
5
+ const ATTACH = /\b(adjunt|attach|evidenc|screenshot|captura)/i;
6
+ // The instructions the step's agents read: the doer's when an agent does it, the reviewer's when an
7
+ // agent reviews it.
8
+ function readBy(step) {
9
+ const doer = step.doer === 'you' ? [] : [step.instructions.take, step.instructions.before];
10
+ const review = step.reviewer === 'any' ? [step.instructions.review] : [];
11
+ return { doer, all: [...doer, ...review] };
12
+ }
13
+ export function instructionHints(def) {
14
+ const out = [];
15
+ for (const step of def.steps) {
16
+ const { doer, all } = readBy(step);
17
+ if (all.length === 0)
18
+ continue;
19
+ const params = { step: step.name.trim() };
20
+ if (def.about.trim() === '' && all.every((text) => text.trim() === '')) {
21
+ out.push({ code: 'instructions_missing', step: step.id, params });
22
+ continue;
23
+ }
24
+ const required = new Set(step.hand.filter(({ req }) => req !== 'no').map(({ ref }) => ref));
25
+ const carried = new Set([...startsWith(def, step.id).map(({ ref }) => ref), ...def.anytime]);
26
+ const asked = new Set();
27
+ for (const ref of doer.flatMap(mentionedRefs)) {
28
+ const part = partOf(def, ref);
29
+ if (!part || required.has(ref) || carried.has(ref) || asked.has(ref))
30
+ continue;
31
+ asked.add(ref);
32
+ out.push({
33
+ code: 'instructions_ask_part',
34
+ step: step.id,
35
+ params: { ...params, part: part.name.trim() },
36
+ });
37
+ }
38
+ const evidence = [...required].some((ref) => {
39
+ const part = partOf(def, ref);
40
+ return part !== undefined && isEvidence(part);
41
+ });
42
+ if (!evidence && doer.some((text) => ATTACH.test(text)))
43
+ out.push({ code: 'instructions_ask_evidence', step: step.id, params });
44
+ }
45
+ return out;
46
+ }