@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,541 @@
1
+ import { parse } from 'yaml';
2
+ import { z } from 'zod';
3
+ import { OteaError } from './errors.js';
4
+ import { closeNames, iconProblem } from './icons.js';
5
+ import { FIELD_MODULES, readLayout, SEVERITY_SCALE, } from './modules.js';
6
+ import { labelProblems, labelsSchema, presetNames, typeLabels, } from './preset-labels.js';
7
+ import { presetNotes } from './preset-notes.js';
8
+ import { AUTHORITIES, CLOSINGS, REQUIREMENTS, TURNS, } from './workflow.js';
9
+ export { FIELD_MODULES, SEVERITY_SCALE } from './modules.js';
10
+ // The type of a preset that declares no `types`: every item of it.
11
+ export const DEFAULT_TYPE = 'item';
12
+ export const VIEW_KINDS = ['list', 'board', 'grid'];
13
+ // The columns of the grid that every collection can draw, beside its fields.
14
+ export const BUILT_IN_COLUMNS = ['id', 'title', 'state', 'type', 'who', 'age'];
15
+ const NAME = /^[a-z0-9][a-z0-9-]*$/;
16
+ // The key of a field, state, gate or type: a board's part and step ids are checked by it too.
17
+ export const KEY = /^[a-z][a-z0-9_]*$/;
18
+ const fieldSchema = z.strictObject({
19
+ module: z.string(),
20
+ required: z.enum(['create', 'complete']).optional(),
21
+ values: z.array(z.string()).nonempty().optional(),
22
+ default: z.string().optional(),
23
+ label: z.string().trim().min(1).optional(),
24
+ });
25
+ const fieldsSchema = z.record(z.string().regex(KEY, 'field names must be snake_case'), fieldSchema);
26
+ const transitionSchema = z.strictObject({
27
+ from: z.union([z.string(), z.array(z.string()).nonempty()]),
28
+ to: z.string(),
29
+ by: z.enum(AUTHORITIES),
30
+ reason: z.literal('required').optional(),
31
+ // A board's land step: an agent closes the item as done after the person approved the step before.
32
+ land: z.literal(true).optional(),
33
+ });
34
+ const workflowSchema = z.strictObject({
35
+ initial: z.string(),
36
+ incomplete: z.string().optional(),
37
+ states: z.record(z.string().regex(KEY, 'state names must be snake_case'), z.strictObject({
38
+ turn: z.enum(TURNS),
39
+ closes: z.enum(CLOSINGS).optional(),
40
+ // One requirement, or a list of them: requires: [children_closed, blockers_closed].
41
+ requires: z
42
+ .union([z.enum(REQUIREMENTS), z.array(z.enum(REQUIREMENTS)).nonempty()])
43
+ .optional(),
44
+ // Deprecated: the former name of requires, read with the same meaning.
45
+ close_requires: z.enum(REQUIREMENTS).optional(),
46
+ })),
47
+ transitions: z.array(transitionSchema),
48
+ gates: z
49
+ .record(z.string().regex(KEY, 'gate actions must be snake_case'), z.array(z.string()).nonempty())
50
+ .optional(),
51
+ });
52
+ // Layouts are read by the module registry, which reports their problems by slot and position.
53
+ const layoutSchema = z.unknown();
54
+ const typeSchema = z.strictObject({
55
+ label: z.string().min(1),
56
+ icon: z.string().optional(),
57
+ fields: fieldsSchema.optional(),
58
+ workflow: workflowSchema.optional(),
59
+ layout: layoutSchema.optional(),
60
+ playbook: z.string().optional(),
61
+ children: z.array(z.string()).optional(),
62
+ root: z.boolean().optional(),
63
+ });
64
+ const presetSchema = z.strictObject({
65
+ preset: z.string().regex(NAME, 'must be lowercase letters, digits and dashes'),
66
+ preset_version: z.int().positive(),
67
+ playbook: z.string().optional(),
68
+ fields: fieldsSchema,
69
+ workflow: workflowSchema,
70
+ types: z.record(z.string().regex(KEY, 'type names must be snake_case'), typeSchema).optional(),
71
+ // The layout of the implicit type, in a preset without types.
72
+ layout: layoutSchema.optional(),
73
+ // The preset's icon, given to its collections; in a preset without types, also the implicit
74
+ // type's.
75
+ icon: z.string().optional(),
76
+ view: z
77
+ .strictObject({
78
+ kind: z.enum(VIEW_KINDS).optional(),
79
+ group_by: z.string().optional(),
80
+ columns: z.array(z.string()).nonempty().optional(),
81
+ })
82
+ .optional(),
83
+ labels: labelsSchema.optional(),
84
+ });
85
+ function isModule(module) {
86
+ return FIELD_MODULES.includes(module);
87
+ }
88
+ function fieldProblems(at, field) {
89
+ const problems = [];
90
+ if (!isModule(field.module)) {
91
+ problems.push(`${at}.module: unknown module "${field.module}" (official: ${FIELD_MODULES.join(', ')})`);
92
+ }
93
+ if (field.module === 'enum' && !field.values) {
94
+ problems.push(`${at}.values: required by the enum module`);
95
+ }
96
+ if (field.module !== 'enum' && field.values) {
97
+ problems.push(`${at}.values: only the enum module takes values`);
98
+ }
99
+ const values = valuesOf(field);
100
+ if (values && field.default !== undefined && !values.includes(field.default)) {
101
+ problems.push(`${at}.default: "${field.default}" is not one of ${values.join(', ')}`);
102
+ }
103
+ return problems;
104
+ }
105
+ function fieldsProblems(at, fields) {
106
+ return Object.entries(fields).flatMap(([name, field]) => fieldProblems(`${at}.${name}`, field));
107
+ }
108
+ // The values a field may take: an enum's own, or the severity scale.
109
+ function valuesOf(field) {
110
+ return field.module === 'severity' ? [...SEVERITY_SCALE] : field.values;
111
+ }
112
+ function titleProblems(title) {
113
+ if (!title)
114
+ return ['fields.title: missing; every preset needs a title field'];
115
+ const problems = [];
116
+ if (title.module !== 'text')
117
+ problems.push('fields.title: must use the text module');
118
+ if (title.required !== 'create')
119
+ problems.push('fields.title: must be required: create');
120
+ return problems;
121
+ }
122
+ function expand(workflow) {
123
+ return workflow.transitions.flatMap(({ from, to, by, reason }) => [from]
124
+ .flat()
125
+ .map((source) => ({ from: source, to, by, reasonRequired: reason === 'required' })));
126
+ }
127
+ function transitionProblems(at, workflow) {
128
+ const { states } = workflow;
129
+ const problems = [];
130
+ const seen = new Set();
131
+ workflow.transitions.forEach(({ from, to, by, land }, index) => {
132
+ const where = `${at}.transitions.${index}`;
133
+ for (const source of [from].flat()) {
134
+ if (!(source in states))
135
+ problems.push(`${where}.from: unknown state "${source}"`);
136
+ const key = JSON.stringify([source, to, by]);
137
+ if (seen.has(key))
138
+ problems.push(`${where}: duplicate transition "${source}" -> "${to}" by ${by}`);
139
+ seen.add(key);
140
+ if (source === to)
141
+ problems.push(`${where}: "${source}" -> "${to}" does not change state`);
142
+ // Agents never approve their own work: only a human may close an item as done, except when
143
+ // an agent lands what the person already approved.
144
+ if (by === 'agent' && states[to]?.closes === 'done' && !land) {
145
+ problems.push(`${where}: an agent cannot close an item as done ("${source}" -> "${to}"); use human or human-ui`);
146
+ }
147
+ }
148
+ if (!(to in states))
149
+ problems.push(`${where}.to: unknown state "${to}"`);
150
+ });
151
+ return problems;
152
+ }
153
+ function reachable(entries, transitions) {
154
+ const reached = new Set(entries);
155
+ const pending = [...entries];
156
+ for (let state = pending.pop(); state !== undefined; state = pending.pop()) {
157
+ for (const { from, to } of transitions) {
158
+ if (from === state && !reached.has(to)) {
159
+ reached.add(to);
160
+ pending.push(to);
161
+ }
162
+ }
163
+ }
164
+ return reached;
165
+ }
166
+ function stateProblems(at, workflow, transitions) {
167
+ const { initial, incomplete, states } = workflow;
168
+ const problems = [];
169
+ if (!(initial in states))
170
+ problems.push(`${at}.initial: unknown state "${initial}"`);
171
+ if (incomplete !== undefined && !(incomplete in states)) {
172
+ problems.push(`${at}.incomplete: unknown state "${incomplete}"`);
173
+ }
174
+ if (incomplete === initial)
175
+ problems.push(`${at}.incomplete: must differ from initial`);
176
+ const entries = [initial, incomplete ?? initial].filter((entry) => entry in states);
177
+ const reached = reachable(entries, transitions);
178
+ for (const [name, { turn, closes, requires, close_requires }] of Object.entries(states)) {
179
+ const where = `${at}.states.${name}`;
180
+ const leaves = transitions.some(({ from }) => from === name);
181
+ if (entries.length > 0 && !reached.has(name)) {
182
+ problems.push(`${where}: not reachable from the initial or incomplete state`);
183
+ }
184
+ if (turn === 'none' && leaves)
185
+ problems.push(`${where}: has turn none but outgoing transitions`);
186
+ if (turn !== 'none' && !leaves) {
187
+ problems.push(`${where}: has turn ${turn} but no outgoing transitions`);
188
+ }
189
+ if (turn === 'none' && closes === undefined) {
190
+ problems.push(`${where}.closes: required on a state with turn none (done or discarded)`);
191
+ }
192
+ if (turn !== 'none' && closes !== undefined) {
193
+ problems.push(`${where}.closes: only a state with turn none closes`);
194
+ }
195
+ if (requires !== undefined && close_requires !== undefined) {
196
+ problems.push(`${where}: declares both requires and close_requires; keep requires`);
197
+ }
198
+ if (Array.isArray(requires)) {
199
+ requires.forEach((requirement, index) => {
200
+ if (requires.indexOf(requirement) !== index) {
201
+ problems.push(`${where}.requires[${index}]: "${requirement}" is listed twice`);
202
+ }
203
+ });
204
+ }
205
+ }
206
+ return problems;
207
+ }
208
+ // close_requires still reads, as requires, but each use is reported until it is renamed.
209
+ function workflowWarnings(at, workflow, type) {
210
+ return Object.entries(workflow.states)
211
+ .filter(([, state]) => state.close_requires !== undefined && state.requires === undefined)
212
+ .map(([name, state]) => ({
213
+ code: 'deprecated_key',
214
+ level: 'warning',
215
+ message: `${at}.states.${name}.close_requires: deprecated; write requires: ${state.close_requires}`,
216
+ path: { section: 'states', ...(type ? { type } : {}), state: name },
217
+ }));
218
+ }
219
+ function presetWarnings(raw) {
220
+ const typed = Object.entries(raw.types ?? {}).flatMap(([name, { workflow }]) => workflow ? workflowWarnings(`types.${name}.workflow`, workflow, name) : []);
221
+ return [...workflowWarnings('workflow', raw.workflow), ...typed];
222
+ }
223
+ // Each gate lists states of its workflow, each once.
224
+ function gateProblems(at, workflow) {
225
+ return Object.entries(workflow.gates ?? {}).flatMap(([action, states]) => states.flatMap((state, index) => {
226
+ const where = `${at}.gates.${action}[${index}]`;
227
+ if (!(state in workflow.states))
228
+ return [`${where}: unknown state "${state}"`];
229
+ if (states.indexOf(state) !== index)
230
+ return [`${where}: "${state}" is listed twice`];
231
+ return [];
232
+ }));
233
+ }
234
+ function workflowProblems(at, workflow) {
235
+ const transitions = expand(workflow);
236
+ return [
237
+ ...transitionProblems(at, workflow),
238
+ ...stateProblems(at, workflow, transitions),
239
+ ...gateProblems(at, workflow),
240
+ ];
241
+ }
242
+ // A field required to complete needs an incomplete state to start in. `of` names the type when the
243
+ // workflow is the preset's but the field is the type's own.
244
+ function incompleteProblems(at, workflow, fields, of = '') {
245
+ if (workflow.incomplete !== undefined)
246
+ return [];
247
+ return Object.entries(fields)
248
+ .filter(([, field]) => field.required === 'complete')
249
+ .map(([name]) => `${at}.incomplete: missing, but field "${name}"${of} is required: complete`);
250
+ }
251
+ function toField(field) {
252
+ const spec = { module: field.module };
253
+ if (field.required)
254
+ spec.required = field.required;
255
+ const values = valuesOf(field);
256
+ if (values)
257
+ spec.values = [...values];
258
+ if (field.default !== undefined)
259
+ spec.default = field.default;
260
+ if (field.label !== undefined)
261
+ spec.label = field.label;
262
+ return spec;
263
+ }
264
+ function toFields(fields) {
265
+ return Object.fromEntries(Object.entries(fields).map(([name, field]) => [name, toField(field)]));
266
+ }
267
+ function toWorkflow(name, raw) {
268
+ const states = Object.entries(raw.states).map(([state, declared]) => {
269
+ const { turn, closes } = declared;
270
+ const spec = { name: state, turn };
271
+ if (closes !== undefined)
272
+ spec.closes = closes;
273
+ const requires = declared.requires ?? declared.close_requires;
274
+ if (typeof requires === 'string')
275
+ spec.requires = [requires];
276
+ else if (requires !== undefined)
277
+ spec.requires = [...requires];
278
+ return spec;
279
+ });
280
+ const workflow = { name, initial: raw.initial, states, transitions: expand(raw) };
281
+ if (raw.incomplete !== undefined)
282
+ workflow.incomplete = raw.incomplete;
283
+ if (raw.gates !== undefined)
284
+ workflow.gates = raw.gates;
285
+ return workflow;
286
+ }
287
+ // A preset declares a hierarchy once one of its types lists children.
288
+ function declaresHierarchy(types) {
289
+ return Object.values(types).some(({ children }) => children !== undefined);
290
+ }
291
+ function childProblems(types) {
292
+ const names = Object.keys(types);
293
+ return Object.entries(types).flatMap(([name, { children = [] }]) => children.flatMap((child, index) => {
294
+ const at = `types.${name}.children[${index}]`;
295
+ if (!names.includes(child))
296
+ return [`${at}: unknown type "${child}" (types: ${names.join(', ')})`];
297
+ if (children.indexOf(child) !== index)
298
+ return [`${at}: "${child}" is listed twice`];
299
+ return [];
300
+ }));
301
+ }
302
+ // Each loop once, from the first type it passes through in the order the preset declares them: a
303
+ // walk from a type goes only through the types declared after it, back to where it started.
304
+ function loopProblems(types) {
305
+ const names = Object.keys(types);
306
+ const childrenOf = (name) => (types[name]?.children ?? []).filter((child) => names.includes(child));
307
+ const problems = [];
308
+ names.forEach((start, first) => {
309
+ const walk = (path) => {
310
+ for (const child of new Set(childrenOf(path.at(-1) ?? start))) {
311
+ if (child === start) {
312
+ problems.push(`types.${start}.children: loop ${[...path, start].join(' -> ')}`);
313
+ }
314
+ else if (names.indexOf(child) > first && !path.includes(child)) {
315
+ walk([...path, child]);
316
+ }
317
+ }
318
+ };
319
+ walk([start]);
320
+ });
321
+ return problems;
322
+ }
323
+ // A type that may not stand alone needs a type to hang under.
324
+ function rootProblems(types) {
325
+ return Object.entries(types)
326
+ .filter(([, { root }]) => root === false)
327
+ .filter(([name]) => !Object.values(types).some(({ children }) => children?.includes(name)))
328
+ .map(([name]) => `types.${name}.root: false, but no type lists ${name} in its children`);
329
+ }
330
+ function hierarchyProblems(types) {
331
+ return [...childProblems(types), ...loopProblems(types), ...rootProblems(types)];
332
+ }
333
+ function iconProblems(at, icon) {
334
+ const problem = icon === undefined ? undefined : iconProblem(at, icon);
335
+ return problem ? [problem] : [];
336
+ }
337
+ function implicitType(raw, fields, workflow) {
338
+ const { layout, problems } = readLayout(raw.layout, fields, 'layout');
339
+ const type = { name: DEFAULT_TYPE, label: 'Item', fields, workflow, layout };
340
+ if (raw.icon !== undefined)
341
+ type.icon = raw.icon;
342
+ return { types: [type], problems: [...problems, ...iconProblems('icon', raw.icon)] };
343
+ }
344
+ function readTypes(raw, fields, workflow) {
345
+ const reading = { types: [], problems: [] };
346
+ const declared = Object.entries(raw.types ?? {});
347
+ if (declared.length === 0)
348
+ reading.problems.push('types: declare at least one type');
349
+ if (raw.layout !== undefined) {
350
+ reading.problems.push('layout: declare the layout of each type under types.<type>.layout');
351
+ }
352
+ reading.problems.push(...iconProblems('icon', raw.icon));
353
+ const hierarchy = declaresHierarchy(raw.types ?? {});
354
+ reading.problems.push(...hierarchyProblems(raw.types ?? {}));
355
+ for (const [name, type] of declared) {
356
+ const at = `types.${name}`;
357
+ const own = type.fields ?? {};
358
+ for (const field of Object.keys(own)) {
359
+ if (field in raw.fields)
360
+ reading.problems.push(`${at}.fields.${field}: already declared by the preset`);
361
+ }
362
+ reading.problems.push(...fieldsProblems(`${at}.fields`, own));
363
+ if (type.workflow) {
364
+ reading.problems.push(...workflowProblems(`${at}.workflow`, type.workflow));
365
+ reading.problems.push(...incompleteProblems(`${at}.workflow`, type.workflow, { ...raw.fields, ...own }));
366
+ }
367
+ else {
368
+ reading.problems.push(...incompleteProblems('workflow', raw.workflow, own, ` of type ${name}`));
369
+ }
370
+ const typeFields = { ...fields, ...toFields(own) };
371
+ const { layout, problems } = readLayout(type.layout, typeFields, `${at}.layout`);
372
+ reading.problems.push(...problems, ...iconProblems(`${at}.icon`, type.icon));
373
+ const read = {
374
+ name,
375
+ label: type.label,
376
+ fields: typeFields,
377
+ workflow: type.workflow ? toWorkflow(`${raw.preset}:${name}`, type.workflow) : workflow,
378
+ layout,
379
+ };
380
+ if (type.icon !== undefined)
381
+ read.icon = type.icon;
382
+ if (type.playbook !== undefined)
383
+ read.playbook = type.playbook;
384
+ if (hierarchy) {
385
+ read.children = [...new Set(type.children ?? [])];
386
+ read.root = type.root ?? true;
387
+ }
388
+ reading.types.push(read);
389
+ }
390
+ return reading;
391
+ }
392
+ const GROUPS = ['turn', 'state', 'type'];
393
+ // A column holds one line: a field of these modules can be one.
394
+ const ONE_LINE = ['enum', 'severity', 'text'];
395
+ function moduleOf(types, name) {
396
+ return types.map((type) => type.fields[name]?.module).find((module) => module !== undefined);
397
+ }
398
+ // A grouping is turn, state, type, or a one-line field every type has (an enum, a severity, or
399
+ // free text, whose values come from the items); never the title, which every item has its own.
400
+ function groupProblems(groupBy, types) {
401
+ if (GROUPS.includes(groupBy))
402
+ return [];
403
+ if (groupBy === 'title')
404
+ return ['view.group_by: title cannot group (every item has its own)'];
405
+ if (types.every((type) => type.fields[groupBy])) {
406
+ const module = types
407
+ .map((type) => type.fields[groupBy]?.module ?? '')
408
+ .find((name) => !ONE_LINE.includes(name));
409
+ if (module === undefined)
410
+ return [];
411
+ return [
412
+ `view.group_by: ${groupBy} is ${module}; only one-line fields group (enum, severity, text)`,
413
+ ];
414
+ }
415
+ return [`view.group_by: "${groupBy}" is not turn, state, type or a one-line field of every type`];
416
+ }
417
+ // Without columns of its own, the grid shows the row slot's one-line fields between title and state.
418
+ function defaultColumns(types) {
419
+ const row = types.flatMap((type) => type.layout.row.flatMap(({ field }) => field !== undefined && ONE_LINE.includes(type.fields[field]?.module ?? '') ? [field] : []));
420
+ return ['id', 'title', ...new Set(row), 'state', 'who', 'age'];
421
+ }
422
+ function columnProblems(columns, types) {
423
+ const fields = [...new Set(types.flatMap((type) => Object.keys(type.fields)))];
424
+ const known = BUILT_IN_COLUMNS;
425
+ const problems = columns.flatMap((column, index) => {
426
+ const at = `view.columns[${index}]`;
427
+ if (columns.indexOf(column) !== index)
428
+ return [`${at}: "${column}" is listed twice`];
429
+ if (known.includes(column))
430
+ return [];
431
+ const module = moduleOf(types, column);
432
+ if (module === undefined) {
433
+ const close = closeNames(column, [...known, ...fields]);
434
+ const hint = close.length > 0 ? ` (did you mean ${close.join(', ')}?)` : '';
435
+ return [`${at}: unknown column "${column}"${hint}`];
436
+ }
437
+ if (!ONE_LINE.includes(module))
438
+ return [`${at}: ${column} is ${module}; a column holds one line`];
439
+ return [];
440
+ });
441
+ if (!columns.includes('title'))
442
+ problems.push('view.columns: title is always shown; list it');
443
+ return problems;
444
+ }
445
+ function readView(raw, types) {
446
+ const declared = raw.view?.columns;
447
+ const view = {
448
+ kind: raw.view?.kind ?? 'list',
449
+ groupBy: raw.view?.group_by ?? 'turn',
450
+ columns: declared ?? defaultColumns(types),
451
+ };
452
+ const problems = [
453
+ ...groupProblems(view.groupBy, types),
454
+ ...(declared ? columnProblems(declared, types) : []),
455
+ ];
456
+ return { view, problems };
457
+ }
458
+ function parseYaml(text) {
459
+ try {
460
+ return { ok: true, value: parse(text) };
461
+ }
462
+ catch (error) {
463
+ return { ok: false, problem: `invalid YAML: ${error.message.split('\n')[0]}` };
464
+ }
465
+ }
466
+ export function readPreset(text) {
467
+ const yaml = parseYaml(text);
468
+ if (!yaml.ok)
469
+ return { ok: false, problems: [yaml.problem] };
470
+ const result = presetSchema.safeParse(yaml.value);
471
+ if (!result.success) {
472
+ const problems = result.error.issues.map((issue) => `${issue.path.map(String).join('.') || '(root)'}: ${issue.message}`);
473
+ return { ok: false, problems };
474
+ }
475
+ const raw = result.data;
476
+ const fields = toFields(raw.fields);
477
+ const workflow = toWorkflow(raw.preset, raw.workflow);
478
+ const typed = raw.types === undefined
479
+ ? implicitType(raw, fields, workflow)
480
+ : readTypes(raw, fields, workflow);
481
+ const { view, problems: viewProblems } = readView(raw, typed.types);
482
+ for (const type of typed.types) {
483
+ const labels = typeLabels(raw.labels, type);
484
+ if (labels)
485
+ type.labels = labels;
486
+ }
487
+ const problems = [
488
+ ...titleProblems(raw.fields.title),
489
+ ...fieldsProblems('fields', raw.fields),
490
+ ...workflowProblems('workflow', raw.workflow),
491
+ ...incompleteProblems('workflow', raw.workflow, raw.fields),
492
+ ...typed.problems,
493
+ ...viewProblems,
494
+ ...labelProblems(raw.labels, typed.types, raw.types === undefined),
495
+ ];
496
+ if (problems.length > 0)
497
+ return { ok: false, problems: [...new Set(problems)] };
498
+ const preset = {
499
+ name: raw.preset,
500
+ version: raw.preset_version,
501
+ fields,
502
+ workflow,
503
+ types: typed.types,
504
+ view,
505
+ };
506
+ const icon = raw.icon ?? typed.types.find(({ root }) => root !== false)?.icon;
507
+ if (icon !== undefined)
508
+ preset.icon = icon;
509
+ if (raw.playbook !== undefined)
510
+ preset.playbook = raw.playbook;
511
+ const names = presetNames(raw.labels);
512
+ if (names)
513
+ preset.names = names;
514
+ const notes = [...presetWarnings(raw), ...presetNotes(preset)];
515
+ const warnings = notes.filter(({ level }) => level === 'warning').map(({ message }) => message);
516
+ return { ok: true, preset, warnings, notes };
517
+ }
518
+ export function parsePreset(text) {
519
+ const reading = readPreset(text);
520
+ if (reading.ok)
521
+ return reading.preset;
522
+ throw new OteaError('invalid_preset', `Invalid preset: ${reading.problems.join('; ')}`);
523
+ }
524
+ function typeNames(preset) {
525
+ return preset.types.map(({ name }) => name).join(', ');
526
+ }
527
+ export function typeOf(preset, name) {
528
+ const type = preset.types.find((candidate) => candidate.name === name);
529
+ if (type)
530
+ return type;
531
+ throw new OteaError('invalid_type', `Unknown type "${name}" in preset ${preset.name} (types: ${typeNames(preset)})`);
532
+ }
533
+ // The type a new item takes: the one given, or the preset's only type.
534
+ export function typeFor(preset, name) {
535
+ if (name !== undefined)
536
+ return typeOf(preset, name);
537
+ const [only, ...others] = preset.types;
538
+ if (only && others.length === 0)
539
+ return only;
540
+ throw new OteaError('invalid_type', `Preset ${preset.name} has several types; give one of: ${typeNames(preset)}`);
541
+ }
@@ -0,0 +1,55 @@
1
+ import { OteaError } from './errors.js';
2
+ // What an agent declares for a model or an effort it cannot read from its own settings or
3
+ // environment: Otea never guesses for it, nor lets it guess. It still makes a profile, and the
4
+ // analysis keeps it apart from every family and effort.
5
+ export const UNKNOWN = 'unknown';
6
+ export const isUnknown = (value) => value === UNKNOWN;
7
+ // Model ids grouped for analysis: the first rule that matches names the family; an id none matches
8
+ // is its own family, without the provider a harness may name before it. Extend it as new lines of
9
+ // models appear.
10
+ const FAMILIES = [
11
+ [/\b(opus|sonnet|haiku|fable)\b/, (m) => m[1] ?? ''],
12
+ [/^gpt-(\d+)/, (m) => `gpt-${m[1]}`],
13
+ [/^(o\d+)\b/, (m) => m[1] ?? ''],
14
+ [/^gemini-.*?\b(pro|flash)\b/, (m) => `gemini-${m[1]}`],
15
+ ];
16
+ export function modelFamily(model) {
17
+ // A harness may name the provider before the model (opencode/big-pickle): the model is the same.
18
+ const id = model.toLowerCase().replace(/^.*\//, '');
19
+ if (id === UNKNOWN)
20
+ return UNKNOWN;
21
+ for (const [pattern, family] of FAMILIES) {
22
+ const match = id.match(pattern);
23
+ if (match)
24
+ return family(match);
25
+ }
26
+ return id;
27
+ }
28
+ const VALUE = /^\S{1,100}$/;
29
+ // A profile value is one word as the agent declares it (an exact model id, an effort level, a
30
+ // harness name): no translation between vendors, so it is only checked to be one word (a harness
31
+ // may have spaces, as its maker writes it). A model or an effort the agent cannot read is unknown,
32
+ // kept in one spelling; the harness it always knows.
33
+ export function assertProfileValue(name, value) {
34
+ const unknown = value.toLowerCase() === UNKNOWN;
35
+ if (unknown && name === 'harness') {
36
+ throw new OteaError('invalid_profile', '--harness takes the tool you run in (such as claude-code, codex or gemini-cli): you always know it');
37
+ }
38
+ if (unknown)
39
+ return UNKNOWN;
40
+ if (VALUE.test(value))
41
+ return value;
42
+ // A harness is named as its maker writes it ("Claude Code", "OpenCode 1.4"), spaces and all.
43
+ const named = value.trim();
44
+ if (name === 'harness' && named !== '' && named.length <= 100)
45
+ return named;
46
+ // Each option with its own example, and unknown offered only where it is taken.
47
+ const said = {
48
+ model: 'the exact model id, as your harness names it (such as claude-opus-5-5), or unknown when this session does not tell you: never guess',
49
+ effort: 'the effort, as your harness names it (such as high), or unknown when this session does not tell you: never guess',
50
+ harness: 'the tool you run in (such as claude-code, codex or gemini-cli)',
51
+ };
52
+ const takes = name === 'harness' ? 'a name' : 'one word';
53
+ throw new OteaError('invalid_profile', `--${name} takes ${takes} of at most 100 characters: ${said[name]}`);
54
+ }
55
+ export const profileLine = ({ model, effort }) => `${model} · ${effort}`;
@@ -0,0 +1,20 @@
1
+ const BASE32 = 'abcdefghijklmnopqrstuvwxyz234567';
2
+ const SLUG_MAX = 32;
3
+ export const PROJECT_ID_RANDOM_BYTES = 6;
4
+ // Lowercase ASCII letters and digits joined by single dashes; accents fold to their base letter.
5
+ export function slugify(name) {
6
+ const slug = name
7
+ .normalize('NFKD')
8
+ .replace(/[̀-ͯ]/g, '')
9
+ .toLowerCase()
10
+ .replace(/[^a-z0-9]+/g, '-')
11
+ .slice(0, SLUG_MAX)
12
+ .replace(/^-+|-+$/g, '');
13
+ return slug === '' ? 'project' : slug;
14
+ }
15
+ // `<slug>-<6 base32 chars>`, one char per random byte. The slug is for people; the suffix keeps two
16
+ // projects with the same folder name apart.
17
+ export function projectId(name, random) {
18
+ const suffix = Array.from(random.subarray(0, PROJECT_ID_RANDOM_BYTES), (b) => BASE32[b & 31]);
19
+ return `${slugify(name)}-${suffix.join('')}`;
20
+ }
@@ -0,0 +1 @@
1
+ export {};