@skitterbyte/skitterspec-linear 18.0.1 → 18.1.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 (50) hide show
  1. package/MIGRATION.md +81 -0
  2. package/assets/core/env.config.md +36 -9
  3. package/assets/hooks/main-guard.cjs +1 -1
  4. package/assets/hooks/review-gate.cjs +1 -1
  5. package/assets/rules/spec-planning.md +4 -2
  6. package/assets/skills/spec-complete/SKILL.md +67 -25
  7. package/assets/skills/spec-hotfix/SKILL.md +21 -11
  8. package/assets/skills/spec-sync/SKILL.md +10 -1
  9. package/package.json +1 -1
  10. package/src/cli.js +289 -34
  11. package/src/env/config.js +14 -2
  12. package/src/env/hotfix.js +288 -16
  13. package/src/env/hotfixland.js +302 -0
  14. package/src/env/resolve.js +22 -8
  15. package/src/init.js +36 -4
  16. package/src/vendor/linear/api.js +43 -56
  17. package/src/vendor/linear/cli-sanitise.js +2 -2
  18. package/src/vendor/linear/cli-sync.js +87 -390
  19. package/src/vendor/linear/config.js +46 -171
  20. package/src/vendor/linear/credentials.js +40 -370
  21. package/src/vendor/linear/dialect.js +177 -0
  22. package/src/vendor/linear/doctor.js +7 -15
  23. package/src/vendor/linear/identity.js +20 -70
  24. package/src/vendor/linear/released.js +4 -222
  25. package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
  26. package/src/vendor/provider-kit/index.js +41 -0
  27. package/src/vendor/provider-kit/src/adapter.js +23 -0
  28. package/src/vendor/provider-kit/src/apply.js +197 -0
  29. package/src/vendor/provider-kit/src/args.js +68 -0
  30. package/src/vendor/provider-kit/src/config.js +198 -0
  31. package/src/vendor/provider-kit/src/credentials.js +404 -0
  32. package/src/vendor/provider-kit/src/doctor.js +35 -0
  33. package/src/vendor/provider-kit/src/http.js +44 -0
  34. package/src/vendor/provider-kit/src/identity.js +93 -0
  35. package/src/vendor/provider-kit/src/md-compare.js +39 -0
  36. package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
  37. package/src/vendor/provider-kit/src/prompt.js +50 -0
  38. package/src/vendor/provider-kit/src/released.js +226 -0
  39. package/src/vendor/provider-kit/src/specs.js +166 -0
  40. package/src/vendor/provider-kit/src/transport.js +22 -0
  41. package/src/vendor/sync-core/index.js +22 -5
  42. package/src/vendor/sync-core/src/compare.js +14 -12
  43. package/src/vendor/sync-core/src/dialect.js +51 -0
  44. package/src/vendor/sync-core/src/fields.js +36 -0
  45. package/src/vendor/sync-core/src/legacy.js +19 -9
  46. package/src/vendor/sync-core/src/normalize.js +30 -158
  47. package/src/vendor/sync-core/src/push.js +1 -1
  48. package/src/vendor/sync-core/src/retarget.js +21 -17
  49. package/src/vendor/sync-core/src/verify.js +24 -45
  50. package/src/vendor/sync-core/src/write.js +7 -5
@@ -1,393 +1,63 @@
1
1
  'use strict'
2
2
 
3
3
  /**
4
- * The user-level credentials store — where a Linear API key lives when it is
5
- * not in the environment.
4
+ * The Linear binding of the shared credentials store
5
+ * (`@skitterbyte/skitterspec-provider-kit`, `src/credentials.js`) — one file per
6
+ * machine at `$XDG_CONFIG_HOME/skitterspec/credentials.json`, keyed by Linear
7
+ * team id so one file serves every checkout.
6
8
  *
7
- * The repo's `specs/.core/linear.config.json` is COMMITTED and deliberately
8
- * holds only the NAME of an env var, never a key. That is what makes it safe to
9
- * share, so a key can never go there. This store is the alternative: one file
10
- * per machine, outside every repo, at
11
- * `$XDG_CONFIG_HOME/skitterspec/credentials.json` (else `~/.config/…`), keyed by
12
- * Linear team id so one file serves every checkout.
9
+ * The store machinery — schemas, permissions guards, keyCommand resolution —
10
+ * lives in the kit; what stays here is only what is Linear's: the provider
11
+ * name, the fact that v1 stores are this provider's (it predates the
12
+ * namespace), the `lin_api_` key shape, and the wording of the refusals that
13
+ * mention it.
13
14
  *
14
- * Reads never throw. `resolveApiKey` already treats "no key" as a NORMAL state
15
- * meaning "fall back to MCP" rather than an error, so every failure here returns
16
- * a structured reason the caller can report or ignore — a missing store is not a
17
- * problem, it is the default.
18
- *
19
- * Nothing in this module ever returns a key inside an error, and callers must
20
- * keep it out of logs, plans, snapshots and stamped frontmatter.
21
- */
22
-
23
- const { spawnSync } = require('node:child_process')
24
- const fs = require('node:fs')
25
- const os = require('node:os')
26
- const path = require('node:path')
27
-
28
- const DIR_NAME = 'skitterspec'
29
- const FILE_NAME = 'credentials.json'
30
-
31
- // Modes wider than owner-only. Checked ssh-style: a store other users can read
32
- // is refused rather than read, because silently using it would hide the leak,
33
- // and silently chmod'ing someone's file is not ours to do.
34
- const GROUP_OR_WORLD = 0o077
35
-
36
- /**
37
- * Absolute path of the store. Honours `$XDG_CONFIG_HOME`, else `~/.config`.
38
- * `env` and `homedir` are injected so tests never touch a real home directory.
39
- */
40
- function storePath(env = process.env, homedir = os.homedir) {
41
- const xdg = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.trim()
42
- const base = xdg || path.join(homedir(), '.config')
43
- return path.join(base, DIR_NAME, FILE_NAME)
44
- }
45
-
46
- /**
47
- * Read the store.
48
- *
49
- * @returns {object} `{ ok: true, store, path }` — parsed and owner-only;
50
- * `{ ok: false, reason, code, path }` otherwise. `code` is one of:
51
- * `absent` (no file — the normal default, not a problem), `permissions`
52
- * (group/world readable), `unreadable`, `malformed`.
15
+ * The API is unchanged: reads never throw, "no key" is a normal state, and
16
+ * nothing here ever returns a key inside an error.
53
17
  */
54
- function readStore(file, { stat = fs.statSync, read = fs.readFileSync } = {}) {
55
- let info
56
- try {
57
- info = stat(file)
58
- } catch (err) {
59
- if (err.code === 'ENOENT') {
60
- return { ok: false, code: 'absent', path: file, reason: `no credentials store at ${file}` }
61
- }
62
- return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
63
- }
64
-
65
- if (info.mode & GROUP_OR_WORLD) {
66
- const mode = (info.mode & 0o777).toString(8)
67
- return {
68
- ok: false,
69
- code: 'permissions',
70
- path: file,
71
- reason:
72
- `credentials store ${file} is mode ${mode} — readable by other users.\n` +
73
- ` Run: chmod 600 ${file}`,
74
- }
75
- }
76
18
 
77
- let raw
78
- try {
79
- raw = read(file, 'utf-8')
80
- } catch (err) {
81
- return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
82
- }
83
-
84
- let store
85
- try {
86
- store = JSON.parse(raw)
87
- } catch (err) {
88
- return { ok: false, code: 'malformed', path: file, reason: `invalid JSON in ${file}: ${err.message}` }
89
- }
90
- if (!store || typeof store !== 'object' || Array.isArray(store)) {
91
- return { ok: false, code: 'malformed', path: file, reason: `invalid credentials store in ${file}` }
92
- }
93
- return { ok: true, store, path: file }
94
- }
19
+ const kit = require('../provider-kit/src/credentials.js')
95
20
 
96
- /**
97
- * The key recorded for one team, or null. Never throws, and never reports the
98
- * value it did or didn't find.
99
- */
100
- function keyForTeam(store, teamId) {
101
- if (!teamId) return null
102
- const teams = store && store.teams
103
- const entry = teams && typeof teams === 'object' ? teams[teamId] : null
104
- if (!entry || typeof entry !== 'object') return null
105
- const key = entry.key
106
- return typeof key === 'string' && key.trim() ? key.trim() : null
107
- }
108
-
109
- /**
110
- * The Linear IDENTITY recorded for one team, or null.
111
- *
112
- * Identity lives here rather than in the repo's `linear.config.json` for the
113
- * same reason the key does: that file is COMMITTED, so a user id written there
114
- * would follow the repo to every teammate who clones it and assign their specs
115
- * to whoever set it up. Who you are is a fact about this machine and this
116
- * workspace, which is exactly what this store is keyed for.
117
- *
118
- * Unlike a key, an identity is NOT a secret — it is a name and a public user id,
119
- * both of which appear on every issue in Linear. So it may be printed, passed as
120
- * an argument, and returned in an error.
121
- */
122
- function userForTeam(store, teamId) {
123
- if (!teamId) return null
124
- const teams = store && store.teams
125
- const entry = teams && typeof teams === 'object' ? teams[teamId] : null
126
- if (!entry || typeof entry !== 'object') return null
127
- const user = entry.user
128
- if (!user || typeof user !== 'object') return null
129
- // The id is what the assignment is actually made with, so an entry without one
130
- // is not a partial identity — it is no identity at all.
131
- const id = typeof user.id === 'string' && user.id.trim() ? user.id.trim() : null
132
- if (!id) return null
133
- const name = typeof user.name === 'string' && user.name.trim() ? user.name.trim() : null
134
- return { id, name }
135
- }
136
-
137
- // Last 4 characters, for reporting that a key exists without revealing it.
138
- function fingerprint(key) {
139
- if (typeof key !== 'string' || !key) return null
140
- return `…${key.slice(-4)}`
141
- }
142
-
143
-
144
- /**
145
- * Record a key for one team, creating the store at `0600` and its directory at
146
- * `0700`. Other teams' entries are preserved.
147
- *
148
- * Refuses rather than writing when the existing store is unreadable or
149
- * over-permissive — the same guard as reading, because silently rewriting a
150
- * world-readable file would leave the leak in place.
151
- *
152
- * Returns `{ ok: true, path, created }` or `{ ok: false, reason }`. The key is
153
- * never echoed back in either.
154
- */
155
- function writeKey(file, teamId, key, deps = {}) {
156
- const mkdir = deps.mkdir || fs.mkdirSync
157
- const write = deps.write || fs.writeFileSync
158
- const chmod = deps.chmod || fs.chmodSync
159
- const exists = deps.exists || fs.existsSync
160
-
161
- if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
162
- if (typeof key !== 'string' || !key.trim()) return { ok: false, reason: 'empty key — nothing stored' }
163
-
164
- const created = !exists(file)
165
- let store = { version: 1, teams: {} }
166
- if (!created) {
167
- const current = readStore(file, deps)
168
- if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
169
- store = current.store
170
- if (!store.teams || typeof store.teams !== 'object') store.teams = {}
171
- if (!store.version) store.version = 1
172
- }
173
-
174
- store.teams[teamId] = { ...(store.teams[teamId] || {}), key: key.trim() }
175
-
176
- mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
177
- write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
178
- // `mode` on writeFileSync only applies when the file is CREATED, so an
179
- // existing file keeps its mode — narrow it explicitly.
180
- chmod(file, 0o600)
181
- return { ok: true, path: file, created }
182
- }
183
-
184
- /**
185
- * Record the Linear identity for one team, preserving that team's key (or
186
- * `keyCommand`) and every other team's entry.
187
- *
188
- * Same store, same 0600 / 0700 guards, same refusal on an over-permissive file
189
- * as `writeKey` — the file holds a key whether or not this particular write
190
- * carries one, so relaxing the guard here would relax it for the key too.
191
- *
192
- * Returns `{ ok: true, path, created }` or `{ ok: false, reason }`.
193
- */
194
- function writeUser(file, teamId, user, deps = {}) {
195
- const mkdir = deps.mkdir || fs.mkdirSync
196
- const write = deps.write || fs.writeFileSync
197
- const chmod = deps.chmod || fs.chmodSync
198
- const exists = deps.exists || fs.existsSync
199
-
200
- if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
201
- const id = user && typeof user.id === 'string' ? user.id.trim() : ''
202
- if (!id) return { ok: false, reason: 'no user id — nothing stored' }
203
- const name = user && typeof user.name === 'string' ? user.name.trim() : ''
204
-
205
- const created = !exists(file)
206
- let store = { version: 1, teams: {} }
207
- if (!created) {
208
- const current = readStore(file, deps)
209
- if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
210
- store = current.store
211
- if (!store.teams || typeof store.teams !== 'object') store.teams = {}
212
- if (!store.version) store.version = 1
213
- }
214
-
215
- // Spread the existing entry, exactly as `writeKey` does: recording an identity
216
- // must never cost the user the key sitting beside it.
217
- store.teams[teamId] = { ...(store.teams[teamId] || {}), user: name ? { id, name } : { id } }
218
-
219
- mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
220
- write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
221
- chmod(file, 0o600)
222
- return { ok: true, path: file, created }
223
- }
224
-
225
- /**
226
- * Forget the identity recorded for one team, leaving that team's KEY in place.
227
- *
228
- * Deliberately not `removeKey`'s shape. That one drops the whole team entry,
229
- * which is right when the key is what you are revoking; here it would sign the
230
- * user out of Linear entirely because they corrected their own name. A store or
231
- * entry that isn't there is a clean no-op, not an error.
232
- */
233
- function removeUser(file, teamId, deps = {}) {
234
- const write = deps.write || fs.writeFileSync
235
- const current = readStore(file, deps)
236
- if (!current.ok) {
237
- if (current.code === 'absent') return { ok: true, path: file, removed: false }
238
- return { ok: false, reason: current.reason, code: current.code }
239
- }
240
- const entry = current.store.teams && current.store.teams[teamId]
241
- if (!entry || !entry.user) return { ok: true, path: file, removed: false }
242
- delete entry.user
243
- write(file, JSON.stringify(current.store, null, 2) + '\n', { mode: 0o600 })
244
- return { ok: true, path: file, removed: true }
245
- }
246
-
247
- /**
248
- * Remove one team's entry, leaving every other team intact. A store or entry
249
- * that isn't there is a clean no-op, not an error.
250
- */
251
- function removeKey(file, teamId, deps = {}) {
252
- const write = deps.write || fs.writeFileSync
253
- const current = readStore(file, deps)
254
- if (!current.ok) {
255
- if (current.code === 'absent') return { ok: true, path: file, removed: false }
256
- return { ok: false, reason: current.reason, code: current.code }
257
- }
258
- const teams = current.store.teams
259
- if (!teams || !teams[teamId]) return { ok: true, path: file, removed: false }
260
- delete teams[teamId]
261
- write(file, JSON.stringify(current.store, null, 2) + '\n', { mode: 0o600 })
262
- return { ok: true, path: file, removed: true }
263
- }
264
-
265
- /**
266
- * Resolve one team's key from the store: a stored `key` first, else running its
267
- * `keyCommand` and taking stdout.
268
- *
269
- * `keyCommand` is honoured ONLY from this user-level store — never from the
270
- * repo's committed `linear.config.json`. That file travels with the repo, so a
271
- * command named there would let a cloned repo run arbitrary code on the machine
272
- * of anyone who ran `spec-sync`. The repo config keeps naming only an env var.
273
- *
274
- * A command that fails, times out or prints nothing resolves to no key, which is
275
- * the ordinary "fall back to MCP" state — but its stderr is carried back so a
276
- * broken command is diagnosable rather than mysteriously inert. Its **stdout is
277
- * never** put in an error: that is the key.
278
- *
279
- * @returns {object} `{ key, source }` with source `'store'` | `'command'`, or
280
- * `{ key: null, source: null, reason }`.
281
- */
282
- function resolveTeamKey(store, teamId, deps = {}) {
283
- const direct = keyForTeam(store, teamId)
284
- if (direct) return { key: direct, source: 'store' }
285
-
286
- const entry = store && store.teams && typeof store.teams === 'object' ? store.teams[teamId] : null
287
- const command = entry && typeof entry.keyCommand === 'string' ? entry.keyCommand.trim() : ''
288
- if (!command) return { key: null, source: null }
289
-
290
- const run = deps.run || defaultRunCommand
291
- const result = run(command, deps.timeoutMs || COMMAND_TIMEOUT_MS)
292
- if (!result.ok) {
293
- return { key: null, source: null, command, reason: `keyCommand failed: ${result.error}` }
294
- }
295
- const key = (result.stdout || '').trim()
296
- if (!key) {
297
- return { key: null, source: null, command, reason: 'keyCommand produced no output' }
298
- }
299
- return { key, source: 'command', command }
300
- }
301
-
302
- // 60s: a password manager may prompt for biometric or a master password, and a
303
- // hang here would look like the CLI itself wedging.
304
- const COMMAND_TIMEOUT_MS = 60_000
21
+ // v1 stores were only ever written by this provider — the store predates the
22
+ // namespace — so this binding owns them and keeps writing them in place. The
23
+ // first write by any OTHER provider migrates the file to v2.
24
+ const store = kit.makeCredentialsStore({ provider: 'linear', legacyV1Owner: 'linear' })
305
25
 
306
26
  // Linear personal API keys are `lin_api_` + a long token.
307
27
  const LITERAL_KEY_RE = /lin_api_[A-Za-z0-9]{8,}/
308
28
 
309
- function defaultRunCommand(command, timeout) {
310
- const r = spawnSync('sh', ['-c', command], { encoding: 'utf-8', timeout })
311
- if (r.error) return { ok: false, error: r.error.message }
312
- if (r.status !== 0) {
313
- // stderr only — stdout is the secret, and must not reach an error message.
314
- const detail = (r.stderr || '').trim().split('\n')[0] || `exit ${r.status}`
315
- return { ok: false, error: detail }
316
- }
317
- return { ok: true, stdout: r.stdout }
318
- }
319
-
320
- /**
321
- * Record a command for one team instead of a key. Unlike a key, a command is not
322
- * a secret, so this one IS safe to pass as an argument.
323
- */
324
- function writeKeyCommand(file, teamId, command, deps = {}) {
325
- const mkdir = deps.mkdir || fs.mkdirSync
326
- const write = deps.write || fs.writeFileSync
327
- const chmod = deps.chmod || fs.chmodSync
328
- const exists = deps.exists || fs.existsSync
329
-
330
- if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
331
- if (typeof command !== 'string' || !command.trim()) {
332
- return { ok: false, reason: 'empty command — nothing stored' }
333
- }
334
- // Refusing `--key` makes `--command "echo lin_api_…"` the obvious workaround,
335
- // and it is worse: a command is NOT treated as a secret — `status` prints it
336
- // back, and it sits in the store in clear. Catch the shortcut at the door.
337
- if (LITERAL_KEY_RE.test(command)) {
338
- return {
339
- ok: false,
340
- reason:
341
- 'that command has a Linear key written into it.\n' +
342
- ' A command is displayed by `credentials status` and is not treated as a\n' +
343
- ' secret — embedding a key there exposes it. To store a key, run\n' +
344
- ' `credentials set` with no arguments and paste at the hidden prompt.',
345
- }
346
- }
347
-
348
- const created = !exists(file)
349
- let store = { version: 1, teams: {} }
350
- if (!created) {
351
- const current = readStore(file, deps)
352
- if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
353
- store = current.store
354
- if (!store.teams || typeof store.teams !== 'object') store.teams = {}
355
- if (!store.version) store.version = 1
356
- }
357
-
358
- // A command REPLACES a stored key for that team — keeping both would mean the
359
- // key silently wins and the command never runs.
360
- store.teams[teamId] = { keyCommand: command.trim() }
361
-
362
- mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
363
- write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
364
- chmod(file, 0o600)
365
- return { ok: true, path: file, created }
366
- }
367
-
368
- /** The store's permission bits as an octal string, or null when absent. */
369
- function storeMode(file, deps = {}) {
370
- const stat = deps.stat || fs.statSync
371
- try {
372
- return (stat(file).mode & 0o777).toString(8)
373
- } catch {
374
- return null
375
- }
376
- }
29
+ const LITERAL_KEY_ADVICE =
30
+ 'that command has a Linear key written into it.\n' +
31
+ ' A command is displayed by `credentials status` and is not treated as a\n' +
32
+ ' secret — embedding a key there exposes it. To store a key, run\n' +
33
+ ' `credentials set` with no arguments and paste at the hidden prompt.'
34
+
35
+ const keyForTeam = (s, teamId) => store.keyFor(s, teamId)
36
+ const userForTeam = (s, teamId) => store.userFor(s, teamId)
37
+ const resolveTeamKey = (s, teamId, deps) => store.resolveKey(s, teamId, deps)
38
+ const writeKey = (file, teamId, key, deps) => store.writeKey(file, teamId, key, deps)
39
+ const writeUser = (file, teamId, user, deps) => store.writeUser(file, teamId, user, deps)
40
+ const removeKey = (file, teamId, deps) => store.removeKey(file, teamId, deps)
41
+ const removeUser = (file, teamId, deps) => store.removeUser(file, teamId, deps)
42
+ const writeKeyCommand = (file, teamId, command, deps) =>
43
+ store.writeKeyCommand(file, teamId, command, deps, {
44
+ literalKeyRe: LITERAL_KEY_RE,
45
+ literalKeyAdvice: LITERAL_KEY_ADVICE,
46
+ })
377
47
 
378
48
  module.exports = {
379
- storePath,
380
- readStore,
49
+ storePath: kit.storePath,
50
+ readStore: kit.readStore,
381
51
  keyForTeam,
382
52
  userForTeam,
383
- fingerprint,
53
+ fingerprint: kit.fingerprint,
384
54
  writeKey,
385
55
  writeUser,
386
56
  writeKeyCommand,
387
57
  resolveTeamKey,
388
58
  removeKey,
389
59
  removeUser,
390
- storeMode,
391
- DIR_NAME,
392
- FILE_NAME,
60
+ storeMode: kit.storeMode,
61
+ DIR_NAME: kit.DIR_NAME,
62
+ FILE_NAME: kit.FILE_NAME,
393
63
  }
@@ -0,0 +1,177 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * The Linear markdown DIALECT — every transform that exists because of how
5
+ * Linear's editor reserialises or corrupts markdown on save. Extracted from the
6
+ * neutral engine (sync-core) so the engine carries no tracker's quirks: the
7
+ * loader attaches this object to `config.dialect`, and the engine calls its
8
+ * hooks wherever it used to call these functions directly.
9
+ *
10
+ * Three hooks (see sync-core `src/dialect.js` for the contract):
11
+ * - `canonicalize` — Linear rewrites bullets, trims trailing space and
12
+ * mangles emphasis straddling a line break.
13
+ * - `flattenTables` — Linear truncates data cells of tables nested in
14
+ * list items (measured on SKI-28).
15
+ * - `canonicalForCompare`— Linear renumbers ordered lists, unifies bullet
16
+ * markers, case-folds checkboxes and collapses table
17
+ * separator rows on save.
18
+ *
19
+ * Everything here is pure string → string.
20
+ */
21
+
22
+ const { flattenNestedTables, splitCells } = require('../provider-kit/src/md-tables.js')
23
+
24
+ // Linear mangles inline emphasis whose markers straddle a hard line break: it
25
+ // terminates the run at end-of-line and restarts it at the next, so `**a\nb**`
26
+ // comes back as `**a****\n****b**`, `*a\nb*` as `*a**\n**b*`, and a link splits
27
+ // into two. Canonicalise BOTH representations — the clean straddle we author and
28
+ // the mangled form Linear returns — to the same single-line span, so an
29
+ // already-mangled remote stops reading as a spurious `remote-only` diff and the
30
+ // payload we push carries no straddle for Linear to mangle again. Idempotent: a
31
+ // joined span has no interior newline, so nothing re-fires. Repo files are never
32
+ // rewritten — this only shapes the normalized projection the compare/push see.
33
+ function joinEmphasisAcrossBreaks(text) {
34
+ let s = String(text)
35
+ // (1) Repair Linear's mangle artifacts first — an emphasis run terminated at
36
+ // end-of-line and restarted at the next. These are very specific asterisk runs
37
+ // flanking a break, so a targeted regex is safe:
38
+ // bold: `**X****\n****Y**` → the `****\n****` empty-bold artifact → a space.
39
+ s = s.replace(/\*{4}[ \t]*\n[ \t]*\*{4}/g, ' ')
40
+ // italic: `*X**\n**Y*` — the `**\n**` artifact sits INSIDE a single-`*` span;
41
+ // gate on the enclosing single `*` so a genuine pair of adjacent bolds at a
42
+ // line boundary (`a**\n**b`) is left alone.
43
+ s = s.replace(/(^|[^*\n])\*([^*\n]+)\*\*[ \t]*\n[ \t]*\*\*([^*\n]+)\*(?![*])/g, '$1*$2 $3*')
44
+ // link split across a break onto the same url → one link.
45
+ s = s.replace(/\[([^\]]+)\]\(([^)]+)\)[ \t]*\n[ \t]*\[([^\]]+)\]\(\2\)/g, '[$1 $3]($2)')
46
+ // (2) Join the clean straddle we author — a newline that falls while an
47
+ // emphasis/link span is OPEN. A scanner (not a regex) so an opening `**` is
48
+ // never mis-paired with an unrelated closing `**` on the next line, and markers
49
+ // inside a `code span` are ignored (Linear only rejoins those, harmlessly).
50
+ return joinOpenSpans(s)
51
+ }
52
+
53
+ // Walk the text tracking whether we're inside a `**bold**`, `*italic*`, `[link
54
+ // text]`/`(url)`, or `` `code` `` span. A newline encountered while a
55
+ // non-code span is open joins the two lines with a single space (dropping the
56
+ // next line's indentation); every other newline is preserved.
57
+ function joinOpenSpans(text) {
58
+ const out = []
59
+ let bold = false
60
+ let italic = false
61
+ let code = false
62
+ let link = 0 // 0 none · 1 in link text · 2 in url
63
+ for (let i = 0; i < text.length; i++) {
64
+ const c = text[i]
65
+ if (c === '\n') {
66
+ if (!code && (bold || italic || link)) {
67
+ // Skip the continuation's indentation AND any blockquote marker (`>`) —
68
+ // a span wrapped across two `> …` lines is one quoted run, so the join
69
+ // must drop the continuation `>` rather than swallow it into the text.
70
+ // Then join: a word wrapped at a hyphen (`state-entry-with-`⏎`assignment`)
71
+ // is one compound — join TIGHT (no space); otherwise a single space.
72
+ let j = i + 1
73
+ while (j < text.length && (text[j] === ' ' || text[j] === '\t' || text[j] === '>')) j++
74
+ const softHyphen = text[i - 1] === '-' && /\w/.test(text[i - 2] || '') && /\w/.test(text[j] || '')
75
+ if (!softHyphen) out.push(' ')
76
+ i = j - 1
77
+ } else {
78
+ out.push('\n')
79
+ }
80
+ continue
81
+ }
82
+ if (c === '`') {
83
+ code = !code
84
+ out.push(c)
85
+ continue
86
+ }
87
+ if (code) {
88
+ out.push(c)
89
+ continue
90
+ }
91
+ if (c === '*' && text[i + 1] === '*') {
92
+ bold = !bold
93
+ out.push('**')
94
+ i++
95
+ continue
96
+ }
97
+ if (c === '*') {
98
+ // Basic flanking so a stray `*` (e.g. `2 * 3`) doesn't open a phantom span:
99
+ // an opener needs a non-space to its right, a closer a non-space to its left.
100
+ const ok = italic ? !/\s/.test(text[i - 1] || '') : !/\s/.test(text[i + 1] || '')
101
+ if (ok) italic = !italic
102
+ out.push(c)
103
+ continue
104
+ }
105
+ if (c === '[' && link === 0) {
106
+ link = 1
107
+ out.push(c)
108
+ continue
109
+ }
110
+ if (c === ']' && link === 1) {
111
+ if (text[i + 1] === '(') {
112
+ link = 2
113
+ out.push('](')
114
+ i++
115
+ } else {
116
+ link = 0
117
+ out.push(c)
118
+ }
119
+ continue
120
+ }
121
+ if (c === ')' && link === 2) {
122
+ link = 0
123
+ out.push(c)
124
+ continue
125
+ }
126
+ out.push(c)
127
+ }
128
+ return out.join('')
129
+ }
130
+
131
+ // Canonicalise markdown so semantically-equal content hashes equal across the
132
+ // boundary. Linear reserializes markdown on save (authored `-` bullets come back
133
+ // as `*`, trailing whitespace trimmed, blank runs collapsed, emphasis spanning a
134
+ // line break mangled), so without this a clean push→pull would report
135
+ // `description` as perpetually changed. Applied to the description on BOTH sides.
136
+ // Conservative: only unifies list markers, whitespace, and emphasis-across-a-break
137
+ // — the transforms actually observed from Linear.
138
+ function canonicalizeMarkdown(text) {
139
+ if (text == null) return text
140
+ const marked = String(text)
141
+ .replace(/\r\n/g, '\n')
142
+ .split('\n')
143
+ // Unordered-list marker at line start (`*`/`+`/`-`) → `-`. Requires a space
144
+ // after the marker so bold/emphasis (`**Goal:**`) is untouched. Done BEFORE
145
+ // the emphasis join so a `*` list bullet can't spoof an italic delimiter.
146
+ .map((line) => line.replace(/^(\s*)[*+-]( +)/, '$1-$2').replace(/[ \t]+$/, ''))
147
+ .join('\n')
148
+ return joinEmphasisAcrossBreaks(marked)
149
+ // A word wrapped at a hyphen within a paragraph (`state-entry-with-`⏎
150
+ // `assignment`) rejoins TIGHT — otherwise Linear (CommonMark) renders the
151
+ // soft line break as a space and corrupts the compound. Single newline only,
152
+ // so paragraph breaks are preserved.
153
+ .replace(/(\w-)[ \t]*\n[ \t]*(?=\w)/g, '$1')
154
+ .replace(/\n{3,}/g, '\n\n')
155
+ .trim()
156
+ }
157
+
158
+ // Linear reserialises markdown on save; the reduction that makes those
159
+ // transforms invisible is shared with the ADF dialect and lives in the kit.
160
+ const { markdownCanonicalForCompare: canonicalForCompare } = require('../provider-kit/src/md-compare.js')
161
+
162
+
163
+ // The dialect object the config loader attaches (`config.dialect`).
164
+ const dialect = Object.freeze({
165
+ canonicalize: canonicalizeMarkdown,
166
+ flattenTables: flattenNestedTables,
167
+ canonicalForCompare,
168
+ })
169
+
170
+ module.exports = {
171
+ dialect,
172
+ canonicalizeMarkdown,
173
+ joinEmphasisAcrossBreaks,
174
+ flattenNestedTables,
175
+ splitCells,
176
+ canonicalForCompare,
177
+ }
@@ -29,18 +29,12 @@
29
29
  * by construction rather than by convention.
30
30
  */
31
31
 
32
- // `warn` sits between `ok` and `broken`: worth a human's attention, but not a
33
- // failure. A ladder whose last rung never closes an issue is a real problem for
34
- // most projects and a deliberate choice for some, and only the project knows
35
- // which — so it is said, and the exit code is left alone.
36
- const STATES = ['ok', 'missing', 'broken', 'skipped', 'warn']
37
-
38
- // A row is a check. `fix` is the exact command to run, or null when there is
39
- // nothing to fix.
40
- const row = (id, label, state, detail, fix = null) => {
41
- if (!STATES.includes(state)) throw new Error(`doctor: unknown check state "${state}" for ${id}`)
42
- return { id, label, state, detail, fix }
43
- }
32
+ // The states, the row shape and the combining rule are the kit's
33
+ // (`provider-kit/src/doctor.js`); the checks below are Linear's. A ladder whose
34
+ // last rung never closes an issue is a real problem for most projects and a
35
+ // deliberate choice for some, and only the project knows which — which is what
36
+ // the kit's `warn` state exists for.
37
+ const { DOCTOR_STATES: STATES, doctorRow: row, combineDoctorChecks } = require('../provider-kit/src/doctor.js')
44
38
 
45
39
  /**
46
40
  * @param {object} state gathered by the caller:
@@ -65,9 +59,7 @@ function runChecks(state = {}) {
65
59
  ladderCheck(state.ladder, state.tracker),
66
60
  mcpCheck(state.mcp, state.tracker, state.project, state.remote),
67
61
  ]
68
- // `missing` is a declined opt-in, so it must not fail the run. Only a
69
- // configured-but-wrong layer does.
70
- return { ok: !checks.some((c) => c.state === 'broken'), checks }
62
+ return combineDoctorChecks(checks)
71
63
  }
72
64
 
73
65
  /**