@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,44 @@
1
+ import { quoted } from '../core/board/next.js';
2
+ // The exact command an agent runs to keep hearing the desk, which next and wait end with (PLAN5 G3):
3
+ // an agent told only "wait" ends its turn, and what the person does next goes unheard.
4
+ function on(collection) {
5
+ return collection === undefined ? '' : ` --collection ${quoted(collection)}`;
6
+ }
7
+ // otea wait for the agent's next item, named as it is on every call.
8
+ export function keepWaitingCommand(agent, collection) {
9
+ return `otea wait --turn agent --unclaimed${on(collection)} --as ${agent}`;
10
+ }
11
+ // The wait and the next as the agent runs them: on the command line with its name; over MCP as the
12
+ // tools (MCP words turn them into tool calls, which take the name as `as`), with the wait first as a
13
+ // shell line ("$ ", kept as it is) to run in the background, since the wait tool holds the chat
14
+ // until it returns (all of OpenCode's TUI) and a background shell leaves it free (P2S-R2-9).
15
+ function commands(agent, channel, collection) {
16
+ const mcp = channel === 'mcp';
17
+ const next = mcp ? `otea next${on(collection)}` : `otea next${on(collection)} --as ${agent}`;
18
+ const shell = keepWaitingCommand(agent, collection);
19
+ const tool = ` Without a shell, otea wait --turn agent --unclaimed${on(collection)} holds your chat until it returns.`;
20
+ return { mcp, next, shell, tool };
21
+ }
22
+ // What an idle agent is told of the desk: it hears the person only while its wait runs (P2S-6).
23
+ const DESK = ' Only a running wait hears the desk: approvals, answers and notes from the person.';
24
+ // next's last line: with nothing to do, wait now; with an item, once it is handed off and next has
25
+ // nothing more.
26
+ export function keepWaitingLine(agent, channel, { idle, collection }) {
27
+ const { mcp, next, shell, tool } = commands(agent, channel, collection);
28
+ if (!mcp) {
29
+ const wait = `${shell} in the background if you can`;
30
+ return idle
31
+ ? `Wait for one: ${wait}, then ${next}.${DESK}`
32
+ : `When you finish and ${next} has nothing: ${wait}.`;
33
+ }
34
+ return idle
35
+ ? `Wait for one in a background shell, which keeps your chat free: $ ${shell}; then ${next}.${tool}${DESK}`
36
+ : `When you finish and ${next} has nothing, wait in a background shell, which keeps your chat free: $ ${shell}.${tool}`;
37
+ }
38
+ // What otea wait ends with once it woke: read what woke it, then wait again.
39
+ export function waitAgainLine(agent, channel, collection) {
40
+ const { mcp, next, shell, tool } = commands(agent, channel, collection);
41
+ if (!mcp)
42
+ return `Then keep going: ${next}; when it has nothing, ${shell} in the background if you can.`;
43
+ return `Then keep going: ${next}; when it has nothing, wait again in a background shell: $ ${shell}.${tool}`;
44
+ }
@@ -0,0 +1,107 @@
1
+ import { isClosed, isLandStep, positionOf } from '../core/board/engine.js';
2
+ import { guardedBranch } from '../core/board/model.js';
3
+ import { activeLease } from '../core/lease.js';
4
+ import { selectItems, selectStateEntries } from '../store/queries.js';
5
+ import { leftFor, liveBoardOf, liveBoards } from './next.js';
6
+ import { sessionEnded } from './presence.js';
7
+ import { priorityOf } from './priority.js';
8
+ // One agent lands at a time on a base branch, and the next to land is the item highest in the
9
+ // person's order (P1-R3-2): approved items raced into main, the lower and unordered ones landed
10
+ // first, and the ones on top conflicted again and again, each conflict another review round. It
11
+ // holds on any board's land step (the step an agent integrates what the person approved in,
12
+ // however the board names it), across the boards that land in the same base of the same repo.
13
+ // The person still moves anything by hand: they reorder the Matrix, put an item on top, move an
14
+ // item themselves or leave it for one agent (Reasignar), which lands it when it takes it.
15
+ // Where an item stands on a land step: the base it lands in, and the key of that base in its repo
16
+ // (boards whose guard reads the repo from a field keep each repo apart). Undefined anywhere else.
17
+ function landingIn(board, item) {
18
+ const position = positionOf(item.state);
19
+ if (isClosed(position) || position.phase !== 'doing')
20
+ return undefined;
21
+ if (!isLandStep(board.def, position.step))
22
+ return undefined;
23
+ const guard = guardedBranch(board.def);
24
+ if (!guard)
25
+ return undefined;
26
+ const base = guard.guard.base ?? 'the base';
27
+ const repo = guard.guard.repo === undefined ? '' : item.fields[guard.guard.repo];
28
+ return { key: `${typeof repo === 'string' ? repo.toLowerCase() : ''}\0${base}`, base };
29
+ }
30
+ // Why an item comes first in the person's order: what they put on top, their order on the
31
+ // Matrix, else that it was approved first.
32
+ function placeText(priority) {
33
+ if (priority?.pin !== undefined)
34
+ return `on top ${priority.pin}`;
35
+ if (priority?.rank !== undefined)
36
+ return `order ${priority.rank}`;
37
+ return 'approved before it';
38
+ }
39
+ // What lands in the item's base before it, for the agent asking; undefined when the item is not on
40
+ // a land step, or its turn to land is now. `takeable` says whether the agent could take another
41
+ // item now, leaving this order aside: an item no agent can take (a question waits for the person)
42
+ // never holds up the ones after it.
43
+ export function landsFirst(ctx, item, agent, at, takeable) {
44
+ const board = liveBoardOf(ctx, item.collection);
45
+ const own = board && landingIn(board, item);
46
+ if (!own)
47
+ return undefined;
48
+ // The person left it for this agent: their say goes.
49
+ if (leftFor(ctx, item.id) === agent)
50
+ return undefined;
51
+ // Its landing began with this agent, whose lease may have run out meanwhile: it goes on with it.
52
+ if (item.lease?.holder === agent)
53
+ return undefined;
54
+ const waiting = liveBoards(ctx).flatMap((each) => selectItems(ctx.db, { collection: each.collection }).flatMap((other) => other.id !== item.id && landingIn(each, other)?.key === own.key
55
+ ? [{ item: other, board: each }]
56
+ : []));
57
+ // A landing under way: another item of the base an agent holds, unless that agent's session
58
+ // ended (a claim takes its lease over then, P3C-R3-11).
59
+ const landing = waiting.flatMap(({ item: other }) => {
60
+ const lease = activeLease(other.lease, at);
61
+ return lease && !sessionEnded(ctx.db, lease.holder, () => at)
62
+ ? [{ first: other.id, base: own.base, holder: lease.holder }]
63
+ : [];
64
+ });
65
+ if (landing[0])
66
+ return landing[0];
67
+ const priority = priorityOf(ctx.db);
68
+ const entered = selectStateEntries(ctx.db);
69
+ const key = (each) => [
70
+ priority.get(each.id)?.pin ?? Number.POSITIVE_INFINITY,
71
+ priority.get(each.id)?.rank ?? Number.POSITIVE_INFINITY,
72
+ ];
73
+ const since = (each) => entered.get(each.id) ?? each.createdAt;
74
+ const before = (a, b) => {
75
+ const [pa = 0, ra = 0] = key(a);
76
+ const [pb = 0, rb = 0] = key(b);
77
+ if (pa !== pb)
78
+ return pa < pb;
79
+ if (ra !== rb)
80
+ return ra < rb;
81
+ const [sa, sb] = [since(a), since(b)];
82
+ return sa !== sb ? sa < sb : a.createdAt < b.createdAt;
83
+ };
84
+ const ahead = waiting
85
+ .filter(({ item: other, board: each }) => takeable(each, other) && before(other, item))
86
+ .map(({ item: other }) => other);
87
+ const first = ahead.reduce((best, other) => (best === undefined || before(other, best) ? other : best), undefined);
88
+ if (!first)
89
+ return undefined;
90
+ return { first: first.id, base: own.base, place: placeText(priority.get(first.id)) };
91
+ }
92
+ // Why a claim of the item is refused while another lands first, in one line.
93
+ export function landsFirstText(id, first) {
94
+ const { base } = first;
95
+ const ahead = 'holder' in first
96
+ ? `${first.holder} lands ${first.first} in ${base} now; ${id} lands after it`
97
+ : `${first.first} lands in ${base} first (${first.place}), then ${id}`;
98
+ return `${id} not claimed: ${ahead}: one agent lands at a time on ${base}, in the person's order, so no landing conflicts with another under way. Take other work meanwhile: otea next.`;
99
+ }
100
+ // What next says, with nothing to offer, of the items that wait for their turn to land.
101
+ export function landsFirstLine(id, first) {
102
+ const { base } = first;
103
+ const ahead = 'holder' in first
104
+ ? `${first.holder} lands ${first.first} there now`
105
+ : `${first.first} lands there first (${first.place})`;
106
+ return `${id} waits to land in ${base}: ${ahead}; one agent lands at a time on ${base}, in the person's order.`;
107
+ }
@@ -0,0 +1,52 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { LANGS } from '../core/board/template-words.js';
4
+ import { selectPreference, upsertPreference } from '../store/machine.js';
5
+ import { machineDir, withMachine } from './machine.js';
6
+ import { system } from './system-locale.js';
7
+ // The language of what Otea makes for the person: the language they use at that moment, kept as
8
+ // it was made. Switching later rewrites nothing that exists; what agents write is up to the agents.
9
+ // The desk knows the language (the person's own choice, kept as a preference of the person in the
10
+ // machine store); a command with no desk to ask resolves it here, in one place:
11
+ // 1. the language the desk last used,
12
+ // 2. the language of this computer (a locale that starts with es is Spanish, any other English),
13
+ // 3. English.
14
+ const KEY = 'language';
15
+ export const isLang = (value) => LANGS.includes(value);
16
+ // The language the person's desk is in, or none while no desk has told the server.
17
+ export function storedLanguage(machine) {
18
+ const value = selectPreference(machine, KEY);
19
+ return isLang(value) ? value : undefined;
20
+ }
21
+ // Remembers the desk's language. With `onlyIfUnset` (a desk that just opened) it only fills the
22
+ // gap, so a phone opening in another language never overrides what the person chose. Returns the
23
+ // language that stands.
24
+ export function rememberLanguage(machine, lang, onlyIfUnset = false) {
25
+ const stored = storedLanguage(machine);
26
+ if (onlyIfUnset && stored !== undefined)
27
+ return stored;
28
+ if (stored !== lang)
29
+ upsertPreference(machine, KEY, lang);
30
+ return lang;
31
+ }
32
+ // What the machine store holds, without creating a store that is not there yet.
33
+ export function storedLanguageAt(env = process.env) {
34
+ if (!existsSync(join(machineDir(env), 'machine.db')))
35
+ return undefined;
36
+ return withMachine(env, storedLanguage);
37
+ }
38
+ // This computer's language: the locale variables a person set (LC_ALL, then LC_MESSAGES, then LANG;
39
+ // C and POSIX, with or without an encoding, say nothing), else the one the runtime reads from the
40
+ // system.
41
+ export function systemLanguage(env = process.env, locale = system.locale) {
42
+ const set = [env.LC_ALL, env.LC_MESSAGES, env.LANG].find((value) => value && !/^(C|POSIX)(\.|$)/.test(value));
43
+ return /^es(?![a-z])/i.test(set ?? locale()) ? 'es' : 'en';
44
+ }
45
+ // The one resolver: the stored desk language, else the system's, else English.
46
+ export function resolveLang(stored, env = process.env, locale) {
47
+ return stored ?? systemLanguage(env, locale);
48
+ }
49
+ // The language for what is made with no desk in front of the person.
50
+ export function defaultLang(env = process.env) {
51
+ return resolveLang(storedLanguageAt(env), env);
52
+ }
@@ -0,0 +1,56 @@
1
+ import { accessSync, constants, statSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ export function oteaLauncher(main, runtime) {
4
+ if (runtime.electron === undefined) {
5
+ return { command: 'node', args: ['--disable-warning=ExperimentalWarning', main] };
6
+ }
7
+ return { command: runtime.execPath, args: [main], env: { ELECTRON_RUN_AS_NODE: '1' } };
8
+ }
9
+ // Whether path is a file this computer can run: any file on Windows (PATHEXT picks the ending), an
10
+ // executable one elsewhere.
11
+ function runnable(path, platform) {
12
+ try {
13
+ if (!statSync(path).isFile())
14
+ return false;
15
+ if (platform !== 'win32')
16
+ accessSync(path, constants.X_OK);
17
+ return true;
18
+ }
19
+ catch {
20
+ return false;
21
+ }
22
+ }
23
+ // The otea command on $PATH (npm link, an installed package), as a harness starts it, so what the
24
+ // agent adds survives a checkout that moves; undefined when no otea is there. A harness on Windows
25
+ // starts the .cmd shim npm puts there only through cmd /c, as it does npx.
26
+ export function pathLauncher(env, platform = process.platform) {
27
+ const windows = platform === 'win32';
28
+ const dirs = (env.PATH ?? env.Path ?? '').split(windows ? ';' : ':').filter(Boolean);
29
+ const endings = windows
30
+ ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
31
+ : [''];
32
+ for (const dir of dirs) {
33
+ for (const ending of endings) {
34
+ if (!runnable(join(dir, `otea${ending}`), platform))
35
+ continue;
36
+ return /^\.(bat|cmd)$/i.test(ending)
37
+ ? { command: 'cmd', args: ['/c', 'otea'] }
38
+ : { command: 'otea', args: [] };
39
+ }
40
+ }
41
+ return undefined;
42
+ }
43
+ // The launcher carrying an Otea home set apart ($OTEA_HOME), so what runs it later (the MCP
44
+ // server, a hook) finds the same projects; as it is without one.
45
+ export function withHome(launcher, home) {
46
+ if (home === undefined)
47
+ return launcher;
48
+ return { ...launcher, env: { ...launcher.env, OTEA_HOME: home } };
49
+ }
50
+ // A bare word or a flag goes as it is; anything else (a path) in double quotes.
51
+ const word = (part) => (/^(--)?[\w=.-]+$/.test(part) ? part : `"${part}"`);
52
+ // The launcher as the start of a POSIX shell command line (git hooks, Claude Code hooks).
53
+ export function shellLine(launcher) {
54
+ const env = Object.entries(launcher.env ?? {}).map(([name, value]) => `${name}=${word(value)} `);
55
+ return `${env.join('')}${[launcher.command, ...launcher.args].map(word).join(' ')}`;
56
+ }
@@ -0,0 +1,54 @@
1
+ import { OteaError } from '../core/errors.js';
2
+ import { activeLease, assertMayWrite, DEFAULT_LEASE_TTL_MS, leaseExpiry, leaseHeld, } from '../core/lease.js';
3
+ import { timeText } from '../core/time.js';
4
+ import { appendEvent, clearLease, selectEvents, takeLease, } from '../store/queries.js';
5
+ import { sessionEnded, sessionRuns } from './presence.js';
6
+ // Why a claim of an item whose lease ran out is refused while its holder's session runs.
7
+ function stillWorking(id, lease) {
8
+ const { holder } = lease;
9
+ return new OteaError('lease_held', `${id} is still ${holder}'s: its lease ran out at ${timeText(lease.expiresAt)}, but its session runs (an MCP server or wait of it), so it may be at work on a long step with no otea call. Take other work: otea next. If ${holder} is stuck, the person frees the item on the desk (Liberar).`);
10
+ }
11
+ // Takes the lease on an item for the actor, inside the caller's transaction, once the caller has
12
+ // checked the item is the actor's to claim: refused while another holds it, unless that agent's
13
+ // session ended (P3C-R3-11): its lease is taken over, with `cause: ended`. Claiming it again
14
+ // extends it. A new holder writes a `claimed` event. Shared by otea claim and otea next --claim.
15
+ export function takeItem(db, item, actor, at, ttlMs = DEFAULT_LEASE_TTL_MS) {
16
+ const held = activeLease(item.lease, at);
17
+ const other = held && held.holder !== actor.name ? held : null;
18
+ const ended = other !== null && sessionEnded(db, other.holder, () => at);
19
+ if (other && !ended)
20
+ throw leaseHeld(item.id, other);
21
+ // A lease that ran out is no proof its holder stopped (P1-R3-6): while its session runs, the item
22
+ // stays its own.
23
+ const ranOut = !held && item.lease && item.lease.holder !== actor.name ? item.lease : null;
24
+ if (ranOut && sessionRuns(db, ranOut.holder, () => at))
25
+ throw stillWorking(item.id, ranOut);
26
+ if (ended)
27
+ clearLease(db, item.id);
28
+ const lease = { holder: actor.name, expiresAt: leaseExpiry(at, ttlMs) };
29
+ if (!takeLease(db, item.id, lease, at))
30
+ throw new OteaError('lease_held', `${item.id} is held`);
31
+ if (!held || ended) {
32
+ const previous = item.lease && item.lease.holder !== actor.name ? item.lease.holder : null;
33
+ const data = previous ? { ...lease, previous, ...(ended ? { cause: 'ended' } : {}) } : lease;
34
+ appendEvent(db, { itemId: item.id, type: 'claimed', actor, at, data });
35
+ }
36
+ return lease;
37
+ }
38
+ // Whether the actor may write the item now: no other agent holds it (assertMayWrite), and an agent
39
+ // whose own lease ran out, or that the person freed it from, claims it again first. Its work may
40
+ // have gone to another agent meanwhile; writing on as if it still held it would hand off over them.
41
+ export function assertMayWriteItem(db, item, actor, at) {
42
+ const lease = activeLease(item.lease, at);
43
+ assertMayWrite(item.id, lease, actor);
44
+ if (actor.kind !== 'agent' || lease)
45
+ return;
46
+ const again = `claim it again before you write: otea claim ${item.id}`;
47
+ if (item.lease?.holder === actor.name) {
48
+ throw new OteaError('not_lease_holder', `Your lease on ${item.id} ran out at ${timeText(item.lease.expiresAt)}; ${again}`);
49
+ }
50
+ const last = selectEvents(db, item.id).findLast(({ type }) => type === 'claimed' || type === 'released');
51
+ if (last?.type === 'released' && last.actor.kind === 'human' && last.data.holder === actor.name) {
52
+ throw new OteaError('not_lease_holder', `The person freed ${item.id} from you at ${timeText(last.at)}; ${again}`);
53
+ }
54
+ }
@@ -0,0 +1,86 @@
1
+ import { positionOf } from '../core/board/engine.js';
2
+ import { placeText } from '../core/board/next.js';
3
+ import { OteaError } from '../core/errors.js';
4
+ import { activeLease, DEFAULT_LEASE_TTL_MS, heldText, leaseExpiry } from '../core/lease.js';
5
+ import { turnOf } from '../core/workflow.js';
6
+ import { transaction } from '../store/database.js';
7
+ import { appendEvent, clearLease, takeLease } from '../store/queries.js';
8
+ import { present, requireWritableItem, systemClock, workflowOf } from './items.js';
9
+ import { takeItem } from './lease-take.js';
10
+ import { assertMayClaim, liveBoardOf, setAsideRefusal, wantedNowRefusal } from './next.js';
11
+ function notHolder(item, actor, at) {
12
+ const lease = activeLease(item.lease, at);
13
+ const message = lease
14
+ ? `${heldText(item.id, lease)}, not by ${actor.name}: only ${lease.holder} can renew or release it`
15
+ : `${item.id} is not held by ${actor.name}; claim it first`;
16
+ return new OteaError('not_lease_holder', message);
17
+ }
18
+ // `tookOver`: the agent whose lease the claim took over, its session ended (takeItem).
19
+ export function claimItem(ctx, input, now = systemClock) {
20
+ const { db } = ctx;
21
+ return transaction(db, () => {
22
+ const item = requireWritableItem(db, input.id);
23
+ const workflow = workflowOf(ctx, item);
24
+ const turn = turnOf(workflow, item.state);
25
+ if (turn !== 'agent') {
26
+ const board = liveBoardOf(ctx, item.collection);
27
+ const where = board ? placeText(board.def, positionOf(item.state)) : item.state;
28
+ throw new OteaError('not_claimable', `${item.id} is in ${where} (turn ${turn}); only items on the agent turn can be claimed`);
29
+ }
30
+ const at = now();
31
+ assertMayClaim(ctx, item, input.actor.name, at);
32
+ const held = activeLease(item.lease, at)?.holder;
33
+ const lease = takeItem(db, item, input.actor, at, input.ttlMs);
34
+ const claimed = present({ ...item, lease }, workflow, at);
35
+ return held !== undefined && held !== input.actor.name
36
+ ? { ...claimed, tookOver: held }
37
+ : claimed;
38
+ });
39
+ }
40
+ export function heartbeatItem(ctx, input, now = systemClock) {
41
+ const { db } = ctx;
42
+ return transaction(db, () => {
43
+ const item = requireWritableItem(db, input.id);
44
+ const at = now();
45
+ const current = activeLease(item.lease, at);
46
+ if (current?.holder !== input.actor.name)
47
+ throw notHolder(item, input.actor, at);
48
+ // A ttl given sets the lease from now; none extends it, never shortening a longer one.
49
+ const extended = leaseExpiry(at, input.ttlMs ?? DEFAULT_LEASE_TTL_MS);
50
+ const keep = input.ttlMs === undefined && current.expiresAt > extended;
51
+ const lease = { holder: current.holder, expiresAt: keep ? current.expiresAt : extended };
52
+ takeLease(db, item.id, lease, at);
53
+ return present({ ...item, lease }, workflowOf(ctx, item), at);
54
+ });
55
+ }
56
+ export function releaseItem(ctx, input, now = systemClock) {
57
+ const { db } = ctx;
58
+ return transaction(db, () => {
59
+ const item = requireWritableItem(db, input.id);
60
+ const at = now();
61
+ const current = activeLease(item.lease, at);
62
+ // An item nobody holds is set aside for later too: an agent that let it go with a plain release
63
+ // when the person wanted it later sets it aside without claiming it again (P3C-R3-2).
64
+ const aside = input.later === true && current === null;
65
+ if (!aside && current?.holder !== input.actor.name)
66
+ throw notHolder(item, input.actor, at);
67
+ // What is not agent work right now comes back on its own: setting it aside would only hide it
68
+ // once it does (P7-R3-1).
69
+ const refused = input.later ? setAsideRefusal(ctx, item) : undefined;
70
+ if (refused && current) {
71
+ const plain = `${refused.message} To let go of it: otea release ${item.id}`;
72
+ throw new OteaError(refused.code, plain);
73
+ }
74
+ if (refused)
75
+ throw refused;
76
+ const quote = input.later ? input.quote?.trim() : undefined;
77
+ const wanted = input.later ? wantedNowRefusal(ctx, item, quote) : undefined;
78
+ if (wanted)
79
+ throw wanted;
80
+ clearLease(db, item.id);
81
+ const holder = current?.holder ?? input.actor.name;
82
+ const data = { holder, cause: input.later ? 'later' : 'release', ...(quote ? { quote } : {}) };
83
+ appendEvent(db, { itemId: item.id, type: 'released', actor: input.actor, at, data });
84
+ return present({ ...item, lease: null }, workflowOf(ctx, item), at);
85
+ });
86
+ }
@@ -0,0 +1,39 @@
1
+ import { mkdirSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { openDatabase } from '../store/database.js';
4
+ import { deleteLocalProject, migrateMachine, selectLocalProjects, upsertLocalProject, } from '../store/machine.js';
5
+ import { oteaHome } from './home.js';
6
+ // This computer's one Otea server keeps what is not a project's in the Otea home: the paired
7
+ // devices, the phone settings and the notification targets (machine.db), the browser's sign-in
8
+ // key (ui-token), the Web Push keys (push-keys.json) and where it runs (serve.json). A paired device
9
+ // is the person's: it sees every project this server serves, and revoking it is what protects them.
10
+ export const machineDir = (env = process.env) => oteaHome(env);
11
+ export function openMachine(env = process.env) {
12
+ const dir = machineDir(env);
13
+ mkdirSync(dir, { recursive: true });
14
+ const db = openDatabase(join(dir, 'machine.db'));
15
+ migrateMachine(db);
16
+ return db;
17
+ }
18
+ // A machine store that lives as long as its connection (tests, and a server given none).
19
+ export function memoryMachine() {
20
+ const db = openDatabase(':memory:');
21
+ migrateMachine(db);
22
+ return db;
23
+ }
24
+ export function rememberLocalProject(db, project, now = new Date()) {
25
+ upsertLocalProject(db, project, now.toISOString());
26
+ }
27
+ export const localProjects = (db) => selectLocalProjects(db);
28
+ export function forgetLocalProject(db, id) {
29
+ deleteLocalProject(db, id);
30
+ }
31
+ export function withMachine(env, use) {
32
+ const db = openMachine(env);
33
+ try {
34
+ return use(db);
35
+ }
36
+ finally {
37
+ db.close();
38
+ }
39
+ }
@@ -0,0 +1,89 @@
1
+ import { isClosed, landStepOf, positionOf, reopenStep, stateOf } from '../core/board/engine.js';
2
+ import { MERGED, mergedFrom } from '../core/board/merged.js';
3
+ import { DONE, guardedBranch } from '../core/board/model.js';
4
+ import { reopenedText } from '../core/board/next.js';
5
+ import { OteaError } from '../core/errors.js';
6
+ import { activeLease } from '../core/lease.js';
7
+ import { transaction } from '../store/database.js';
8
+ import { appendEvent, selectEvents } from '../store/queries.js';
9
+ import { landMove, requireWritableItem, systemClock, workflowOf } from './items.js';
10
+ import { liveBoardOf } from './next.js';
11
+ export function mergedOf(ctx, id) {
12
+ return mergedFrom(selectEvents(ctx.db, id));
13
+ }
14
+ // Records that a Done item's branch was merged: after Done the item takes no other change, so this
15
+ // is the fact that tells its rows and page the work is in (and not still waiting to be merged).
16
+ export function markMerged(ctx, input, now = systemClock) {
17
+ const { id } = input;
18
+ return transaction(ctx.db, () => {
19
+ const item = requireWritableItem(ctx.db, id);
20
+ const position = positionOf(item.state);
21
+ if (!isClosed(position) || position.closed !== DONE)
22
+ throw new OteaError('invalid_transition', `${id} is not Done yet: mark it merged once it is Done and its branch is in`, { kind: 'not_done', item: id });
23
+ if (mergedOf(ctx, id))
24
+ throw new OteaError('invalid_transition', `${id} is marked merged already`, {
25
+ kind: 'merged_already',
26
+ item: id,
27
+ });
28
+ const board = liveBoardOf(ctx, item.collection);
29
+ const part = board ? guardedBranch(board.def) : undefined;
30
+ const branch = part ? String(item.fields[part.id] ?? '').trim() : '';
31
+ // A merge the forge contradicts is refused: a wrong mark would freeze the item for good.
32
+ const { forge } = input;
33
+ const pr = input.pr?.trim() ?? '';
34
+ if (forge && forge.state.toUpperCase() !== 'MERGED')
35
+ throw new OteaError('invalid_transition', `Not marked ${id} merged: its PR ${pr} is ${forge.state.toLowerCase()}, not merged. Merge it first, then otea merged ${id} --pr ${pr}.`, { kind: 'pr_not_merged', item: id, state: forge.state });
36
+ if (forge && branch !== '' && forge.head !== branch)
37
+ throw new OteaError('invalid_transition', `Not marked ${id} merged: its PR ${pr} merges ${forge.head}, not ${id}'s branch ${branch}.`, { kind: 'pr_other_branch', item: id, head: forge.head });
38
+ appendEvent(ctx.db, {
39
+ itemId: id,
40
+ type: MERGED,
41
+ actor: input.actor,
42
+ at: now(),
43
+ data: {
44
+ ...(branch === '' ? {} : { branch }),
45
+ ...(input.pr?.trim() ? { pr: input.pr.trim() } : {}),
46
+ ...(input.commit?.trim() ? { commit: input.commit.trim() } : {}),
47
+ channel: input.channel,
48
+ },
49
+ });
50
+ const merged = mergedOf(ctx, id);
51
+ if (!merged)
52
+ throw new Error(`the merge of ${id} was not kept`);
53
+ return merged;
54
+ });
55
+ }
56
+ // Takes a Done item whose branch is not merged yet back to the step that pushes its branch: its PR
57
+ // stopped merging as it is (another branch merged first and now conflicts) and its branch, frozen
58
+ // while it is Done, must change. Whoever asks (the agent that hits the conflict, or the person)
59
+ // says why; the change goes through the step's review again, so the person approves it again.
60
+ // Once the branch is merged (marked so, or landed in the board's land step) the item stays Done: a
61
+ // further change is new work.
62
+ export function reopenItem(ctx, input, now = systemClock) {
63
+ const { id } = input;
64
+ return transaction(ctx.db, () => {
65
+ const item = requireWritableItem(ctx.db, id);
66
+ const position = positionOf(item.state);
67
+ const refuse = (kind, text) => {
68
+ throw new OteaError('invalid_transition', text, { kind, item: id });
69
+ };
70
+ if (!isClosed(position) || position.closed !== DONE)
71
+ refuse('not_done', `${id} is not Done: only a Done item whose branch is not merged yet reopens`);
72
+ if (mergedOf(ctx, id))
73
+ refuse('merged_already', `${id} is merged already: its branch is in, so a further change is new work, not ${id}`);
74
+ const board = liveBoardOf(ctx, item.collection);
75
+ // On a board with a land step, an agent merged the item there before it was Done.
76
+ const land = board ? landStepOf(board.def) : undefined;
77
+ if (land)
78
+ refuse('merged_already', `${id} was merged in ${land.name} already: its branch is in, so a further change is new work, not ${id}`);
79
+ const step = board ? reopenStep(board.def) : undefined;
80
+ if (!board || step === undefined)
81
+ return refuse('no_branch', `${id} protects no branch: there is nothing to reopen it for`);
82
+ if (!input.reason.trim())
83
+ throw new OteaError('reason_required', `Reopening ${id} needs a reason: why its branch must change`, { kind: 'way_back_reason', item: id });
84
+ const to = stateOf({ step, phase: 'doing' });
85
+ const at = now();
86
+ const moved = landMove(ctx, workflowOf(ctx, item), item, { to, actor: input.actor, at, lease: activeLease(item.lease, at), board: true }, { reason: input.reason.trim(), reopened: true, channel: input.channel });
87
+ return { item: moved, text: reopenedText(board.def, id, step) };
88
+ });
89
+ }