@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,208 @@
1
+ import { OteaError } from './errors.js';
2
+ // Typed links between two items of a project, across collections. Each is stored once, from one
3
+ // item to the other: `parent` from the child to its parent, `blocks` from the blocker to what it
4
+ // blocks, `duplicates` from the copy to the original, `implements` from the work to what it
5
+ // implements. `relates` has no direction.
6
+ export const RELATION_KINDS = ['parent', 'blocks', 'duplicates', 'implements', 'relates'];
7
+ // How a relation reads from one of its two items: stored kinds from the `from` side, their inverse
8
+ // from the `to` side.
9
+ export const RELATION_VIEWS = [
10
+ 'parent',
11
+ 'child',
12
+ 'blocks',
13
+ 'blocked_by',
14
+ 'duplicates',
15
+ 'duplicated_by',
16
+ 'implements',
17
+ 'implemented_by',
18
+ 'relates',
19
+ ];
20
+ const INVERSE = {
21
+ parent: 'child',
22
+ blocks: 'blocked_by',
23
+ duplicates: 'duplicated_by',
24
+ implements: 'implemented_by',
25
+ relates: 'relates',
26
+ };
27
+ // Kinds whose links may not loop back: a parent cannot descend from its child, and a blocker cannot
28
+ // wait, however far down the chain, on what it blocks.
29
+ const ACYCLIC = ['parent', 'blocks'];
30
+ export function parseRelationKind(kind) {
31
+ if (RELATION_KINDS.includes(kind))
32
+ return kind;
33
+ throw new OteaError('invalid_relation', `Unknown relation "${kind}" (relations: ${RELATION_KINDS.join(', ')})`);
34
+ }
35
+ // A symmetric relation is stored with its two ids in order, so either way names the same link.
36
+ export function normalizeRelation(relation) {
37
+ const { kind, from, to } = relation;
38
+ if (kind !== 'relates' || from <= to)
39
+ return { kind, from, to };
40
+ return { kind, from: to, to: from };
41
+ }
42
+ export function matchesRelation(stored, given) {
43
+ const a = normalizeRelation(stored);
44
+ const b = normalizeRelation(given);
45
+ return a.kind === b.kind && a.from === b.from && a.to === b.to;
46
+ }
47
+ export function viewOf(relation, id) {
48
+ if (relation.from === id)
49
+ return { kind: relation.kind, id: relation.to };
50
+ return { kind: INVERSE[relation.kind], id: relation.from };
51
+ }
52
+ export function describeRelation({ kind, from, to }) {
53
+ if (kind === 'parent')
54
+ return `${from} is a child of ${to}`;
55
+ if (kind === 'relates')
56
+ return `${from} relates to ${to}`;
57
+ return `${from} ${kind} ${to}`;
58
+ }
59
+ // The links of one kind leading from `start` to `goal`, following each from its `from` to its `to`;
60
+ // undefined when there is no such path.
61
+ function pathBetween(relations, start, goal) {
62
+ const via = new Map();
63
+ const pending = [start];
64
+ const seen = new Set(pending);
65
+ for (let at = pending.shift(); at !== undefined; at = pending.shift()) {
66
+ if (at === goal) {
67
+ const path = [];
68
+ for (let step = via.get(at); step; step = via.get(step.from))
69
+ path.unshift(step);
70
+ return path;
71
+ }
72
+ for (const relation of relations) {
73
+ if (relation.from !== at || seen.has(relation.to))
74
+ continue;
75
+ seen.add(relation.to);
76
+ via.set(relation.to, relation);
77
+ pending.push(relation.to);
78
+ }
79
+ }
80
+ return undefined;
81
+ }
82
+ function sameLink(stored, next) {
83
+ if (stored.kind !== next.kind)
84
+ return false;
85
+ if (matchesRelation(stored, next))
86
+ return true;
87
+ // A copy cannot also be the original of its original, nor work implement what implements it.
88
+ return !ACYCLIC.includes(next.kind) && stored.from === next.to && stored.to === next.from;
89
+ }
90
+ // The rules a new relation must keep, given every relation stored: no item related to itself, one
91
+ // link per pair and kind, at most one parent, and no loop in parents or in blocks.
92
+ export function assertCanRelate(existing, next) {
93
+ const { kind, from, to } = next;
94
+ if (from === to)
95
+ throw new OteaError('self_relation', `${from} cannot be related to itself`, {
96
+ kind: 'self_link',
97
+ item: from,
98
+ });
99
+ const same = existing.find((stored) => sameLink(stored, next));
100
+ if (same)
101
+ throw new OteaError('already_exists', `Already linked: ${describeRelation(same)}`, {
102
+ kind: 'already_linked',
103
+ });
104
+ if (kind === 'parent') {
105
+ const parent = existing.find((stored) => stored.kind === 'parent' && stored.from === from);
106
+ if (parent) {
107
+ throw new OteaError('parent_exists', `${from} already has a parent, ${parent.to}; unlink it first (an item has at most one parent)`, { kind: 'parent_exists', item: from, parent: parent.to });
108
+ }
109
+ }
110
+ if (!ACYCLIC.includes(kind))
111
+ return;
112
+ const loop = pathBetween(existing.filter((stored) => stored.kind === kind), to, from);
113
+ if (loop) {
114
+ throw new OteaError('relation_cycle', `${describeRelation(next)} would close a cycle: ${loop.map(describeRelation).join(', ')}`, { kind: 'link_cycle' });
115
+ }
116
+ }
117
+ // The items no cycle of blocks holds back: peeled off from those nothing blocks, as long as some are
118
+ // left. What remains sits in a cycle, or waits on one.
119
+ function unblockable(order, blocks) {
120
+ const waiting = new Map(order.map((id) => [id, 0]));
121
+ for (const { to } of blocks)
122
+ waiting.set(to, (waiting.get(to) ?? 0) + 1);
123
+ const free = new Set();
124
+ const pending = order.filter((id) => waiting.get(id) === 0);
125
+ for (let id = pending.pop(); id !== undefined; id = pending.pop()) {
126
+ free.add(id);
127
+ for (const { from, to } of blocks) {
128
+ if (from !== id)
129
+ continue;
130
+ const left = (waiting.get(to) ?? 0) - 1;
131
+ waiting.set(to, left);
132
+ if (left === 0)
133
+ pending.push(to);
134
+ }
135
+ }
136
+ return free;
137
+ }
138
+ // The items in the order their `blocks` allow: each comes right after what blocks it, which is pulled
139
+ // up before it. Stable (items keep the order given wherever blocks allow) and safe on cycles (what is
140
+ // caught in one, or waits on one, keeps its order at the end). Only links between the given items
141
+ // count. This is the order a brief lists its items in.
142
+ export function orderByBlocks(ids, relations) {
143
+ const order = [...new Set(ids)];
144
+ const inSet = new Set(order);
145
+ const blocks = relations.filter(({ kind, from, to }) => kind === 'blocks' && inSet.has(from) && inSet.has(to) && from !== to);
146
+ const free = unblockable(order, blocks);
147
+ const rank = new Map(order.map((id, index) => [id, index]));
148
+ const placed = [];
149
+ const done = new Set();
150
+ const place = (id) => {
151
+ if (done.has(id))
152
+ return;
153
+ done.add(id);
154
+ const blockers = blocks
155
+ .filter(({ to }) => to === id)
156
+ .map(({ from }) => from)
157
+ .sort((a, b) => (rank.get(a) ?? 0) - (rank.get(b) ?? 0));
158
+ for (const blocker of blockers)
159
+ place(blocker);
160
+ placed.push(id);
161
+ };
162
+ for (const id of order)
163
+ if (free.has(id))
164
+ place(id);
165
+ return [...placed, ...order.filter((id) => !free.has(id))];
166
+ }
167
+ export function childrenSummary(children) {
168
+ const summary = { total: children.length, open: 0, done: 0, discarded: 0 };
169
+ for (const { closes } of children) {
170
+ if (closes === undefined)
171
+ summary.open += 1;
172
+ else
173
+ summary[closes] += 1;
174
+ }
175
+ return summary;
176
+ }
177
+ function listOpen(items) {
178
+ return items.map((item) => `${item.id} (${item.state})`).join(', ');
179
+ }
180
+ // A state that declares `requires: children_closed` takes a parent only once none of its children
181
+ // is open, whatever the state's turn. Nothing ever moves the parent for them.
182
+ export function assertChildrenClosed(id, to, children) {
183
+ const open = children.filter(({ closes }) => closes === undefined);
184
+ if (open.length === 0)
185
+ return;
186
+ throw new OteaError('children_open', `${id} cannot move to "${to}" while ${open.length} of its ${children.length} children are open: ${listOpen(open)}`, {
187
+ kind: 'links_open',
188
+ item: id,
189
+ links: 'children',
190
+ open: open.map((child) => child.id),
191
+ total: children.length,
192
+ });
193
+ }
194
+ // The twin of children_closed: a state that declares `requires: blockers_closed` takes an item only
195
+ // once nothing that blocks it is open, in its own collection or another. Nothing moves it for them.
196
+ export function assertBlockersClosed(id, to, blockers) {
197
+ const open = blockers.filter(({ closes }) => closes === undefined);
198
+ if (open.length === 0)
199
+ return;
200
+ const are = open.length === 1 ? 'is' : 'are';
201
+ throw new OteaError('blockers_open', `${id} cannot move to "${to}" while ${open.length} of its ${blockers.length} blockers ${are} open: ${listOpen(open)}`, {
202
+ kind: 'links_open',
203
+ item: id,
204
+ links: 'blockers',
205
+ open: open.map((blocker) => blocker.id),
206
+ total: blockers.length,
207
+ });
208
+ }
@@ -0,0 +1,54 @@
1
+ // One remote, however it is written: `host/path` for a remote on a host, in its https, ssh, scp
2
+ // (`git@host:path`) or git form, without the user, port or trailing `.git`, the host lowercased
3
+ // (the path keeps its case, which a host may tell apart); a local remote by its path, with forward
4
+ // slashes and a lowercase drive letter.
5
+ export function normalizeRemoteUrl(url) {
6
+ let rest = url.trim().replaceAll('\\', '/');
7
+ let host = '';
8
+ const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(rest);
9
+ if (scheme) {
10
+ rest = rest.slice(scheme[0].length);
11
+ if (scheme[1]?.toLowerCase() !== 'file') {
12
+ const slash = rest.indexOf('/');
13
+ const authority = slash === -1 ? rest : rest.slice(0, slash);
14
+ host = authority.replace(/^.*@/, '').replace(/:\d*$/, '');
15
+ rest = slash === -1 ? '' : rest.slice(slash);
16
+ }
17
+ }
18
+ else {
19
+ // An scp-like `[user@]host:path`; a one-letter "host" is a Windows drive.
20
+ const scp = /^(?:[^@/]+@)?([^/:]{2,}):(.*)$/.exec(rest);
21
+ if (scp) {
22
+ host = scp[1] ?? '';
23
+ rest = scp[2] ?? '';
24
+ }
25
+ }
26
+ const path = rest.replace(/\/+$/, '').replace(/\.git$/i, '');
27
+ if (host)
28
+ return `${host.toLowerCase()}/${path.replace(/^\/+/, '')}`;
29
+ return path.replace(/^\/([a-z]:)/i, '$1').replace(/^[a-z]:/i, (drive) => drive.toLowerCase());
30
+ }
31
+ // What a project knows a repo by: its origin remote (`remote:<normalized URL>`), or its root
32
+ // commits (`root:<sha …>`) when it has no origin; null when it has neither (no remote, no commit).
33
+ export function repoIdentity({ remoteUrl, rootCommit }) {
34
+ if (remoteUrl)
35
+ return `remote:${normalizeRemoteUrl(remoteUrl)}`;
36
+ if (rootCommit)
37
+ return `root:${rootCommit}`;
38
+ return null;
39
+ }
40
+ // The same repo when the remote URL or the root commit matches; different when one of them could
41
+ // be compared and none matched; unknown when neither could be compared.
42
+ export function compareRepos(a, b) {
43
+ const pairs = [
44
+ [
45
+ a.remoteUrl && normalizeRemoteUrl(a.remoteUrl),
46
+ b.remoteUrl && normalizeRemoteUrl(b.remoteUrl),
47
+ ],
48
+ [a.rootCommit, b.rootCommit],
49
+ ];
50
+ const comparable = pairs.filter(([x, y]) => x && y);
51
+ if (comparable.length === 0)
52
+ return 'unknown';
53
+ return comparable.some(([x, y]) => x === y) ? 'same' : 'different';
54
+ }
@@ -0,0 +1,161 @@
1
+ import { parse } from 'yaml';
2
+ import { z } from 'zod';
3
+ import { EVIDENCE_ROLES } from './evidence.js';
4
+ import { valueProblem } from './fields.js';
5
+ import { RELATION_VIEWS } from './relations.js';
6
+ // Sample items: a few example items a preset carries in samples.yaml, beside preset.yaml, so Studio
7
+ // can draw the real detail, row, form and lanes from a draft. They never enter a collection or the
8
+ // database. Their evidence names files in the samples/ folder beside samples.yaml.
9
+ //
10
+ // A sample that does not fit the preset never stops it loading: what is wrong is noted against the
11
+ // preset, and the sample is drawn as best it can be (or left out, when it cannot be drawn at all).
12
+ export const SAMPLES_FILE = 'samples.yaml';
13
+ export const SAMPLES_DIR = 'samples';
14
+ // A plain file name in the samples folder: no folders, no way out of it.
15
+ export const SAMPLE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
16
+ const text = z.string().min(1);
17
+ const evidenceSchema = z.strictObject({
18
+ file: z.string().regex(SAMPLE_FILE, 'must be a file name in the samples folder'),
19
+ role: z.enum(EVIDENCE_ROLES).optional(),
20
+ module: text.optional(),
21
+ caption: text.optional(),
22
+ });
23
+ const relationSchema = z.strictObject({
24
+ kind: z.enum(RELATION_VIEWS),
25
+ id: text,
26
+ title: text,
27
+ type: text.optional(),
28
+ state: text.optional(),
29
+ });
30
+ const eventSchema = z.strictObject({
31
+ actor: z.enum(['human', 'agent']),
32
+ name: text,
33
+ event: text,
34
+ from: text.optional(),
35
+ to: text.optional(),
36
+ reason: text.optional(),
37
+ ago: z
38
+ .string()
39
+ .regex(/^\d+[mhd]$/, 'minutes, hours or days: 5m, 3h, 2d')
40
+ .optional(),
41
+ });
42
+ const sampleSchema = z.strictObject({
43
+ type: text.optional(),
44
+ id: text,
45
+ title: text,
46
+ state: text,
47
+ fields: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
48
+ evidence: z.array(evidenceSchema).optional(),
49
+ relations: z.array(relationSchema).optional(),
50
+ history: z.array(eventSchema).optional(),
51
+ });
52
+ const fileSchema = z.strictObject({ samples: z.array(z.unknown()) });
53
+ function note(code, message, path) {
54
+ return { code, level: 'warning', message, path: { section: 'samples', ...path } };
55
+ }
56
+ function issuesOf(error, at) {
57
+ return error.issues
58
+ .map((issue) => `${[at, ...issue.path.map(String)].join('.')}: ${issue.message}`)
59
+ .join('; ');
60
+ }
61
+ function typeFor(preset, name) {
62
+ if (name === undefined)
63
+ return preset.types.length === 1 ? preset.types[0] : undefined;
64
+ return preset.types.find((type) => type.name === name);
65
+ }
66
+ // The entry without the keys it leaves out.
67
+ function defined(entry) {
68
+ return Object.fromEntries(Object.entries(entry).filter(([, value]) => value !== undefined));
69
+ }
70
+ function readOne(raw, index, preset, files) {
71
+ const at = `samples[${index}]`;
72
+ const notes = [];
73
+ const type = typeFor(preset, raw.type);
74
+ if (!type) {
75
+ const names = preset.types.map(({ name }) => name).join(', ');
76
+ const message = raw.type === undefined
77
+ ? `${at}.type: missing; the preset has several types (${names})`
78
+ : `${at}.type: unknown type "${raw.type}" (types: ${names})`;
79
+ const path = raw.type === undefined ? { index } : { index, type: raw.type };
80
+ return { notes: [note('sample_unknown_type', message, path)] };
81
+ }
82
+ const { workflow } = type;
83
+ let { state } = raw;
84
+ if (!workflow.states.some(({ name }) => name === state)) {
85
+ const states = workflow.states.map(({ name }) => name).join(', ');
86
+ notes.push(note('sample_unknown_state', `${at}.state: "${state}" is not a state of ${type.name} (states: ${states}); drawn as ${workflow.initial}`, { index, type: type.name, state }));
87
+ state = workflow.initial;
88
+ }
89
+ const fields = Object.fromEntries(Object.entries(raw.fields ?? {}).map(([name, value]) => [name, String(value)]));
90
+ for (const [name, value] of Object.entries(fields)) {
91
+ const spec = type.fields[name];
92
+ const where = { index, type: type.name, field: name };
93
+ if (!spec) {
94
+ notes.push(note('sample_unknown_field', `${at}.fields.${name}: ${type.name} has no field "${name}"`, where));
95
+ continue;
96
+ }
97
+ const problem = valueProblem(name, spec, value);
98
+ if (problem)
99
+ notes.push(note('sample_invalid_value', `${at}.fields.${name}: ${problem}`, where));
100
+ }
101
+ const evidence = [];
102
+ (raw.evidence ?? []).forEach(({ file, role = 'single', module, caption }, position) => {
103
+ if (!files.has(file)) {
104
+ notes.push(note('sample_missing_file', `${at}.evidence[${position}].file: ${SAMPLES_DIR}/${file} does not exist`, { index, file }));
105
+ return;
106
+ }
107
+ evidence.push({
108
+ file,
109
+ role,
110
+ ...(module === undefined ? {} : { module }),
111
+ ...(caption === undefined ? {} : { caption }),
112
+ });
113
+ });
114
+ const sample = {
115
+ type: type.name,
116
+ id: raw.id,
117
+ title: raw.title,
118
+ state,
119
+ fields,
120
+ evidence,
121
+ relations: (raw.relations ?? []).map((relation) => defined(relation)),
122
+ history: (raw.history ?? []).map((event) => defined(event)),
123
+ };
124
+ return { sample, notes };
125
+ }
126
+ // Reads samples.yaml against the preset (or a draft of it) and the files of its samples folder.
127
+ // `text` is undefined when the preset has no samples.yaml.
128
+ export function readSamples(text, preset, files) {
129
+ if (text === undefined || text.trim() === '')
130
+ return { samples: [], notes: [] };
131
+ let value;
132
+ try {
133
+ value = parse(text);
134
+ }
135
+ catch (error) {
136
+ const message = `${SAMPLES_FILE}: invalid YAML: ${error.message.split('\n')[0]}`;
137
+ return { samples: [], notes: [note('sample_invalid', message, {})] };
138
+ }
139
+ const file = fileSchema.safeParse(value);
140
+ if (!file.success) {
141
+ return {
142
+ samples: [],
143
+ notes: [note('sample_invalid', issuesOf(file.error, SAMPLES_FILE), {})],
144
+ };
145
+ }
146
+ const present = new Set(files);
147
+ const reading = { samples: [], notes: [] };
148
+ file.data.samples.forEach((entry, index) => {
149
+ const raw = sampleSchema.safeParse(entry);
150
+ if (!raw.success) {
151
+ const message = issuesOf(raw.error, `samples[${index}]`);
152
+ reading.notes.push(note('sample_invalid', message, { index }));
153
+ return;
154
+ }
155
+ const { sample, notes } = readOne(raw.data, index, preset, present);
156
+ if (sample)
157
+ reading.samples.push(sample);
158
+ reading.notes.push(...notes);
159
+ });
160
+ return reading;
161
+ }
@@ -0,0 +1,68 @@
1
+ // How Otea searches what people wrote (topics, items' threads): by whole words, folding accents
2
+ // and plurals, so a search finds a text holding any of its words, the one holding the most first.
3
+ // Text as a search compares it: lower case, without accents (migración finds migracion).
4
+ const folded = (text) => text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
5
+ // Words a search skips, Spanish and English: too common to tell one text from another.
6
+ const COMMON_WORDS = new Set(('a al como con de del el en es esa ese eso esta este esto la las lo los mas no o para pero ' +
7
+ 'por que se si sin sobre su sus un una uno unos unas y ' +
8
+ 'an and are as at be by for how in is it of on or that the this to what with').split(' '));
9
+ // The words of a text as a search compares them: folded, split on anything not a letter or digit.
10
+ const wordsOf = (text) => folded(text)
11
+ .split(/[^\p{L}\p{N}]+/u)
12
+ .filter((word) => word !== '');
13
+ // A searched word and its singular, when it reads as a plural: envíos, envio; cases, case;
14
+ // paginaciones, paginacion. Short words stay as they are (mes, gas).
15
+ function formsOf(word) {
16
+ const forms = [word];
17
+ if (word.length > 3 && word.endsWith('s'))
18
+ forms.push(word.slice(0, -1));
19
+ if (word.length > 4 && word.endsWith('es'))
20
+ forms.push(word.slice(0, -2));
21
+ return forms;
22
+ }
23
+ // The words searched, without the common ones, unless they are all common.
24
+ export function searchWords(search) {
25
+ const words = [...new Set(wordsOf(search))];
26
+ const telling = words.filter((word) => !COMMON_WORDS.has(word));
27
+ return (telling.length > 0 ? telling : words).map(formsOf);
28
+ }
29
+ // Words too common to tie one text to another, besides COMMON_WORDS: what a to-do or an answer says
30
+ // whatever it is about (hace falta, todo, cuando; need, when).
31
+ const GENERAL_WORDS = new Set(('ahora algo alli aqui asi bien cada cual cuando desde donde entre era esta estan estar estas ' +
32
+ 'estos falta fue hace hacen hacer haces hago hasta hay haya mismo misma muy nada otra otras otro ' +
33
+ 'otros porque puede pueden quien quiero sera ser solo tambien tener tengo tiene tienen toda ' +
34
+ 'todas todo todos ' +
35
+ 'about after also before does done from have into just like make more most much need only ' +
36
+ 'other over some such than then there these they this those very want were when where which ' +
37
+ 'will would your ' +
38
+ // What any work request or bug says, whatever it is about (P6-R3-7): an error, a fix, a file.
39
+ 'agregar anadir arreglar arreglo cambiar cambio cambios dato datos error errores falla fallas ' +
40
+ 'fallo fallos nueva nuevas nuevo nuevos problema problemas quitar usar archivo archivos ' +
41
+ 'change changes data error errors fail fails failing file files issue issues problem ' +
42
+ 'problems remove').split(' '));
43
+ // The words a project's items say: those in at least a quarter of its items, and in three at
44
+ // least, are too common there to tie a topic to one of them (P6-R3-7: a project's own name, its
45
+ // domain's word, on every item).
46
+ export function commonWords(texts) {
47
+ const counts = new Map();
48
+ for (const text of texts) {
49
+ for (const word of new Set(wordsOf(text)))
50
+ counts.set(word, (counts.get(word) ?? 0) + 1);
51
+ }
52
+ const floor = Math.max(3, texts.length / 4);
53
+ return new Set([...counts].filter(([, n]) => n >= floor).map(([word]) => word));
54
+ }
55
+ // The telling words of a text, to tie it to another (a topic an item may have come from): none
56
+ // common, none shorter than four letters, so nothing rather than noise (P4-R2-7).
57
+ export function tellingWords(text) {
58
+ return [...new Set(wordsOf(text))]
59
+ .filter((word) => word.length >= 4 && !COMMON_WORDS.has(word) && !GENERAL_WORDS.has(word))
60
+ .map(formsOf);
61
+ }
62
+ // How many of the words searched a text holds. A word matches a whole word of the text, or the
63
+ // start of one when it has four letters or more (moto finds motos, pagin paginación).
64
+ export function wordsHeld(text, searched) {
65
+ const words = [...new Set(wordsOf(text))];
66
+ const holds = (form) => words.includes(form) || (form.length >= 4 && words.some((word) => word.startsWith(form)));
67
+ return searched.filter((forms) => forms.some(holds)).length;
68
+ }
@@ -0,0 +1,120 @@
1
+ const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
2
+ function decode(text) {
3
+ return text
4
+ .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, '$1')
5
+ .replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (whole, name) => {
6
+ if (name[0] === '#') {
7
+ const code = name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : Number(name.slice(1));
8
+ return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
9
+ }
10
+ return ENTITIES[name.toLowerCase()] ?? whole;
11
+ });
12
+ }
13
+ function attributes(text) {
14
+ const out = {};
15
+ for (const [, key, double, single] of text.matchAll(/([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
16
+ if (key)
17
+ out[key] = decode(double ?? single ?? '');
18
+ }
19
+ return out;
20
+ }
21
+ function totalsOf(cases) {
22
+ const totals = { passed: 0, failed: 0, skipped: 0 };
23
+ for (const c of cases)
24
+ totals[c.status] += 1;
25
+ return totals;
26
+ }
27
+ function parseJunit(text) {
28
+ if (!/<testsuites?\b/.test(text))
29
+ return null;
30
+ const cases = [];
31
+ // Each suite names the file its cases come from when a case does not.
32
+ for (const suite of text.matchAll(/<testsuite\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testsuite>)/g)) {
33
+ const suiteName = attributes(suite[1] ?? '').name ?? '';
34
+ for (const found of (suite[2] ?? '').matchAll(/<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g)) {
35
+ const attrs = attributes(found[1] ?? '');
36
+ const body = found[2] ?? '';
37
+ const failure = /<(failure|error)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/.exec(body);
38
+ const file = attrs.file ?? attrs.classname ?? suiteName;
39
+ const name = attrs.name ?? '';
40
+ if (failure) {
41
+ const said = decode(failure[3] ?? '').trim() || attributes(failure[2] ?? '').message || '';
42
+ cases.push({ file, name, status: 'failed', ...(said ? { message: said } : {}) });
43
+ }
44
+ else if (/<skipped\b/.test(body))
45
+ cases.push({ file, name, status: 'skipped' });
46
+ else
47
+ cases.push({ file, name, status: 'passed' });
48
+ }
49
+ }
50
+ return { format: 'junit', cases, totals: totalsOf(cases) };
51
+ }
52
+ const JSON_STATUS = {
53
+ passed: 'passed',
54
+ failed: 'failed',
55
+ pending: 'skipped',
56
+ skipped: 'skipped',
57
+ todo: 'skipped',
58
+ disabled: 'skipped',
59
+ };
60
+ function parseJson(text) {
61
+ let data;
62
+ try {
63
+ data = JSON.parse(text);
64
+ }
65
+ catch {
66
+ return null;
67
+ }
68
+ const results = data?.testResults;
69
+ if (!Array.isArray(results))
70
+ return null;
71
+ const cases = [];
72
+ for (const result of results) {
73
+ const file = typeof result?.name === 'string' ? result.name : '';
74
+ const assertions = Array.isArray(result?.assertionResults) ? result.assertionResults : [];
75
+ for (const a of assertions) {
76
+ const status = JSON_STATUS[String(a?.status)] ?? 'skipped';
77
+ const name = String(a?.fullName ?? a?.title ?? '');
78
+ const messages = Array.isArray(a?.failureMessages) ? a.failureMessages.map(String) : [];
79
+ const message = messages.join('\n').trim();
80
+ cases.push({ file, name, status, ...(status === 'failed' && message ? { message } : {}) });
81
+ }
82
+ }
83
+ return { format: 'json', cases, totals: totalsOf(cases) };
84
+ }
85
+ // The report a file holds, or null when it is not one.
86
+ export function parseTestReport(text) {
87
+ const start = text.trimStart();
88
+ if (start.startsWith('{'))
89
+ return parseJson(start);
90
+ if (start.startsWith('<'))
91
+ return parseJunit(start);
92
+ return null;
93
+ }
94
+ const keyOf = (c) => `${c.file}\u0000${c.name}`;
95
+ // What changed from one run to the next, case by case (a case is its file and name).
96
+ export function compareReports(before, after) {
97
+ const was = new Map(before.cases.map((c) => [keyOf(c), c]));
98
+ const now = new Set(after.cases.map(keyOf));
99
+ const change = {
100
+ newlyFailing: [],
101
+ stillFailing: [],
102
+ fixed: [],
103
+ added: [],
104
+ removed: before.cases.filter((c) => !now.has(keyOf(c))),
105
+ };
106
+ for (const c of after.cases) {
107
+ const old = was.get(keyOf(c));
108
+ if (!old)
109
+ change.added.push(c);
110
+ if (c.status === 'failed') {
111
+ if (old?.status === 'failed')
112
+ change.stillFailing.push(c);
113
+ else
114
+ change.newlyFailing.push(c);
115
+ }
116
+ else if (c.status === 'passed' && old?.status === 'failed')
117
+ change.fixed.push(c);
118
+ }
119
+ return change;
120
+ }
@@ -0,0 +1,8 @@
1
+ // A timestamp as every text of the CLI and the MCP tools says it: "2026-11-12 10:04 UTC". One
2
+ // clock for every agent and person, wherever each runs; --json keeps the full ISO timestamp.
3
+ export function timeText(iso) {
4
+ const ms = Date.parse(iso);
5
+ if (Number.isNaN(ms))
6
+ return iso;
7
+ return `${new Date(ms).toISOString().slice(0, 16).replace('T', ' ')} UTC`;
8
+ }