@mainwave/cli 0.3.0 → 0.4.0-rc.1

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 (80) hide show
  1. package/README.md +94 -10
  2. package/dist/adapters/claude-code.js +3 -0
  3. package/dist/adapters/claude-code.js.map +1 -1
  4. package/dist/adapters/codex-cli.js +10 -1
  5. package/dist/adapters/codex-cli.js.map +1 -1
  6. package/dist/adapters/copilot-chat.js +13 -0
  7. package/dist/adapters/copilot-chat.js.map +1 -1
  8. package/dist/adapters/copilot-cli.js +2 -0
  9. package/dist/adapters/copilot-cli.js.map +1 -1
  10. package/dist/adapters/cursor-enterprise.js +146 -0
  11. package/dist/adapters/cursor-enterprise.js.map +1 -0
  12. package/dist/adapters/cursor.js +197 -0
  13. package/dist/adapters/cursor.js.map +1 -0
  14. package/dist/adapters/index.js +4 -0
  15. package/dist/adapters/index.js.map +1 -1
  16. package/dist/api/index.js +3 -0
  17. package/dist/api/index.js.map +1 -0
  18. package/dist/api/types.gen.js +3 -0
  19. package/dist/api/types.gen.js.map +1 -0
  20. package/dist/core/apply.js +258 -0
  21. package/dist/core/apply.js.map +1 -0
  22. package/dist/core/auth-commands.js +157 -0
  23. package/dist/core/auth-commands.js.map +1 -0
  24. package/dist/core/behaviour-hooks.js +101 -0
  25. package/dist/core/behaviour-hooks.js.map +1 -0
  26. package/dist/core/browser.js +41 -0
  27. package/dist/core/browser.js.map +1 -0
  28. package/dist/core/codecs/cursor-hooks-json.js +90 -0
  29. package/dist/core/codecs/cursor-hooks-json.js.map +1 -0
  30. package/dist/core/detect.js +52 -0
  31. package/dist/core/detect.js.map +1 -0
  32. package/dist/core/device-login.js +76 -0
  33. package/dist/core/device-login.js.map +1 -0
  34. package/dist/core/doctor.js +51 -2
  35. package/dist/core/doctor.js.map +1 -1
  36. package/dist/core/errors.js +23 -0
  37. package/dist/core/errors.js.map +1 -1
  38. package/dist/core/flags.js +57 -0
  39. package/dist/core/flags.js.map +1 -0
  40. package/dist/core/headers.js +15 -1
  41. package/dist/core/headers.js.map +1 -1
  42. package/dist/core/interview.js +198 -0
  43. package/dist/core/interview.js.map +1 -0
  44. package/dist/core/keys.js +41 -0
  45. package/dist/core/keys.js.map +1 -0
  46. package/dist/core/markers.js +5 -1
  47. package/dist/core/markers.js.map +1 -1
  48. package/dist/core/platform.js +152 -0
  49. package/dist/core/platform.js.map +1 -0
  50. package/dist/core/prompts.js +68 -22
  51. package/dist/core/prompts.js.map +1 -1
  52. package/dist/core/status.js +25 -1
  53. package/dist/core/status.js.map +1 -1
  54. package/dist/core/store.js +118 -0
  55. package/dist/core/store.js.map +1 -0
  56. package/dist/core/tty.js +6 -0
  57. package/dist/core/tty.js.map +1 -1
  58. package/dist/core/ucid.js +25 -0
  59. package/dist/core/ucid.js.map +1 -0
  60. package/dist/core/ui.js +26 -0
  61. package/dist/core/ui.js.map +1 -0
  62. package/dist/core/use-case.js +99 -0
  63. package/dist/core/use-case.js.map +1 -0
  64. package/dist/core/validate.js +22 -0
  65. package/dist/core/validate.js.map +1 -1
  66. package/dist/core/verify.js +154 -0
  67. package/dist/core/verify.js.map +1 -0
  68. package/dist/core/wizard.js +148 -278
  69. package/dist/core/wizard.js.map +1 -1
  70. package/dist/main.js +185 -29
  71. package/dist/main.js.map +1 -1
  72. package/hooks/cursor-otlp.mjs +244 -0
  73. package/hooks/github-pr-marker.mjs +30 -10
  74. package/hooks/jira-ticket-marker.mjs +69 -17
  75. package/hooks/linear-ticket-marker.mjs +75 -12
  76. package/hooks/marker-core.mjs +5 -0
  77. package/hooks/matchers.json +2 -2
  78. package/hooks/vocabulary.d.mts +35 -0
  79. package/hooks/vocabulary.mjs +109 -0
  80. package/package.json +6 -3
@@ -8,19 +8,24 @@
8
8
  // key out of the tool *result*, and emits one small OTLP marker span so the
9
9
  // platform counts distinct tickets filed instead of raw tool calls.
10
10
  //
11
- // Crucially it emits the SAME `mainwave.ticket_marker` span and the SAME
12
- // `linear.issue_id` / `linear.op` / `linear.issue_url` attribute keys the Linear
13
- // hook does, because the read side (app/read/activity_rollup.py) matches on those
14
- // exact keys. The `linear.*` names are a deliberate misnomer here — they are the
15
- // storage-agnostic "tickets filed" contract, not a Linear-specific field — so
16
- // Jira tickets count with no backend change. A future rename to `ticket.*` would
17
- // touch both hooks and the reader together.
11
+ // It emits the SAME v2 work-item events (work.item.created / .updated) and the
12
+ // SAME work.item.* keys as the Linear hook; the two are told apart by
13
+ // `work.vendor` (jira vs linear) — the fix for the old vendor-blind `linear.*`
14
+ // misnomer, where a Jira and a Linear ticket were indistinguishable (MAI-1469 /
15
+ // MAI-1480). The read side (app/read/_vocab.py) coalesces the v2 keys over the
16
+ // legacy `linear.*` ones, so history keeps counting.
18
17
  //
19
18
  // Shared OTLP plumbing (config resolution, MAI-936 source neutralization, payload
20
19
  // build, fail-open emit) lives in ./marker-core.mjs; this file keeps only the
21
- // Jira-specific extraction and main(). Privacy: emits the issue key (e.g.
22
- // "KAN-4"), the operation, and the issue url only — never the summary or body.
23
- // Fails open and fast so a telemetry hiccup can never block or slow the session.
20
+ // Jira-specific extraction and main(). Emits the issue key (work.item.id, e.g.
21
+ // "KAN-4"), vendor (work.vendor=jira), issue url, operation, and work.instance
22
+ // (the site cloudId from the result envelope's top-level context.cloudId) —
23
+ // never the summary or body. work.instance is best-effort: present when the MCP
24
+ // result carries the cloudId, omitted when it doesn't. It matches the value the
25
+ // Jira connector (MAI-1465) emits, so MAI-1483 can reconcile marker spans against
26
+ // connector events on a shared instance id (MAI-1480 first deferred it, wrongly
27
+ // assuming a hook couldn't produce it). Fails open and fast so a telemetry hiccup
28
+ // can never block or slow the session.
24
29
 
25
30
  import { homedir } from 'node:os'
26
31
  import { join } from 'node:path'
@@ -36,6 +41,18 @@ import {
36
41
  readStdin,
37
42
  toolOutput,
38
43
  } from './marker-core.mjs'
44
+ import {
45
+ ATTR_WORK_INSTANCE,
46
+ ATTR_WORK_ITEM_ID,
47
+ ATTR_WORK_ITEM_OP,
48
+ ATTR_WORK_ITEM_URL,
49
+ ATTR_WORK_VENDOR,
50
+ VENDOR_JIRA,
51
+ WI_CREATED,
52
+ WI_UPDATED,
53
+ WORK_OP_CREATED,
54
+ WORK_OP_UPDATED,
55
+ } from './vocabulary.mjs'
39
56
 
40
57
  const log = makeLog(
41
58
  process.env.MAINWAVE_HOOK_LOG || join(homedir(), '.mainwave-jira-ticket-marker.log'),
@@ -44,7 +61,7 @@ const log = makeLog(
44
61
  // The same non-coding source/service the Linear ticket hook stamps, so a Jira
45
62
  // marker is classified identically to a Linear one: an ordinary ("other") span
46
63
  // that stays out of the coding-work segmentation (MAI-936).
47
- const MARKER_SOURCE = 'mainwave.ticket_marker'
64
+ const MARKER_SOURCE = 'hook.jira'
48
65
  const MARKER_SERVICE = 'mainwave.ticket-hook'
49
66
 
50
67
  const KEY = '[A-Z][A-Z0-9]+-\\d+'
@@ -112,21 +129,54 @@ export const extractIssueUrl = (toolResult) => {
112
129
  return url && new RegExp(`/(?:browse|issue)/${KEY}`, 'i').test(url) ? url : undefined
113
130
  }
114
131
 
132
+ /**
133
+ * The Jira site cloudId (work.instance) from a create/edit result — the immutable
134
+ * site-global id the connector also emits, so a marker span and a connector event
135
+ * on the same site reconcile (MAI-1483). The Atlassian MCP envelope carries it at
136
+ * TOP-LEVEL `context.cloudId`, a sibling of `issues` — NOT under `issues.nodes[0]`
137
+ * — so this reads the full parsed result, not the issue node. Best-effort:
138
+ * undefined for a non-JSON result or one without the cloudId, so the attr is
139
+ * dropped rather than fabricated (the node's numeric `id` is site-scoped, not a
140
+ * global id, so it is never a substitute). Never throws.
141
+ */
142
+ export const extractInstance = (toolResult) => {
143
+ const cloudId = resultObject(toolResult)?.context?.cloudId
144
+ return typeof cloudId === 'string' && cloudId ? cloudId : undefined
145
+ }
146
+
115
147
  /** create for the createJiraIssue tool, update for editJiraIssue (or anything
116
148
  * else that reaches this hook). Op is derived from the tool NAME — unlike Linear,
117
149
  * Jira splits create and edit across two tools rather than one save call. An
118
150
  * `update` is counted as "ticket updated", never filed. */
119
151
  export const detectOp = (toolName) =>
120
- typeof toolName === 'string' && toolName.endsWith('createJiraIssue') ? 'create' : 'update'
152
+ typeof toolName === 'string' && toolName.endsWith('createJiraIssue')
153
+ ? WORK_OP_CREATED
154
+ : WORK_OP_UPDATED
121
155
 
122
156
  /** Build the OTLP/JSON payload for one Jira ticket-marker span. Emits the same
123
- * span name and `linear.*` attribute contract as the Linear hook so the reader
124
- * counts it unchanged. `issueUrl` is dropped by `buildMarkerPayload` when absent. */
125
- export const buildTracePayload = ({ issueKey, issueUrl, op, sessionId, resourceAttrs, nowNs }) =>
157
+ * v2 work-item event names and keys as the Linear hook — the two are now told
158
+ * apart by `work.vendor` (jira vs linear), the fix for the vendor-blind
159
+ * `linear.*`-on-Jira misnomer (MAI-1469 / MAI-1480). `issueUrl` and `instance`
160
+ * are dropped by `buildMarkerPayload` when absent. */
161
+ export const buildTracePayload = ({
162
+ issueKey,
163
+ issueUrl,
164
+ instance,
165
+ op,
166
+ sessionId,
167
+ resourceAttrs,
168
+ nowNs,
169
+ }) =>
126
170
  buildMarkerPayload({
127
- spanName: 'mainwave.ticket_marker',
171
+ spanName: op === WORK_OP_CREATED ? WI_CREATED : WI_UPDATED,
128
172
  scopeName: 'mainwave.jira-ticket-marker',
129
- attributes: { 'linear.issue_id': issueKey, 'linear.op': op, 'linear.issue_url': issueUrl },
173
+ attributes: {
174
+ [ATTR_WORK_ITEM_ID]: issueKey,
175
+ [ATTR_WORK_ITEM_OP]: op,
176
+ [ATTR_WORK_ITEM_URL]: issueUrl,
177
+ [ATTR_WORK_VENDOR]: VENDOR_JIRA,
178
+ [ATTR_WORK_INSTANCE]: instance,
179
+ },
130
180
  sessionId,
131
181
  resourceAttrs,
132
182
  source: MARKER_SOURCE,
@@ -150,6 +200,7 @@ const main = async () => {
150
200
  return
151
201
  }
152
202
  const issueUrl = extractIssueUrl(output)
203
+ const instance = extractInstance(output)
153
204
  const op = detectOp(payload.tool_name)
154
205
 
155
206
  const cwd = payload.cwd || process.cwd()
@@ -170,6 +221,7 @@ const main = async () => {
170
221
  const body = buildTracePayload({
171
222
  issueKey,
172
223
  issueUrl,
224
+ instance,
173
225
  op,
174
226
  sessionId: payload.session_id,
175
227
  resourceAttrs,
@@ -17,9 +17,16 @@
17
17
  //
18
18
  // Shared OTLP plumbing (config resolution, MAI-936 source neutralization,
19
19
  // payload build, fail-open emit) lives in ./marker-core.mjs; this file keeps
20
- // only the ticket-specific extraction and main(). Privacy: emits the issue key
21
- // (e.g. "MAI-930") and the operation only — never the ticket title or body.
22
- // Fails open and fast so a telemetry hiccup can never block or slow the session.
20
+ // only the ticket-specific extraction and main(). Emits the v2 work-item
21
+ // vocabulary — the issue key (work.item.id, e.g. "MAI-930"), vendor
22
+ // (work.vendor=linear), issue url, operation (the typed event name
23
+ // work.item.created / .updated), and work.instance (the Linear team UUID from
24
+ // the save_issue result's teamId / team.id) — never the ticket title or body.
25
+ // work.instance is best-effort: present when the MCP result carries the team id,
26
+ // omitted when it doesn't. It matches the value the connector emits, so MAI-1483
27
+ // can reconcile marker spans against connector events on a shared instance id
28
+ // (MAI-1480 first deferred it, wrongly assuming a hook couldn't produce it).
29
+ // Fails open and fast so a telemetry hiccup can never block the session.
23
30
 
24
31
  import { homedir } from 'node:os'
25
32
  import { join } from 'node:path'
@@ -36,6 +43,18 @@ import {
36
43
  readStdin,
37
44
  toolOutput,
38
45
  } from './marker-core.mjs'
46
+ import {
47
+ ATTR_WORK_INSTANCE,
48
+ ATTR_WORK_ITEM_ID,
49
+ ATTR_WORK_ITEM_OP,
50
+ ATTR_WORK_ITEM_URL,
51
+ ATTR_WORK_VENDOR,
52
+ VENDOR_LINEAR,
53
+ WI_CREATED,
54
+ WI_UPDATED,
55
+ WORK_OP_CREATED,
56
+ WORK_OP_UPDATED,
57
+ } from './vocabulary.mjs'
39
58
 
40
59
  // Re-export the shared pure helpers so existing importers keep resolving them here.
41
60
  export {
@@ -52,7 +71,7 @@ const log = makeLog(process.env.MAINWAVE_HOOK_LOG || join(homedir(), '.mainwave-
52
71
  // A source tag the collector does NOT classify as a coding agent, and a service
53
72
  // name outside its coding-agent `service.name` allow-list, so the marker lands
54
73
  // as an ordinary ("other") span rather than a Claude Code one (MAI-936).
55
- const MARKER_SOURCE = 'mainwave.ticket_marker'
74
+ const MARKER_SOURCE = 'hook.linear'
56
75
  const MARKER_SERVICE = 'mainwave.ticket-hook'
57
76
 
58
77
  const KEY = '[A-Z][A-Z0-9]+-\\d+'
@@ -81,6 +100,13 @@ const resultObject = (toolResult) => {
81
100
  return undefined // a plain string result, not JSON
82
101
  }
83
102
  }
103
+ // MCP tool-result wrapper: `{content: [{type:'text', text:'<json>'}], isError}`.
104
+ // Codex returns save_issue this way (Claude Code hands the bare array); unwrap
105
+ // to the content array so the issue JSON inside `text` is parsed, not the
106
+ // wrapper — which carries neither `id` nor `url` (MAI-1218).
107
+ if (v && typeof v === 'object' && !Array.isArray(v) && Array.isArray(v.content)) {
108
+ v = v.content
109
+ }
84
110
  if (Array.isArray(v)) {
85
111
  const text = v.map((b) => (b && typeof b.text === 'string' ? b.text : '')).join('')
86
112
  try {
@@ -130,6 +156,21 @@ export const extractIssueUrl = (toolResult) => {
130
156
  return url && new RegExp(`/issue/${KEY}`, 'i').test(url) ? url : undefined
131
157
  }
132
158
 
159
+ /**
160
+ * The Linear team UUID (work.instance) from a save_issue result — the immutable
161
+ * instance-global id the connector also emits, so a marker span and a connector
162
+ * event on the same team reconcile (MAI-1483). The linear-server MCP puts it at
163
+ * top-level `teamId`; some other Linear MCPs nest it at `team.id` — read either.
164
+ * Best-effort: undefined for a non-JSON result or one carrying neither, so the
165
+ * attr is dropped rather than fabricated (the result's `id` is the display KEY,
166
+ * not the global id, so it is never a substitute). Never throws.
167
+ */
168
+ export const extractInstance = (toolResult) => {
169
+ const obj = resultObject(toolResult)
170
+ const instance = obj?.teamId ?? obj?.team?.id
171
+ return typeof instance === 'string' && instance ? instance : undefined
172
+ }
173
+
133
174
  /**
134
175
  * create vs update, preferring the tool NAME when it says so. `save_issue` is one
135
176
  * tool for both operations, so the only signal there is whether the input carried
@@ -141,23 +182,43 @@ export const extractIssueUrl = (toolResult) => {
141
182
  */
142
183
  export const detectOp = (toolName, toolInput) => {
143
184
  if (typeof toolName === 'string') {
144
- if (toolName.endsWith('create_issue')) return 'create'
145
- if (toolName.endsWith('update_issue')) return 'update'
185
+ if (toolName.endsWith('create_issue')) return WORK_OP_CREATED
186
+ if (toolName.endsWith('update_issue')) return WORK_OP_UPDATED
146
187
  }
147
- return toolInput && toolInput.id ? 'update' : 'create'
188
+ return toolInput && toolInput.id ? WORK_OP_UPDATED : WORK_OP_CREATED
148
189
  }
149
190
 
150
191
  /** Marker resource attrs with the ticket hook's non-coding source/service (MAI-936). */
151
192
  export const markerResourceAttrs = (resourceAttrs) =>
152
193
  coreMarkerResourceAttrs(resourceAttrs, MARKER_SOURCE, MARKER_SERVICE)
153
194
 
154
- /** Build the OTLP/JSON payload for one ticket-marker span. `issueUrl` is dropped
155
- * by `buildMarkerPayload` when absent (an older result, or no issue url). */
156
- export const buildTracePayload = ({ issueKey, issueUrl, op, sessionId, resourceAttrs, nowNs }) =>
195
+ /** Build the OTLP/JSON payload for one ticket-marker span. The v2 event NAME
196
+ * encodes the operation (work.item.created / work.item.updated); the span
197
+ * self-declares `mainwave.source = hook.linear`, honored verbatim by the
198
+ * collector (MAI-1539). It stays out of coding-activity segmentation because
199
+ * `hook.*` is outside the CODING_TOOL_SOURCES allowlist and markers are admitted
200
+ * by span NAME (MAI-936) — not because of the old `other` fallback. `issueUrl`
201
+ * and `instance` are dropped by `buildMarkerPayload` when absent (an older
202
+ * result with no url, or one that carries no team id). */
203
+ export const buildTracePayload = ({
204
+ issueKey,
205
+ issueUrl,
206
+ instance,
207
+ op,
208
+ sessionId,
209
+ resourceAttrs,
210
+ nowNs,
211
+ }) =>
157
212
  buildMarkerPayload({
158
- spanName: 'mainwave.ticket_marker',
213
+ spanName: op === WORK_OP_CREATED ? WI_CREATED : WI_UPDATED,
159
214
  scopeName: 'mainwave.linear-ticket-marker',
160
- attributes: { 'linear.issue_id': issueKey, 'linear.op': op, 'linear.issue_url': issueUrl },
215
+ attributes: {
216
+ [ATTR_WORK_ITEM_ID]: issueKey,
217
+ [ATTR_WORK_ITEM_OP]: op,
218
+ [ATTR_WORK_ITEM_URL]: issueUrl,
219
+ [ATTR_WORK_VENDOR]: VENDOR_LINEAR,
220
+ [ATTR_WORK_INSTANCE]: instance,
221
+ },
161
222
  sessionId,
162
223
  resourceAttrs,
163
224
  source: MARKER_SOURCE,
@@ -181,6 +242,7 @@ const main = async () => {
181
242
  return
182
243
  }
183
244
  const issueUrl = extractIssueUrl(output)
245
+ const instance = extractInstance(output)
184
246
  const op = detectOp(payload.tool_name, payload.tool_input)
185
247
 
186
248
  const cwd = payload.cwd || process.cwd()
@@ -201,6 +263,7 @@ const main = async () => {
201
263
  const body = buildTracePayload({
202
264
  issueKey,
203
265
  issueUrl,
266
+ instance,
204
267
  op,
205
268
  sessionId: payload.session_id,
206
269
  resourceAttrs,
@@ -13,6 +13,8 @@ import { appendFileSync, readFileSync } from 'node:fs'
13
13
  import { homedir } from 'node:os'
14
14
  import { join } from 'node:path'
15
15
 
16
+ import { ATTR_SCHEMA_VERSION, SCHEMA_VERSION } from './vocabulary.mjs'
17
+
16
18
  const EMIT_TIMEOUT_MS = 3000
17
19
 
18
20
  /** A best-effort appender to `logPath` — never throws (a log hiccup must not
@@ -166,6 +168,9 @@ export const markerResourceAttrs = (resourceAttrs, source, service) => ({
166
168
  ...(resourceAttrs ?? {}),
167
169
  'mainwave.source': source,
168
170
  'service.name': service,
171
+ // The v2 contract stamp on every hook emission (marker + cursor), so the
172
+ // collector shim's lifetime can be measured against v1-vs-v2 traffic (MAI-1480).
173
+ [ATTR_SCHEMA_VERSION]: SCHEMA_VERSION,
169
174
  })
170
175
 
171
176
  const attr = (key, stringValue) => ({ key, value: { stringValue } })
@@ -1,8 +1,8 @@
1
1
  [
2
2
  {
3
3
  "hook": "linear-ticket-marker.mjs",
4
- "matcher": "^mcp__.*[Ll]inear.*__(save|create|update)_issue$",
5
- "why": "The server PREFIX is what varies: this workspace connects Linear as mcp__linear-server__save_issue, the older integration as mcp__linear__save_issue — same tool name, and matching only the latter is what silently emitted nothing. create_issue / update_issue are covered defensively in case an integration splits the save; detectOp reads the op off the tool name and falls back to the input's id. Anchored because linear-server really does expose create_issue_label."
4
+ "matcher": "^mcp__.*[Ll]inear.*_(save|create|update)_issue$",
5
+ "why": "The server PREFIX and the separator both vary. Prefix: this workspace connects Linear as mcp__linear-server__save_issue, the older integration as mcp__linear__save_issue, and Codex exposes it as mcp__codex_apps__linear_save_issue — a SINGLE underscore before save_issue (MAI-1218). So the separator is `.*_` (one-or-more via the greedy `.*`, which absorbs the extra underscore in the __ forms) rather than a literal `__`. create_issue / update_issue are covered defensively in case an integration splits the save; detectOp reads the op off the tool name and falls back to the input's id. Anchored (`$`) because linear-server really does expose create_issue_label — the trailing `_issue$` excludes it."
6
6
  },
7
7
  {
8
8
  "hook": "github-pr-marker.mjs",
@@ -0,0 +1,35 @@
1
+ // Type declarations for vocabulary.mjs — the hooks are runtime-dep-free .mjs and
2
+ // aren't compiled by tsc, but the vitest registry-conformance test (.ts) imports
3
+ // this module, so NodeNext needs a .d.mts sibling to type it (MAI-1480).
4
+
5
+ export const ATTR_SCHEMA_VERSION: string
6
+ export const SCHEMA_VERSION: string
7
+
8
+ export const WI_CREATED: string
9
+ export const WI_UPDATED: string
10
+ export const ATTR_WORK_ITEM_ID: string
11
+ export const ATTR_WORK_ITEM_OP: string
12
+ export const ATTR_WORK_ITEM_URL: string
13
+ export const ATTR_WORK_VENDOR: string
14
+ export const ATTR_WORK_INSTANCE: string
15
+ export const WORK_OP_CREATED: string
16
+ export const WORK_OP_UPDATED: string
17
+ export const VENDOR_LINEAR: string
18
+ export const VENDOR_JIRA: string
19
+ export const WORK_MARKER_KEYS: readonly string[]
20
+
21
+ export const VCS_OPENED: string
22
+ export const ATTR_VCS_REPOSITORY_URL_FULL: string
23
+ export const ATTR_VCS_CHANGE_ID: string
24
+ export const ATTR_VCS_CHANGE_TITLE: string
25
+ export const ATTR_VCS_PROVIDER_NAME: string
26
+ export const ATTR_VCS_CHANGE_FILES_CHANGED: string
27
+ export const ATTR_VCS_CHANGE_LINES_ADDED: string
28
+ export const ATTR_VCS_CHANGE_LINES_REMOVED: string
29
+ export const VCS_PROVIDER_GITHUB: string
30
+ export const VCS_MARKER_KEYS: readonly string[]
31
+
32
+ export const ATTR_CODE_FILE_PATH: string
33
+ export const CODE_KEYS: readonly string[]
34
+
35
+ export const CLI_EVENT_NAMES: readonly string[]
@@ -0,0 +1,109 @@
1
+ // The v2 telemetry vocabulary the CLI marker + cursor hooks emit (MAI-1480).
2
+ //
3
+ // This is the CLI's checkable copy of the work.item.* / vcs.change.* / code.*
4
+ // contract in the repo-root `telemetry/registry.yaml` — the .mjs twin of the
5
+ // backend's `app/devtool/vocabulary.py`. The conformance test
6
+ // `tests/registry-conformance.test.ts` asserts every name and key declared here
7
+ // is a registered `emitted` entry, so a name changed on one side without the
8
+ // other fails the build (telemetry/README.md § Enforcement coverage).
9
+ //
10
+ // Unlike the poller connector, a marker hook mints a RANDOM span id per emit
11
+ // (marker-core `randomBytes`), and the read side counts distinct entity ids
12
+ // (`uniqExact(work.item.id)`), not span ids. So there is no frozen `id_seed`
13
+ // concern here — renaming a marker event name never re-mints history the way it
14
+ // would for the connector's deterministic span ids (see vocabulary.py). The
15
+ // marker self-declares `mainwave.source = hook.<vendor>` (MAI-1539), honored
16
+ // verbatim by the collector's Generic processor. It stays out of coding-activity
17
+ // segmentation because `hook.*` is outside the CODING_TOOL_SOURCES allowlist and
18
+ // markers are admitted by span NAME (MAI-936) — NOT because of the old `other`
19
+ // fallback (before MAI-1539 the hooks stamped `mainwave.ticket_marker` /
20
+ // `mainwave.pr_marker`, which the collector ignored and mapped to `other`).
21
+
22
+ // ── The v2 contract stamp ───────────────────────────────────────────────────
23
+ // Every v2 emission stamps this on its resource; v1 traffic carries no stamp,
24
+ // and the collector shim's lifetime is measured against it (registry header).
25
+ export const ATTR_SCHEMA_VERSION = 'mainwave.schema.version'
26
+ export const SCHEMA_VERSION = '2'
27
+
28
+ // ── Work-item events (tickets) — CLI ticket-marker hooks ─────────────────────
29
+ // The event NAME encodes the operation (a v2 event's name IS its op), so create
30
+ // and update are distinct span names rather than one span discriminated by an
31
+ // attribute the way the v1 `mainwave.ticket_marker` + `linear.op` pair was.
32
+ export const WI_CREATED = 'work.item.created'
33
+ export const WI_UPDATED = 'work.item.updated'
34
+
35
+ export const ATTR_WORK_ITEM_ID = 'work.item.id'
36
+ export const ATTR_WORK_ITEM_OP = 'work.item.op'
37
+ export const ATTR_WORK_ITEM_URL = 'work.item.url'
38
+ export const ATTR_WORK_VENDOR = 'work.vendor'
39
+ // The vendor's immutable instance/site global id — the same value the connector
40
+ // emits as work.instance (Linear team UUID, Jira site cloudId). A marker CAN
41
+ // produce it after all: it sits in the MCP save result the hook already parses
42
+ // (Linear's top-level teamId, Jira's context.cloudId). Emitted best-effort —
43
+ // present when the result supplies it, cleanly omitted otherwise — so MAI-1483
44
+ // can reconcile marker spans against connector events on a shared instance id.
45
+ // (MAI-1480 first deferred this on the assumption a hook couldn't produce the
46
+ // global id; live MCP probes disproved that — MAI-1481 follow-up.)
47
+ export const ATTR_WORK_INSTANCE = 'work.instance'
48
+
49
+ // `work.item.op` values — the registry's entities.item.operations axis. Past
50
+ // tense, matching the connector (vocabulary.py WORK_ITEM_OP_*), not the v1
51
+ // `linear.op` present-tense create/update.
52
+ export const WORK_OP_CREATED = 'created'
53
+ export const WORK_OP_UPDATED = 'updated'
54
+
55
+ // `work.vendor` values a ticket marker stamps — the fix for the vendor-blind
56
+ // `linear.*`-on-Jira misnomer (MAI-1469): a Jira and a Linear ticket are now
57
+ // distinguishable end to end.
58
+ export const VENDOR_LINEAR = 'linear'
59
+ export const VENDOR_JIRA = 'jira'
60
+
61
+ // The exact work keys a ticket marker may emit — what the conformance test
62
+ // checks against the registry's `emitted` work entries.
63
+ export const WORK_MARKER_KEYS = [
64
+ ATTR_WORK_ITEM_ID,
65
+ ATTR_WORK_ITEM_OP,
66
+ ATTR_WORK_ITEM_URL,
67
+ ATTR_WORK_VENDOR,
68
+ ATTR_WORK_INSTANCE,
69
+ ]
70
+
71
+ // ── Change-request events (PRs) — CLI github-pr-marker hook ──────────────────
72
+ // `gh pr create` only ever opens; merged/closed/review are the poller
73
+ // connector's to emit (a hook sees the create call, not the later lifecycle).
74
+ export const VCS_OPENED = 'vcs.change.opened'
75
+
76
+ // The PR URL lands under vcs.repository.url.full and the PR number under
77
+ // vcs.change.id — the registry alias map for github.pr_url / github.pr_number
78
+ // (a house mapping the read side already coalesces on; app/read/_vocab.py).
79
+ export const ATTR_VCS_REPOSITORY_URL_FULL = 'vcs.repository.url.full'
80
+ export const ATTR_VCS_CHANGE_ID = 'vcs.change.id'
81
+ export const ATTR_VCS_CHANGE_TITLE = 'vcs.change.title'
82
+ export const ATTR_VCS_PROVIDER_NAME = 'vcs.provider.name'
83
+ export const ATTR_VCS_CHANGE_FILES_CHANGED = 'vcs.change.files_changed'
84
+ export const ATTR_VCS_CHANGE_LINES_ADDED = 'vcs.change.lines_added'
85
+ export const ATTR_VCS_CHANGE_LINES_REMOVED = 'vcs.change.lines_removed'
86
+
87
+ // `vcs.provider.name` value — vendor-as-value, replacing the implicit vendor in
88
+ // the old `github.pr_*` key prefix.
89
+ export const VCS_PROVIDER_GITHUB = 'github'
90
+
91
+ export const VCS_MARKER_KEYS = [
92
+ ATTR_VCS_REPOSITORY_URL_FULL,
93
+ ATTR_VCS_CHANGE_ID,
94
+ ATTR_VCS_CHANGE_TITLE,
95
+ ATTR_VCS_PROVIDER_NAME,
96
+ ATTR_VCS_CHANGE_FILES_CHANGED,
97
+ ATTR_VCS_CHANGE_LINES_ADDED,
98
+ ATTR_VCS_CHANGE_LINES_REMOVED,
99
+ ]
100
+
101
+ // ── File references — CLI cursor behaviour hook ──────────────────────────────
102
+ // The standard OTel Code (Stable) key, replacing the hook's former
103
+ // `cursor.file_path`.
104
+ export const ATTR_CODE_FILE_PATH = 'code.file.path'
105
+ export const CODE_KEYS = [ATTR_CODE_FILE_PATH]
106
+
107
+ // Every governed v2 event name the CLI hooks emit — checked against the
108
+ // registry's events_v2 lists.
109
+ export const CLI_EVENT_NAMES = [WI_CREATED, WI_UPDATED, VCS_OPENED]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mainwave/cli",
3
- "version": "0.3.0",
3
+ "version": "0.4.0-rc.1",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -36,19 +36,22 @@
36
36
  "test": "vitest",
37
37
  "test:run": "vitest run",
38
38
  "test:hooks": "node --test tests/hooks/*.test.mjs",
39
- "prepare": "lefthook install"
39
+ "prepare": "lefthook install",
40
+ "api:generate": "openapi-ts"
40
41
  },
41
42
  "dependencies": {
42
43
  "@inquirer/prompts": "7.10.0",
43
44
  "picocolors": "1.1.1"
44
45
  },
45
46
  "devDependencies": {
47
+ "@hey-api/openapi-ts": "^0.99.0",
46
48
  "@types/node": "24.8.0",
47
49
  "lefthook": "2.1.5",
48
50
  "oxlint": "1.71.0",
49
51
  "prettier": "3.8.3",
50
52
  "typescript": "6.0.2",
51
- "vitest": "4.1.4"
53
+ "vitest": "4.1.4",
54
+ "yaml": "2.9.0"
52
55
  },
53
56
  "keywords": [
54
57
  "mainwave",