@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,70 @@
1
+ export const EXIT_CODES = {
2
+ ok: 0,
3
+ unexpected: 1,
4
+ // otea check: the gate refuses the action; its own code, so a hook tells a refusal from a crash,
5
+ // on which it stops too, saying Otea could not check.
6
+ gate_refused: 19,
7
+ usage: 2,
8
+ not_found: 3,
9
+ invalid_transition: 4,
10
+ not_undoable: 4,
11
+ not_stuck: 4,
12
+ item_closed: 4,
13
+ not_claimable: 4,
14
+ not_relayable: 4,
15
+ already_exists: 5,
16
+ invalid_name: 6,
17
+ invalid_agent_name: 6,
18
+ unnamed_agent: 2,
19
+ invalid_icon: 6,
20
+ invalid_id: 6,
21
+ forbidden: 7,
22
+ reason_required: 2,
23
+ quote_required: 2,
24
+ file_not_found: 3,
25
+ invalid_fields: 8,
26
+ invalid_type: 8,
27
+ missing_fields: 8,
28
+ invalid_preset: 9,
29
+ validation_failed: 10,
30
+ not_running: 11,
31
+ // otea connect --check: no agent reached Otea through its MCP server yet.
32
+ not_connected: 11,
33
+ lease_held: 12,
34
+ not_lease_holder: 12,
35
+ // Another open MCP session works under the agent name.
36
+ name_in_use: 12,
37
+ timeout: 13,
38
+ evidence_too_large: 14,
39
+ evidence_not_accepted: 15,
40
+ module_required: 2,
41
+ invalid_role: 2,
42
+ invalid_relation: 2,
43
+ self_relation: 16,
44
+ parent_exists: 16,
45
+ parent_type: 16,
46
+ parent_required: 16,
47
+ relation_cycle: 16,
48
+ parent_across_boards: 16,
49
+ children_open: 4,
50
+ blockers_open: 4,
51
+ different_repo: 17,
52
+ in_use: 18,
53
+ invalid_draft: 9,
54
+ invalid_board: 9,
55
+ not_publishable: 9,
56
+ invalid_gate: 2,
57
+ invalid_profile: 2,
58
+ // No profile declared, or not declared again in this session: otea profile says how.
59
+ profile_required: 2,
60
+ board_conflict: 4,
61
+ // A phone transport that cannot carry a phone yet: Tailscale not ready, the Otea relay.
62
+ transport_unavailable: 20,
63
+ // An item of an archived board: it is read-only until the person restores the board in Studio.
64
+ board_archived: 21,
65
+ // otea hook install --forge could not set the forge's rules (no gh, signed out, refused): it
66
+ // printed the steps to take by hand.
67
+ forge_unavailable: 22,
68
+ // 128 + SIGINT, as shells report a command stopped by Ctrl+C.
69
+ interrupted: 130,
70
+ };
@@ -0,0 +1,176 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { CommandFailure } from './command.js';
3
+ import { GH_TIMEOUT_MS } from './gh.js';
4
+ export const NO_FORGE = {
5
+ status: () => 'missing',
6
+ repo: () => undefined,
7
+ rulesets: () => [],
8
+ saveRuleset: () => {
9
+ throw new Error('no gh');
10
+ },
11
+ deleteRuleset: () => {
12
+ throw new Error('no gh');
13
+ },
14
+ };
15
+ // The ruleset Otea keeps, by its name: one for every base branch the project's boards protect.
16
+ export const RULESET_NAME = 'Otea: protected base branches';
17
+ export function rulesetFor(bases) {
18
+ return {
19
+ name: RULESET_NAME,
20
+ target: 'branch',
21
+ enforcement: 'active',
22
+ conditions: { ref_name: { include: bases.map((base) => `refs/heads/${base}`), exclude: [] } },
23
+ rules: [
24
+ { type: 'deletion' },
25
+ { type: 'non_fast_forward' },
26
+ {
27
+ type: 'pull_request',
28
+ parameters: {
29
+ required_approving_review_count: 0,
30
+ dismiss_stale_reviews_on_push: false,
31
+ require_code_owner_review: false,
32
+ require_last_push_approval: false,
33
+ required_review_thread_resolution: false,
34
+ },
35
+ },
36
+ ],
37
+ };
38
+ }
39
+ // The steps to take by hand when gh cannot: on GitHub, or with gh once it is signed in.
40
+ export function forgeSteps(bases, why) {
41
+ const names = bases.join(', ');
42
+ return [
43
+ `${why}. To have GitHub enforce what Otea protects (${names}) for any tool:`,
44
+ ' 1. On GitHub, open the repository, then Settings > Rules > Rulesets > New ruleset > New branch ruleset.',
45
+ ` 2. Name it "${RULESET_NAME}" and set Enforcement status to Active.`,
46
+ ` 3. Under Target branches, Add target > Include by pattern: ${bases.join(', then ')}.`,
47
+ ' 4. Turn on Restrict deletions, Block force pushes, and Require a pull request before merging (0 required approvals).',
48
+ ' 5. Create.',
49
+ 'Or, once gh (https://cli.github.com) is installed and signed in (gh auth login) in a checkout of the GitHub repository, run otea hook install --forge again: it sets the ruleset for you.',
50
+ ].join('\n');
51
+ }
52
+ function gh(path, cwd, args, input) {
53
+ return execFileSync(path, args, {
54
+ cwd,
55
+ encoding: 'utf8',
56
+ stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
57
+ timeout: GH_TIMEOUT_MS,
58
+ ...(input === undefined ? {} : { input }),
59
+ }).trim();
60
+ }
61
+ // The real gh CLI at `path` ('gh' on the PATH); `prefix` goes before its arguments (a script a
62
+ // runtime runs, for a stand-in).
63
+ export function ghForge(path, prefix = []) {
64
+ const run = (cwd, args, input) => gh(path, cwd, [...prefix, ...args], input);
65
+ return {
66
+ status(cwd) {
67
+ try {
68
+ run(cwd, ['--version']);
69
+ }
70
+ catch {
71
+ return 'missing';
72
+ }
73
+ try {
74
+ run(cwd, ['auth', 'status']);
75
+ return 'ready';
76
+ }
77
+ catch {
78
+ return 'signed-out';
79
+ }
80
+ },
81
+ repo(cwd) {
82
+ try {
83
+ const name = run(cwd, [
84
+ 'repo',
85
+ 'view',
86
+ '--json',
87
+ 'nameWithOwner',
88
+ '--jq',
89
+ '.nameWithOwner',
90
+ ]);
91
+ return name === '' ? undefined : name;
92
+ }
93
+ catch {
94
+ return undefined;
95
+ }
96
+ },
97
+ rulesets(cwd, repo) {
98
+ const listed = JSON.parse(run(cwd, ['api', `repos/${repo}/rulesets`]) || '[]');
99
+ if (!Array.isArray(listed))
100
+ return [];
101
+ return listed.flatMap((entry) => typeof entry.id === 'number' && typeof entry.name === 'string'
102
+ ? [{ id: entry.id, name: entry.name }]
103
+ : []);
104
+ },
105
+ saveRuleset(cwd, repo, ruleset, id) {
106
+ const [method, endpoint] = id === undefined
107
+ ? ['POST', `repos/${repo}/rulesets`]
108
+ : ['PUT', `repos/${repo}/rulesets/${id}`];
109
+ run(cwd, ['api', '-X', method, endpoint, '--input', '-'], JSON.stringify(ruleset));
110
+ },
111
+ deleteRuleset(cwd, repo, id) {
112
+ run(cwd, ['api', '-X', 'DELETE', `repos/${repo}/rulesets/${id}`]);
113
+ },
114
+ };
115
+ }
116
+ // The GitHub repository of the checkout at cwd, once gh is there and signed in; else refuses with
117
+ // what to do by hand (`steps`, given why gh cannot).
118
+ function readyRepo(forge, cwd, steps) {
119
+ const status = forge.status(cwd);
120
+ const why = status === 'missing'
121
+ ? 'gh, the GitHub CLI, is not installed'
122
+ : status === 'signed-out'
123
+ ? 'gh is not signed in (gh auth status)'
124
+ : undefined;
125
+ if (why)
126
+ throw new CommandFailure('forge_unavailable', steps(why));
127
+ const repo = forge.repo(cwd);
128
+ if (repo === undefined)
129
+ throw new CommandFailure('forge_unavailable', steps(`gh finds no GitHub repository for ${cwd}`));
130
+ return repo;
131
+ }
132
+ function ghError(error) {
133
+ const stderr = error.stderr;
134
+ const said = typeof stderr === 'string' ? stderr.trim() : '';
135
+ return said || (error instanceof Error ? error.message : String(error));
136
+ }
137
+ // Sets the ruleset on the GitHub repository of the checkout at cwd, creating it or replacing
138
+ // Otea's own; refuses with the steps to take by hand when gh cannot.
139
+ export function installForge(cwd, bases, forge) {
140
+ if (bases.length === 0)
141
+ throw new CommandFailure('not_found', 'No board protects a base branch, so there is nothing for the forge to enforce: in Studio, under the protected Rama, turn on «It protects the base branch too»');
142
+ const repo = readyRepo(forge, cwd, (why) => forgeSteps(bases, why));
143
+ const ruleset = rulesetFor(bases);
144
+ try {
145
+ const kept = forge.rulesets(cwd, repo).find(({ name }) => name === RULESET_NAME);
146
+ forge.saveRuleset(cwd, repo, ruleset, kept?.id);
147
+ const path = `github.com/${repo}`;
148
+ const note = `GitHub now refuses a direct push, a force push and a deletion of ${bases.join(', ')} from any tool: changes reach it through a pull request`;
149
+ return {
150
+ path,
151
+ action: kept ? 'updated' : 'created',
152
+ content: JSON.stringify(ruleset, null, 2),
153
+ note,
154
+ said: `${kept ? 'Updated' : 'Set'} the ruleset "${RULESET_NAME}" on ${path} (${note})`,
155
+ };
156
+ }
157
+ catch (error) {
158
+ throw new CommandFailure('forge_unavailable', forgeSteps(bases, `gh could not set the ruleset on ${repo} (${ghError(error)})`));
159
+ }
160
+ }
161
+ // Takes Otea's ruleset off the GitHub repository of the checkout at cwd, leaving every other one.
162
+ export function removeForge(cwd, forge) {
163
+ const byHand = `delete the ruleset "${RULESET_NAME}" under Settings > Rules > Rulesets on GitHub`;
164
+ const repo = readyRepo(forge, cwd, (why) => `${why}: ${byHand}`);
165
+ const path = `github.com/${repo}`;
166
+ try {
167
+ const kept = forge.rulesets(cwd, repo).find(({ name }) => name === RULESET_NAME);
168
+ if (!kept)
169
+ return { path, action: 'absent', said: `${path} has no Otea ruleset` };
170
+ forge.deleteRuleset(cwd, repo, kept.id);
171
+ return { path, action: 'removed', said: `Removed the ruleset "${RULESET_NAME}" from ${path}` };
172
+ }
173
+ catch (error) {
174
+ throw new CommandFailure('forge_unavailable', `gh could not remove the ruleset on ${repo} (${ghError(error)}): ${byHand}`);
175
+ }
176
+ }
@@ -0,0 +1,340 @@
1
+ import { moment } from '../core/board/notes.js';
2
+ import { groupEvidence } from '../core/placement.js';
3
+ import { DEFAULT_TYPE } from '../core/preset.js';
4
+ import { describeRelation } from '../core/relations.js';
5
+ import { timeText } from '../core/time.js';
6
+ export function columns(rows) {
7
+ const widths = [];
8
+ for (const row of rows) {
9
+ row.forEach((cell, index) => {
10
+ widths[index] = Math.max(widths[index] ?? 0, cell.length);
11
+ });
12
+ }
13
+ return rows
14
+ .map((row) => row
15
+ .map((cell, index) => cell.padEnd(widths[index] ?? 0))
16
+ .join(' ')
17
+ .trimEnd())
18
+ .join('\n');
19
+ }
20
+ export function indent(text) {
21
+ return text.replace(/^/gm, ' ');
22
+ }
23
+ function actorLabel(actor) {
24
+ return `${actor.kind}:${actor.name}`;
25
+ }
26
+ function leaseLabel({ holder, expiresAt }) {
27
+ return `held by ${holder} until ${timeText(expiresAt)}`;
28
+ }
29
+ const notImplicit = (item) => item.type !== DEFAULT_TYPE;
30
+ function itemRow(item, withType) {
31
+ const lease = item.lease ? leaseLabel(item.lease) : '';
32
+ const type = withType ? [item.type] : [];
33
+ return [item.id, ...type, item.state, item.turn, item.title, lease];
34
+ }
35
+ export function formatItem(item, typed = notImplicit) {
36
+ return columns([itemRow(item, typed(item))]);
37
+ }
38
+ // order: the person's order (app/priority.ts), said beside each item it places: "on top 1" for
39
+ // what they put on top, "order 2" for the order they fixed on the Matrix. otea next takes them so.
40
+ export function formatItems(items, typed = notImplicit, order = new Map()) {
41
+ if (items.length === 0)
42
+ return 'No items.';
43
+ const withType = items.some(typed);
44
+ const placed = items.some(({ id }) => orderLabel(order.get(id)) !== '');
45
+ return columns(items.map((item) => {
46
+ const [id = '', ...rest] = itemRow(item, withType);
47
+ const title = rest.splice(withType ? 3 : 2);
48
+ return placed
49
+ ? [id, ...rest, orderLabel(order.get(item.id)), ...title]
50
+ : [id, ...rest, ...title];
51
+ }));
52
+ }
53
+ function orderLabel(priority) {
54
+ if (priority?.pin !== undefined)
55
+ return `on top ${priority.pin}`;
56
+ if (priority?.rank !== undefined)
57
+ return `order ${priority.rank}`;
58
+ return '';
59
+ }
60
+ function fieldLines(fields) {
61
+ const lines = Object.entries(fields).map(([name, value]) => {
62
+ const text = typeof value === 'string' ? value : JSON.stringify(value);
63
+ return text.includes('\n') ? `${name}:\n${indent(text)}` : `${name}: ${text}`;
64
+ });
65
+ return lines.length > 0 ? ['', ...lines] : [];
66
+ }
67
+ function quote(value) {
68
+ if (typeof value !== 'string')
69
+ return '(none)';
70
+ const text = JSON.stringify(value);
71
+ return text.length > 42 ? `${text.slice(0, 40)}…"` : text;
72
+ }
73
+ function describeChanges(changes) {
74
+ const entries = Object.entries((changes ?? {}));
75
+ return entries
76
+ .map(([name, { from, to }]) => `${name}: ${quote(from)} -> ${quote(to)}`)
77
+ .join('; ');
78
+ }
79
+ // A decision relayed from conversation names the agent that relayed it and what the human said.
80
+ function relayNote({ via, quote }) {
81
+ if (typeof via !== 'string')
82
+ return '';
83
+ const said = typeof quote === 'string' ? `: ${JSON.stringify(quote)}` : '';
84
+ return `, relayed by ${via}${said}`;
85
+ }
86
+ function describeEvent(event) {
87
+ return `${describeAction(event)}${relayNote(event.data)}`;
88
+ }
89
+ // Why a lease ended: its holder let it go, a move handed it off, or the person put a stuck item
90
+ // back in the queue of its step or left it for another agent (from Atasco, in the UI).
91
+ function releaseCause(data) {
92
+ if (data.cause === 'handoff')
93
+ return 'handed off';
94
+ if (data.cause === 'restart')
95
+ return 'back in the queue';
96
+ if (data.cause === 'reassign')
97
+ return `left for ${String(data.next)}`;
98
+ if (data.cause === 'later')
99
+ return 'set aside for later';
100
+ return 'released';
101
+ }
102
+ // Why a set-aside lifted (app/set-aside.ts): what the item waited for closed, or the person acted.
103
+ function liftCause(data) {
104
+ const after = typeof data.after === 'string' ? ` with ${data.after}` : '';
105
+ if (data.cause === 'parts')
106
+ return `its parts closed${after}`;
107
+ if (data.cause === 'blockers')
108
+ return `what blocked it closed${after}`;
109
+ if (data.cause === 'note')
110
+ return `the person left note ${String(data.note)}`;
111
+ if (data.cause === 'answer')
112
+ return 'the person answered';
113
+ if (data.cause === 'order')
114
+ return 'the person picked it in the order';
115
+ if (data.cause === 'pin')
116
+ return 'the person put it on top';
117
+ return 'the person took it up again';
118
+ }
119
+ function describeAction({ type, data }) {
120
+ if (type === 'created')
121
+ return String(data.state);
122
+ if (type === 'transitioned') {
123
+ const reason = data.reason === undefined ? '' : ` (${String(data.reason)})`;
124
+ return `${String(data.from)} -> ${String(data.to)}${reason}`;
125
+ }
126
+ if (type === 'updated')
127
+ return describeChanges(data.changes);
128
+ if (type === 'claimed') {
129
+ const previous = data.previous === undefined ? '' : `, taken over from ${String(data.previous)}`;
130
+ return `${String(data.holder)} until ${timeText(String(data.expiresAt))}${previous}`;
131
+ }
132
+ if (type === 'released')
133
+ return `${String(data.holder)} (${releaseCause(data)})`;
134
+ if (type === 'set_aside_lifted')
135
+ return `${String(data.by)}'s set-aside (${liftCause(data)})`;
136
+ if (type === 'relation_added' || type === 'relation_removed') {
137
+ return describeRelation(data);
138
+ }
139
+ if (type === 'handoff_amended')
140
+ return JSON.stringify(String(data.note ?? ''));
141
+ if (type === 'note_withdrawn')
142
+ return `note ${String(data.note)}`;
143
+ if (type === 'note_left' || type === 'note_answered' || type === 'note_edited') {
144
+ const anchor = data.anchor;
145
+ const at = typeof anchor?.seconds === 'number' ? ` at ${moment(anchor.seconds)}` : '';
146
+ const quote = typeof anchor?.quote === 'string' ? `: ${JSON.stringify(anchor.quote)}` : '';
147
+ const line = typeof anchor?.line === 'number' ? ` at line ${anchor.line}${quote}` : '';
148
+ const node = typeof anchor?.node === 'string' ? ` at node ${JSON.stringify(anchor.node)}` : '';
149
+ const where = typeof anchor?.filename === 'string' ? ` (on ${anchor.filename}${at}${line}${node})` : '';
150
+ return `note ${String(data.note)}: ${JSON.stringify(String(data.text ?? ''))}${where}`;
151
+ }
152
+ if (type === 'option_chosen') {
153
+ const comment = typeof data.comment === 'string' ? `: ${JSON.stringify(data.comment)}` : '';
154
+ return `chose ${String(data.option)} · ${String(data.name)}${comment}`;
155
+ }
156
+ if (type === 'question_asked' || type === 'question_answered')
157
+ return `question ${String(data.question)}: ${JSON.stringify(String(data.text ?? ''))}`;
158
+ if (type === 'point_proved') {
159
+ const file = String(data.file);
160
+ const proof = data.kind === 'log'
161
+ ? `${file} line ${String(data.line)}`
162
+ : data.kind === 'test'
163
+ ? `the test ${JSON.stringify(String(data.test))} of ${file} (passes)`
164
+ : `${file} (#${String(data.evidence)})`;
165
+ return `proved ${JSON.stringify(String(data.point))} in ${String(data.part)} with ${proof}`;
166
+ }
167
+ if (type === 'evidence_added') {
168
+ const caption = typeof data.caption === 'string' ? ` (${JSON.stringify(data.caption)})` : '';
169
+ const { evidenceId, role, kind, filename } = data;
170
+ const into = typeof data.module === 'string' ? ` in ${data.module}` : '';
171
+ return `#${String(evidenceId)} ${String(role)} ${String(kind)} ${String(filename)}${into}${caption}`;
172
+ }
173
+ if (type === 'evidence_detached') {
174
+ const from = typeof data.module === 'string' ? ` from ${data.module}` : '';
175
+ return `#${String(data.evidenceId)} ${String(data.filename)}${from}`;
176
+ }
177
+ return JSON.stringify(data);
178
+ }
179
+ function eventRow(event) {
180
+ return [timeText(event.at), actorLabel(event.actor), event.type, describeEvent(event)];
181
+ }
182
+ export function formatEvent(event) {
183
+ return [String(event.id), event.itemId, ...eventRow(event)].join(' ');
184
+ }
185
+ function byteSize(bytes) {
186
+ if (bytes < 1024)
187
+ return `${bytes} B`;
188
+ if (bytes < 1024 * 1024)
189
+ return `${(bytes / 1024).toFixed(1)} KB`;
190
+ return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
191
+ }
192
+ function evidenceRow({ id, role, kind, filename, size, caption }) {
193
+ return [`#${id}`, role, kind, filename, byteSize(size), caption ?? ''];
194
+ }
195
+ // Where an agent opens the files, when show gives their paths (P5-R2-4): one line with the first
196
+ // file's path as the example, since every path differs only by the number and the name. A path on
197
+ // each row cost about 25 tokens a file on every show.
198
+ function openLine(evidence) {
199
+ const first = evidence.find((entry) => entry.path !== undefined);
200
+ return first?.path ? [`Open a file at its number and name: #${first.id} is ${first.path}`] : [];
201
+ }
202
+ // An attached entry, led by the module it went to.
203
+ export function formatEvidence(evidence) {
204
+ const [id = '', ...rest] = evidenceRow(evidence);
205
+ return columns([evidence.module === null ? [id, ...rest] : [id, evidence.module, ...rest]]);
206
+ }
207
+ // `named`: on a board, evidence goes by its name; its hidden id is not a reader's word.
208
+ function moduleHeading({ id, module, variant, required, label }, named) {
209
+ const traits = [module, ...(variant ? [variant] : []), ...(required ? ['required'] : [])];
210
+ if (named && label)
211
+ return `${label} (${traits.join(', ')})`;
212
+ return `${id} (${traits.join(', ')})${label ? `: ${label}` : ''}`;
213
+ }
214
+ function evidenceLines(evidence, layout, named = false) {
215
+ const rows = (entries) => columns(entries.map(evidenceRow));
216
+ const groups = layout
217
+ ? groupEvidence(layout, evidence, named)
218
+ : { modules: [], others: evidence };
219
+ const open = openLine(evidence).map(indent);
220
+ if (groups.modules.length === 0) {
221
+ return evidence.length > 0 ? ['Evidence:', indent(rows(evidence)), ...open, ''] : [];
222
+ }
223
+ const sections = groups.modules.map(({ module, evidence: held }) => [moduleHeading(module, named), indent(held.length > 0 ? rows(held) : 'nothing yet')].join('\n'));
224
+ if (groups.others.length > 0) {
225
+ sections.push(['other files', indent(rows(groups.others))].join('\n'));
226
+ }
227
+ return ['Evidence:', indent(sections.join('\n')), ...open, ''];
228
+ }
229
+ const VIEW_HEADING = {
230
+ parent: 'parent',
231
+ child: 'children',
232
+ blocks: 'blocks',
233
+ blocked_by: 'blocked by',
234
+ duplicates: 'duplicates',
235
+ duplicated_by: 'duplicated by',
236
+ implements: 'implements',
237
+ implemented_by: 'implemented by',
238
+ relates: 'related',
239
+ };
240
+ // The children summary of a parent, then its relations grouped by kind, each other item as a row.
241
+ function relationLines({ relations, children }) {
242
+ const lines = [];
243
+ if (children) {
244
+ const closed = children.total - children.open;
245
+ lines.push(`Children: ${closed} of ${children.total} closed (${children.done} done, ${children.discarded} discarded)`);
246
+ }
247
+ if (relations.length > 0) {
248
+ const groups = new Map();
249
+ for (const { kind, id, state, turn, title } of relations) {
250
+ groups.set(kind, [...(groups.get(kind) ?? []), [id, state, turn, title]]);
251
+ }
252
+ const sections = [...groups].map(([kind, rows]) => `${VIEW_HEADING[kind]}\n${indent(columns(rows))}`);
253
+ lines.push('Relations:', indent(sections.join('\n')));
254
+ }
255
+ return lines.length > 0 ? [...lines, ''] : [];
256
+ }
257
+ // A drop with motives (named once, `motives` its names) says how to give one.
258
+ function movesLine(label, moves) {
259
+ const targets = moves.map(({ to, reasonRequired, motives }) => {
260
+ const said = [
261
+ ...(reasonRequired ? ['reason required'] : []),
262
+ ...(motives?.length ? [`--motive "${motives.join('|')}"`] : []),
263
+ ];
264
+ return said.length > 0 ? `${to} (${said.join('; ')})` : to;
265
+ });
266
+ return `Agent can ${label} to: ${targets.length > 0 ? targets.join(', ') : 'nothing'}`;
267
+ }
268
+ function gatesLine(gates) {
269
+ const verdicts = Object.entries(gates).map(([action, allowed]) => `${action} ${allowed ? 'allowed' : 'blocked'}`);
270
+ return `Gates: ${verdicts.join(', ')}`;
271
+ }
272
+ // Whether the checkouts of the item's repo have Otea's pre-push hook (show, on a repo task).
273
+ export function gitHookLine({ repo, installed, missing, foreign = [], outdated = [], }) {
274
+ if ([installed, missing, foreign, outdated].every((paths) => paths.length === 0))
275
+ return `Git hook: no checkout of ${repo} is known to the project (otea repos add)`;
276
+ const said = [
277
+ ...(installed.length > 0 ? [`installed in ${installed.join(', ')}`] : []),
278
+ ...(outdated.length > 0
279
+ ? [
280
+ `outdated in ${outdated.join(', ')} (it lets a push through when Otea cannot check it): run otea hook install --git there`,
281
+ ]
282
+ : []),
283
+ ...(missing.length > 0
284
+ ? [`not installed in ${missing.join(', ')}: run otea hook install --git there`]
285
+ : []),
286
+ ...(foreign.length > 0
287
+ ? [
288
+ `${foreign.join(', ')} ${foreign.length === 1 ? 'has a pre-push hook' : 'have pre-push hooks'} of its own: add Otea's check to it (otea hook install --git prints the lines)`,
289
+ ]
290
+ : []),
291
+ ];
292
+ return `Git hook: ${said.join('; ')}`;
293
+ }
294
+ function createdLine({ createdBy, createdAt, events }) {
295
+ const channel = events.find(({ type }) => type === 'created')?.data.channel;
296
+ const via = typeof channel === 'string' ? ` via ${channel}` : '';
297
+ return `created by ${actorLabel(createdBy)}${via} at ${timeText(createdAt)}`;
298
+ }
299
+ // With the item type's layout, evidence is grouped by the module that draws it.
300
+ // `named`: the item is on a board and reads by names (states, fields and moves already are).
301
+ export function formatItemWithEvents(item, layout, typed = notImplicit, named = false) {
302
+ return [
303
+ `${item.id} ${item.title}`,
304
+ `state: ${item.state} turn: ${item.turn} ${typed(item) ? `type: ${item.type} ` : ''}collection: ${item.collection}`,
305
+ ...(item.lease ? [leaseLabel(item.lease)] : []),
306
+ createdLine(item),
307
+ // On a board the hint is next's whole answer, indented under its heading.
308
+ ...(item.hint
309
+ ? [
310
+ item.hint.includes('\n')
311
+ ? `Next:\n${indent(item.hint).replace(/^ +$/gm, '')}`
312
+ : `Next: ${item.hint}`,
313
+ ]
314
+ : []),
315
+ ...fieldLines(item.fields),
316
+ '',
317
+ ...(item.missing.length > 0 && item.turn !== 'none'
318
+ ? [`Missing to complete: ${item.missing.join(', ')}`]
319
+ : []),
320
+ // On a board, Next: says how to finish the step; what is left to relay still shows.
321
+ ...(named ? [] : [movesLine('move', item.transitions)]),
322
+ ...(named && item.relayable.length === 0 ? [] : [movesLine('relay', item.relayable)]),
323
+ ...(item.gates ? [gatesLine(item.gates)] : []),
324
+ ...(item.gitHook ? [gitHookLine(item.gitHook)] : []),
325
+ '',
326
+ ...relationLines(item),
327
+ ...evidenceLines(item.evidence, layout, named),
328
+ 'Events:',
329
+ indent(columns(item.events.map(eventRow))),
330
+ ].join('\n');
331
+ }
332
+ function plural(count, noun) {
333
+ return `${count} ${noun}${count === 1 ? '' : 's'}`;
334
+ }
335
+ export function formatReport({ errors, warnings, findings }) {
336
+ if (findings.length === 0)
337
+ return 'No problems found.';
338
+ const rows = findings.map(({ severity, subject, message }) => [severity, subject, message]);
339
+ return `${columns(rows)}\n${plural(errors, 'error')}, ${plural(warnings, 'warning')}`;
340
+ }
package/dist/cli/gh.js ADDED
@@ -0,0 +1,17 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ // gh asks the forge over the network, so a command never waits on it longer than this.
3
+ export const GH_TIMEOUT_MS = 10_000;
4
+ // A PR's state (OPEN, CLOSED, MERGED) and head branch, asked of gh in the repo at cwd; undefined
5
+ // when gh is missing, fails or takes too long: the caller goes on without it.
6
+ export function prState(cwd, pr, gh) {
7
+ if (gh === undefined)
8
+ return undefined;
9
+ try {
10
+ const read = execFileSync(gh, ['pr', 'view', pr, '--json', 'state,headRefName', '--jq', '.state + " " + .headRefName'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: GH_TIMEOUT_MS }).trim();
11
+ const [state = '', head = ''] = read.split(' ');
12
+ return state === '' || head === '' ? undefined : { state, head };
13
+ }
14
+ catch {
15
+ return undefined;
16
+ }
17
+ }