@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
@@ -16,7 +16,8 @@
16
16
 
17
17
  const fs = require('node:fs')
18
18
  const path = require('node:path')
19
- const { flattenNestedTables } = require('./tables.js')
19
+ const { dialectOf } = require('./dialect.js')
20
+ const { fieldsOf } = require('./fields.js')
20
21
  const { fenceMask, findTaskBlocks, collapse, collapseHyphenAware } = require('./task-block.js')
21
22
 
22
23
  // --- markdown / frontmatter parsing -----------------------------------------
@@ -88,140 +89,6 @@ function parseSections(body) {
88
89
  return { title, sections }
89
90
  }
90
91
 
91
- // Linear mangles inline emphasis whose markers straddle a hard line break: it
92
- // terminates the run at end-of-line and restarts it at the next, so `**a\nb**`
93
- // comes back as `**a****\n****b**`, `*a\nb*` as `*a**\n**b*`, and a link splits
94
- // into two. Canonicalise BOTH representations — the clean straddle we author and
95
- // the mangled form Linear returns — to the same single-line span, so an
96
- // already-mangled remote stops reading as a spurious `remote-only` diff and the
97
- // payload we push carries no straddle for Linear to mangle again. Idempotent: a
98
- // joined span has no interior newline, so nothing re-fires. Repo files are never
99
- // rewritten — this only shapes the normalized projection the compare/push see.
100
- function joinEmphasisAcrossBreaks(text) {
101
- let s = String(text)
102
- // (1) Repair Linear's mangle artifacts first — an emphasis run terminated at
103
- // end-of-line and restarted at the next. These are very specific asterisk runs
104
- // flanking a break, so a targeted regex is safe:
105
- // bold: `**X****\n****Y**` → the `****\n****` empty-bold artifact → a space.
106
- s = s.replace(/\*{4}[ \t]*\n[ \t]*\*{4}/g, ' ')
107
- // italic: `*X**\n**Y*` — the `**\n**` artifact sits INSIDE a single-`*` span;
108
- // gate on the enclosing single `*` so a genuine pair of adjacent bolds at a
109
- // line boundary (`a**\n**b`) is left alone.
110
- s = s.replace(/(^|[^*\n])\*([^*\n]+)\*\*[ \t]*\n[ \t]*\*\*([^*\n]+)\*(?![*])/g, '$1*$2 $3*')
111
- // link split across a break onto the same url → one link.
112
- s = s.replace(/\[([^\]]+)\]\(([^)]+)\)[ \t]*\n[ \t]*\[([^\]]+)\]\(\2\)/g, '[$1 $3]($2)')
113
- // (2) Join the clean straddle we author — a newline that falls while an
114
- // emphasis/link span is OPEN. A scanner (not a regex) so an opening `**` is
115
- // never mis-paired with an unrelated closing `**` on the next line, and markers
116
- // inside a `code span` are ignored (Linear only rejoins those, harmlessly).
117
- return joinOpenSpans(s)
118
- }
119
-
120
- // Walk the text tracking whether we're inside a `**bold**`, `*italic*`, `[link
121
- // text]`/`(url)`, or `` `code` `` span. A newline encountered while a
122
- // non-code span is open joins the two lines with a single space (dropping the
123
- // next line's indentation); every other newline is preserved.
124
- function joinOpenSpans(text) {
125
- const out = []
126
- let bold = false
127
- let italic = false
128
- let code = false
129
- let link = 0 // 0 none · 1 in link text · 2 in url
130
- for (let i = 0; i < text.length; i++) {
131
- const c = text[i]
132
- if (c === '\n') {
133
- if (!code && (bold || italic || link)) {
134
- // Skip the continuation's indentation AND any blockquote marker (`>`) —
135
- // a span wrapped across two `> …` lines is one quoted run, so the join
136
- // must drop the continuation `>` rather than swallow it into the text.
137
- // Then join: a word wrapped at a hyphen (`state-entry-with-`⏎`assignment`)
138
- // is one compound — join TIGHT (no space); otherwise a single space.
139
- let j = i + 1
140
- while (j < text.length && (text[j] === ' ' || text[j] === '\t' || text[j] === '>')) j++
141
- const softHyphen = text[i - 1] === '-' && /\w/.test(text[i - 2] || '') && /\w/.test(text[j] || '')
142
- if (!softHyphen) out.push(' ')
143
- i = j - 1
144
- } else {
145
- out.push('\n')
146
- }
147
- continue
148
- }
149
- if (c === '`') {
150
- code = !code
151
- out.push(c)
152
- continue
153
- }
154
- if (code) {
155
- out.push(c)
156
- continue
157
- }
158
- if (c === '*' && text[i + 1] === '*') {
159
- bold = !bold
160
- out.push('**')
161
- i++
162
- continue
163
- }
164
- if (c === '*') {
165
- // Basic flanking so a stray `*` (e.g. `2 * 3`) doesn't open a phantom span:
166
- // an opener needs a non-space to its right, a closer a non-space to its left.
167
- const ok = italic ? !/\s/.test(text[i - 1] || '') : !/\s/.test(text[i + 1] || '')
168
- if (ok) italic = !italic
169
- out.push(c)
170
- continue
171
- }
172
- if (c === '[' && link === 0) {
173
- link = 1
174
- out.push(c)
175
- continue
176
- }
177
- if (c === ']' && link === 1) {
178
- if (text[i + 1] === '(') {
179
- link = 2
180
- out.push('](')
181
- i++
182
- } else {
183
- link = 0
184
- out.push(c)
185
- }
186
- continue
187
- }
188
- if (c === ')' && link === 2) {
189
- link = 0
190
- out.push(c)
191
- continue
192
- }
193
- out.push(c)
194
- }
195
- return out.join('')
196
- }
197
-
198
- // Canonicalise markdown so semantically-equal content hashes equal across the
199
- // boundary. Linear reserializes markdown on save (authored `-` bullets come back
200
- // as `*`, trailing whitespace trimmed, blank runs collapsed, emphasis spanning a
201
- // line break mangled), so without this a clean push→pull would report
202
- // `description` as perpetually changed. Applied to the description on BOTH sides.
203
- // Conservative: only unifies list markers, whitespace, and emphasis-across-a-break
204
- // — the transforms actually observed from Linear.
205
- function canonicalizeMarkdown(text) {
206
- if (text == null) return text
207
- const marked = String(text)
208
- .replace(/\r\n/g, '\n')
209
- .split('\n')
210
- // Unordered-list marker at line start (`*`/`+`/`-`) → `-`. Requires a space
211
- // after the marker so bold/emphasis (`**Goal:**`) is untouched. Done BEFORE
212
- // the emphasis join so a `*` list bullet can't spoof an italic delimiter.
213
- .map((line) => line.replace(/^(\s*)[*+-]( +)/, '$1-$2').replace(/[ \t]+$/, ''))
214
- .join('\n')
215
- return joinEmphasisAcrossBreaks(marked)
216
- // A word wrapped at a hyphen within a paragraph (`state-entry-with-`⏎
217
- // `assignment`) rejoins TIGHT — otherwise Linear (CommonMark) renders the
218
- // soft line break as a space and corrupts the compound. Single newline only,
219
- // so paragraph breaks are preserved.
220
- .replace(/(\w-)[ \t]*\n[ \t]*(?=\w)/g, '$1')
221
- .replace(/\n{3,}/g, '\n\n')
222
- .trim()
223
- }
224
-
225
92
  // Canonical milestone status from the phase-index emoji.
226
93
  const EMOJI_STATUS = { '⬜': 'not-started', '🔄': 'in-progress', '✅': 'done' }
227
94
 
@@ -357,7 +224,7 @@ function renderTaskBlockLine(b) {
357
224
 
358
225
  // Read the phase files (01-*.md, 02-*.md …) in execution order. Each yields its
359
226
  // linked milestone id (from optional frontmatter), title, goal and tasks.
360
- function readPhaseFiles(snapshotDir) {
227
+ function readPhaseFiles(snapshotDir, config) {
361
228
  let entries
362
229
  try {
363
230
  entries = fs.readdirSync(snapshotDir)
@@ -388,7 +255,7 @@ function readPhaseFiles(snapshotDir) {
388
255
  phase: file.replace(/\.md$/, ''),
389
256
  file,
390
257
  // The sub-issue id, stamped back into the phase file on first push.
391
- id: data.linear_issue_id != null ? String(data.linear_issue_id) : null,
258
+ id: data[fieldsOf(config).issueId] != null ? String(data[fieldsOf(config).issueId]) : null,
392
259
  name: phaseTitle(body),
393
260
  goal: goal.trim(),
394
261
  state: phaseStateBucket(body),
@@ -423,7 +290,7 @@ function readPhaseFiles(snapshotDir) {
423
290
  * (today: printed, never fatal).
424
291
  */
425
292
  function lintPhases(snapshotDir, config) {
426
- const phases = readPhaseFiles(snapshotDir)
293
+ const phases = readPhaseFiles(snapshotDir, config)
427
294
  // BLIND SPOT: `readPhaseFiles` only sees `NN-*.md`, so a legacy bare
428
295
  // `<name>.md` spec yields no phases at all. Silence is the right answer —
429
296
  // there is no phase file to carry an emoji — but it is silence from having
@@ -534,7 +401,7 @@ function readSnapshot(snapshotDir, config) {
534
401
  const raw = fs.readFileSync(path.join(snapshotDir, overviewFile), 'utf-8')
535
402
  const { data, body } = parseFrontmatter(raw)
536
403
  const { title, sections } = parseSections(body)
537
- const phases = readPhaseFiles(snapshotDir)
404
+ const phases = readPhaseFiles(snapshotDir, config)
538
405
  return { frontmatter: data, title, sections, phases, body }
539
406
  }
540
407
 
@@ -542,7 +409,7 @@ function readSnapshot(snapshotDir, config) {
542
409
  // removed. Keeps the title line for context. `extraSkip` drops additional
543
410
  // sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
544
411
  // the phase list isn't duplicated in the description — Decision 5).
545
- function buildDescription(title, sections, localOnlySections, extraSkip = []) {
412
+ function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect) {
546
413
  const skip = new Set([...(localOnlySections || []), ...extraSkip])
547
414
  const parts = []
548
415
  if (title) parts.push(`# ${title}`)
@@ -550,7 +417,7 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
550
417
  if (skip.has(heading)) continue
551
418
  parts.push(`## ${heading}\n\n${content}`.trim())
552
419
  }
553
- return flattenNestedTables(canonicalizeMarkdown(parts.join('\n\n'))) || null
420
+ return dialect.flattenTables(dialect.canonicalize(parts.join('\n\n'))) || null
554
421
  }
555
422
 
556
423
  // A phase sub-issue's description: its `**Goal:**` line, plus the phase's task
@@ -561,9 +428,9 @@ function buildDescription(title, sections, localOnlySections, extraSkip = []) {
561
428
  // push. Without it a sub-issue is a title and one sentence, which is too thin to
562
429
  // act on; with it the phase is legible to someone working in the tracker without
563
430
  // tasks becoming individually-synced objects again.
564
- function subIssueBody(phase, tasksMode, localOnlySections) {
565
- if (tasksMode !== 'checklist') return flattenNestedTables(phase.goal)
566
- return flattenNestedTables(projectPhaseBody(phase, localOnlySections))
431
+ function subIssueBody(phase, tasksMode, localOnlySections, dialect) {
432
+ if (tasksMode !== 'checklist') return dialect.flattenTables(phase.goal)
433
+ return dialect.flattenTables(projectPhaseBody(phase, localOnlySections))
567
434
  }
568
435
 
569
436
  /**
@@ -674,10 +541,10 @@ function phaseHeading(phase) {
674
541
  * that drops content, which is exactly what the reporting project had to
675
542
  * hand-roll before this existed.
676
543
  */
677
- function withInlinePhases(description, inlined, tasksMode, localOnlySections) {
544
+ function withInlinePhases(description, inlined, tasksMode, localOnlySections, dialect) {
678
545
  if (!inlined.length) return description
679
546
  const sections = inlined.map((phase) => {
680
- const body = demoteHeadings(subIssueBody(phase, tasksMode, localOnlySections) || '', INLINE_PHASE_LEVEL - 1)
547
+ const body = demoteHeadings(subIssueBody(phase, tasksMode, localOnlySections, dialect) || '', INLINE_PHASE_LEVEL - 1)
681
548
  const heading = '#'.repeat(INLINE_PHASE_LEVEL) + ` ${phaseHeading(phase)}`
682
549
  return body ? `${heading}\n\n${body}` : heading
683
550
  })
@@ -718,9 +585,9 @@ const TERMINAL_BUCKETS = ['complete', 'cancelled']
718
585
  * `issueChanges`, where an assignee that was never pushed is left alone rather
719
586
  * than retracted. That is what stops this wiping a PM's triage.
720
587
  */
721
- function assigneeFor(workflowState, frontmatter) {
588
+ function assigneeFor(workflowState, frontmatter, config) {
722
589
  if (TERMINAL_BUCKETS.includes(String(workflowState))) return null
723
- const id = frontmatter && frontmatter.linear_assignee_id
590
+ const id = frontmatter && frontmatter[fieldsOf(config).assigneeId]
724
591
  return typeof id === 'string' && id.trim() ? id.trim() : null
725
592
  }
726
593
 
@@ -796,6 +663,7 @@ function phaseProjection(phases, workflowState, config) {
796
663
  }
797
664
 
798
665
  function normalizeLocal(snapshotDir, config) {
666
+ const dialect = dialectOf(config)
799
667
  const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
800
668
  const tasksMode = (config.mapping && config.mapping.tasks) || 'checklist'
801
669
  // Status is the spec's lifecycle bucket. The folder is the source of truth; an
@@ -828,10 +696,12 @@ function normalizeLocal(snapshotDir, config) {
828
696
  sections,
829
697
  config.sync.localOnlySections,
830
698
  phasesCarriedBySubIssues ? ['Phases'] : [],
699
+ dialect,
831
700
  ),
832
701
  inlined,
833
702
  tasksMode,
834
703
  config.sync.localOnlySections,
704
+ dialect,
835
705
  ),
836
706
  // Sub-issue projection: one per phase. `ref` is the phase-file basename — the
837
707
  // local handle the push skill stamps a newly-created sub-issue id back into.
@@ -843,7 +713,7 @@ function normalizeLocal(snapshotDir, config) {
843
713
  id: p.id,
844
714
  ref: p.phase,
845
715
  name: p.name,
846
- goal: subIssueBody(p, tasksMode, config.sync.localOnlySections),
716
+ goal: subIssueBody(p, tasksMode, config.sync.localOnlySections, dialect),
847
717
  state: p.state,
848
718
  })),
849
719
  workflowState,
@@ -851,7 +721,7 @@ function normalizeLocal(snapshotDir, config) {
851
721
  // `assignee` in `sync.fieldOwnership`, so the opt-in costs no extra check
852
722
  // here — an un-opted-in repo simply has no such key on its projection, and
853
723
  // every downstream reader treats that as "the field is not in play".
854
- assignee: assigneeFor(workflowState, frontmatter),
724
+ assignee: assigneeFor(workflowState, frontmatter, config),
855
725
  }
856
726
  return toFieldSet(extracted, config)
857
727
  }
@@ -919,9 +789,12 @@ function canonicalRemoteStatus(state) {
919
789
  return s
920
790
  }
921
791
 
922
- // The real Linear issue carries its workflow state in `state` (an object
923
- // `{ name, type }`); accept `status` / a bare string too for robustness.
924
- function remoteStateName(issue) {
792
+ // A tracker issue usually carries its workflow state in `state` (an object
793
+ // `{ name, type }`); accept `status` / a bare string too for robustness. A
794
+ // provider whose remote shape differs supplies `config.remote.stateName`.
795
+ function remoteStateName(issue, config) {
796
+ const hook = config && config.remote && config.remote.stateName
797
+ if (typeof hook === 'function') return hook(issue)
925
798
  const st = issue.state != null ? issue.state : issue.status
926
799
  if (st == null) return null
927
800
  if (typeof st === 'object') return st.name != null ? st.name : st.type != null ? st.type : null
@@ -930,9 +803,9 @@ function remoteStateName(issue) {
930
803
 
931
804
  // The ONE thing one-way sync reads back: the mirror issue's current workflow
932
805
  // state, mapped to the local lifecycle bucket, so `/spec-status` can report a
933
- // drift ("Linear says Done, your spec says In Progress"). Read-only — never writes.
806
+ // drift ("the tracker says Done, your spec says In Progress"). Read-only — never writes.
934
807
  function remoteWorkflowState(issue, config) {
935
- const name = remoteStateName(issue || {})
808
+ const name = remoteStateName(issue || {}, config)
936
809
  return name != null ? bucketForState(name, config) : null
937
810
  }
938
811
 
@@ -940,7 +813,7 @@ function remoteWorkflowState(issue, config) {
940
813
  // Pairs with `remoteWorkflowState`: that says which bucket the issue maps to,
941
814
  // this says whether it got there by being deployed. Read-only.
942
815
  function remoteStage(issue, config) {
943
- return stageForState(remoteStateName(issue || {}), config)
816
+ return stageForState(remoteStateName(issue || {}, config), config)
944
817
  }
945
818
 
946
819
  // A Linear issue title is plain text, so markdown emphasis is noise there — and
@@ -1107,9 +980,8 @@ module.exports = {
1107
980
  titleFromText,
1108
981
  validateStates,
1109
982
  canonicalRemoteStatus,
1110
- canonicalizeMarkdown,
1111
- joinEmphasisAcrossBreaks,
1112
983
  bucketForState,
984
+ LIFECYCLE_BUCKETS,
1113
985
  stageForState,
1114
986
  remoteStage,
1115
987
  remoteWorkflowState,
@@ -79,7 +79,7 @@ function push({ dir, snapshotDir, identifier, config }) {
79
79
  */
80
80
  function recordPush({ dir, snapshotDir, identifier, config }) {
81
81
  const projection = projectionOf(snapshotDir, config)
82
- return writeBase(dir, identifier, config, snapshotOf(projection))
82
+ return writeBase(dir, identifier, config, snapshotOf(projection, config))
83
83
  }
84
84
 
85
85
  module.exports = { push, recordPush, projectionOf }
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * Renaming a Linear team rewrites the key in every issue identifier
7
7
  * (`SKI-7` → `SKS-7`). The repo stamps those identifiers in three places — spec
8
- * frontmatter, the `linear-base` snapshot filenames, and the `subIssues` keys
8
+ * frontmatter, the sync-base snapshot filenames, and the `subIssues` keys
9
9
  * inside those snapshots — and nothing moves them, so afterwards every stamped
10
10
  * spec is stale and `/spec-push` fails with `no issue found for SKI-7`.
11
11
  *
@@ -27,21 +27,22 @@ const fs = require('node:fs')
27
27
  const path = require('node:path')
28
28
  const { execFileSync } = require('node:child_process')
29
29
 
30
- const { parseFrontmatter } = require('./normalize.js')
31
-
32
- // The lifecycle buckets a spec can live in. Kept local rather than imported so
33
- // sync-core stays free of the common package.
34
- const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
30
+ const { parseFrontmatter, LIFECYCLE_BUCKETS: BUCKETS } = require('./normalize.js')
31
+ const { fieldsOf } = require('./fields.js')
35
32
 
36
33
  // An issue identifier: team key, dash, number. Matched CASE-INSENSITIVELY
37
- // because `linear_url` carries the identifier lowercased in its path
34
+ // because the stamped url field carries the identifier lowercased in its path
38
35
  // (`…/issue/reu-188/retire-…`). Matching only uppercase left 29 of 33 real URLs
39
36
  // in a live repo pointing at the old key — the same ones the hand-repair
40
37
  // missed. A rewrite only happens when the key matches `oldKey`, so an unrelated
41
38
  // token like `utf-8` is never in scope.
42
39
  const IDENTIFIER_RE = /\b([A-Za-z][A-Za-z0-9]*)-(\d+)\b/g
43
40
 
44
- const STAMP_FIELDS = ['linear_identifier', 'linear_issue_id']
41
+ // The stamped identifier fields, from the provider's vocabulary.
42
+ const stampFields = (config) => {
43
+ const f = fieldsOf(config)
44
+ return [f.identifier, f.issueId]
45
+ }
45
46
  const SNAPSHOT_SUFFIX = '.base.json'
46
47
 
47
48
  // Every `.md` under each spec folder — overview and phase files alike, plus the
@@ -94,7 +95,7 @@ function movePrefix(text, oldKey, newKey) {
94
95
  /**
95
96
  * The recorded key this repo believes it is stamped with.
96
97
  *
97
- * `config.linear.teamKey` is authoritative when set — but it defaults to `""`
98
+ * `config.provider.teamKey` is authoritative when set — but it defaults to `""`
98
99
  * and is written by `init-config` and never read, which is exactly why a stale
99
100
  * key never failed loudly. So fall back to the prefix actually observed in the
100
101
  * stamps. Disagreeing stamps are reported, never guessed at and never thrown:
@@ -103,7 +104,7 @@ function movePrefix(text, oldKey, newKey) {
103
104
  * @returns {{key: string|null, source: 'config'|'stamps'|null, keys?: string[], reason?: string}}
104
105
  */
105
106
  function deriveRecordedKey(dir, config) {
106
- const configured = (config.linear && config.linear.teamKey) || ''
107
+ const configured = (config.provider && config.provider.teamKey) || ''
107
108
  if (configured) return { key: configured, source: 'config' }
108
109
 
109
110
  const keys = new Set()
@@ -115,7 +116,7 @@ function deriveRecordedKey(dir, config) {
115
116
  continue
116
117
  }
117
118
  const { data } = parseFrontmatter(raw)
118
- for (const field of STAMP_FIELDS) {
119
+ for (const field of stampFields(config)) {
119
120
  if (!data[field]) continue
120
121
  const m = /^([A-Z][A-Z0-9]*)-\d+$/.exec(String(data[field]).trim())
121
122
  if (m) keys.add(m[1])
@@ -138,7 +139,7 @@ function deriveRecordedKey(dir, config) {
138
139
  key: null,
139
140
  source: null,
140
141
  keys: found,
141
- reason: `stamps disagree — found ${found.join(', ')}; set linear.teamKey to the recorded one`,
142
+ reason: `stamps disagree — found ${found.join(', ')}; set the provider config's team key to the recorded one`,
142
143
  }
143
144
  }
144
145
 
@@ -191,7 +192,7 @@ function planRetarget({ dir, oldKey, newKey, config }) {
191
192
  snapshots.push({ file: name, from: name, to: renamed, keys, body })
192
193
  }
193
194
 
194
- const recorded = (config.linear && config.linear.teamKey) || ''
195
+ const recorded = (config.provider && config.provider.teamKey) || ''
195
196
  const configKey = recorded && recorded !== newKey ? { from: recorded, to: newKey } : null
196
197
 
197
198
  return { stamps, snapshots, configKey }
@@ -251,12 +252,15 @@ function applyRetarget(plan, { dir, config }) {
251
252
  }
252
253
  }
253
254
 
254
- if (plan.configKey) {
255
+ if (plan.configKey && config.provider && config.provider.configFile) {
255
256
  // Textual, not parse-and-restringify: the config is hand-edited and carries
256
- // ordering (and possibly comments) a JSON round-trip would discard.
257
- const file = path.join(dir, 'specs', '.core', 'linear.config.json')
257
+ // ordering (and possibly comments) a JSON round-trip would discard. The
258
+ // file and the JSON key both come from the provider (`config.provider`).
259
+ const file = path.join(dir, config.provider.configFile)
260
+ const keyField = config.provider.teamKeyJsonField || 'teamKey'
258
261
  const raw = fs.readFileSync(file, 'utf-8')
259
- fs.writeFileSync(file, raw.replace(/("teamKey"\s*:\s*")([^"]*)(")/, `$1${plan.configKey.to}$3`), 'utf-8')
262
+ const re = new RegExp('("' + keyField + '"\\s*:\\s*")([^"]*)(")')
263
+ fs.writeFileSync(file, raw.replace(re, `$1${plan.configKey.to}$3`), 'utf-8')
260
264
  changed.configKey = true
261
265
  }
262
266
 
@@ -1,63 +1,42 @@
1
1
  'use strict'
2
2
 
3
3
  /**
4
- * Compare what Linear STORED against what we sent, and report lost text.
4
+ * Compare what the tracker STORED against what we sent, and report lost text.
5
5
  *
6
- * Why this is not a pull. One-way sync's rule is about **authority**: Linear
7
- * must never influence repo content. This reads a description back to *check*
8
- * it — it merges nothing, writes nothing, and feeds nothing into the projection
9
- * or the snapshot. The repo remains the only source of truth; the only output is
10
- * a warning for a human. Without it, a parser that silently eats characters
11
- * produces a mirror that looks pushed and is wrong, which is exactly how the
12
- * nested-table corruption went unnoticed (see `tables.js`).
6
+ * Why this is not a pull. One-way sync's rule is about **authority**: the
7
+ * tracker must never influence repo content. This reads a description back to
8
+ * *check* it — it merges nothing, writes nothing, and feeds nothing into the
9
+ * projection or the snapshot. The repo remains the only source of truth; the
10
+ * only output is a warning for a human. Without it, a parser that silently eats
11
+ * characters produces a mirror that looks pushed and is wrong, which is exactly
12
+ * how the nested-table corruption went unnoticed (see the Linear provider's
13
+ * dialect, where that flattener now lives).
13
14
  *
14
- * The engine is offline, so the read itself belongs to the `/spec-push` skill —
15
- * it fetches over MCP and hands the result here, the same split
15
+ * The engine is offline, so the read itself belongs to the push skill — it
16
+ * fetches over MCP and hands the result here, the same split
16
17
  * `--workspace-states` already uses.
17
18
  *
19
+ * Each tracker reserialises text its own way, so the reduction that makes its
20
+ * benign transforms invisible is the provider's `config.dialect.canonicalForCompare`
21
+ * (see `src/dialect.js`); with no dialect the identity reduction applies.
22
+ *
18
23
  * Pure: no I/O, no clock, no randomness.
19
24
  */
20
25
 
21
- // Linear reserialises markdown on save. These transforms are all observed and
22
- // all harmless, so they are normalised away BEFORE comparing — otherwise every
23
- // push would report a false divergence.
24
- function canonicalForCompare(text) {
25
- return String(text == null ? '' : text)
26
- .replace(/\r\n/g, '\n')
27
- .split('\n')
28
- .map((line) =>
29
- line
30
- // Ordered-list markers → a placeholder. Linear renumbers lists, and the
31
- // digits it rewrites are alphanumeric, so a naive alphanumeric compare
32
- // would flag its own benign reformat as data loss. Normalising the
33
- // marker keeps digits significant EVERYWHERE ELSE — a port, a version, a
34
- // key length still count.
35
- .replace(/^(\s*)\d+\.(\s)/, '$1#.$2')
36
- // Unordered markers unify (`-`/`+` come back as `*`).
37
- .replace(/^(\s*)[*+-](\s)/, '$1-$2')
38
- // Checkbox marks case-fold. Targeted rather than lowercasing the whole
39
- // text, so a genuine case corruption in prose is still caught.
40
- .replace(/^(\s*-\s*\[)[xX](\])/, '$1x$2')
41
- // Table separator rows collapse (`|-------|` → `| -- |`).
42
- .replace(/^\s*\|[\s:|-]+\|\s*$/, '|--|')
43
- .replace(/[ \t]+$/, ''),
44
- )
45
- .join('\n')
46
- .replace(/\n{3,}/g, '\n\n')
47
- .trim()
48
- }
26
+ const { dialectOf } = require('./dialect.js')
49
27
 
50
28
  // The word-character stream: everything that carries meaning, with every
51
29
  // reformatting artefact (whitespace, bullets, asterisk boundaries, pipes,
52
30
  // separators) removed. Comparing these catches dropped characters while
53
- // ignoring every benign transform above.
54
- function stream(text) {
55
- return canonicalForCompare(text).replace(/[^\p{L}\p{N}]/gu, '')
31
+ // ignoring every benign transform the dialect names.
32
+ function stream(text, config) {
33
+ return dialectOf(config).canonicalForCompare(text).replace(/[^\p{L}\p{N}]/gu, '')
56
34
  }
57
35
 
58
36
  /**
59
37
  * @param {string} sent what we pushed
60
38
  * @param {string} stored what the tracker returned
39
+ * @param {object} [config] the provider config (for its dialect)
61
40
  * @returns {{ok:boolean, at:number|null, lost:number, sentContext:string, storedContext:string}}
62
41
  * `ok` false means word characters differ — content was lost or altered.
63
42
  * `at` is the index in the reduced stream where they first diverge, with ~40
@@ -68,9 +47,9 @@ function stream(text) {
68
47
  // and read as total loss. The evidence that the read happened lives with the
69
48
  // caller, so it must pass only a description it actually read back (`verifyLines`
70
49
  // gates on `typeof stored.issue === 'string'` for exactly this reason).
71
- function compareStored(sent, stored) {
72
- const a = stream(sent)
73
- const b = stream(stored)
50
+ function compareStored(sent, stored, config) {
51
+ const a = stream(sent, config)
52
+ const b = stream(stored, config)
74
53
  if (a === b) return { ok: true, at: null, lost: 0, sentContext: '', storedContext: '' }
75
54
 
76
55
  let at = 0
@@ -85,4 +64,4 @@ function compareStored(sent, stored) {
85
64
  }
86
65
  }
87
66
 
88
- module.exports = { compareStored, canonicalForCompare, stream }
67
+ module.exports = { compareStored, stream }
@@ -5,7 +5,8 @@
5
5
  * Linear, the skill stamps each returned id back into the repo so the next push
6
6
  * updates rather than recreates. Everything here edits the repo in place:
7
7
  *
8
- * - `stampSubIssueId(dir, file, id)` — add/update `linear_issue_id` in a phase
8
+ * - `stampSubIssueId(dir, file, id, config)` — add/update the provider's
9
+ * phase-stamp field (`config.fields.issueId`) in a phase
9
10
  * file's frontmatter (locate the file with `findPhaseFileByTitle`).
10
11
  * - `writeFrontmatter(dir, config, patch)` — patch `00-overview.md` frontmatter
11
12
  * (e.g. the spec issue's `spec_identifier`, `last_synced_at`).
@@ -18,6 +19,7 @@
18
19
  const fs = require('node:fs')
19
20
  const path = require('node:path')
20
21
  const { findTaskBlocks, renderTaskBlock, collapse, inferWidth } = require('./task-block.js')
22
+ const { fieldsOf } = require('./fields.js')
21
23
 
22
24
  // Serialize a JS value as a YAML-ish frontmatter scalar.
23
25
  function serialize(value) {
@@ -143,13 +145,13 @@ function findPhaseFileByTitle(snapshotDir, name) {
143
145
  return null
144
146
  }
145
147
 
146
- // Add/update linear_issue_id in a phase file's frontmatter (in place) — the
147
- // sub-issue id for that phase.
148
- function stampSubIssueId(snapshotDir, file, id) {
148
+ // Add/update the provider's phase-stamp field (`config.fields.issueId`) in a
149
+ // phase file's frontmatter (in place) — the sub-issue id for that phase.
150
+ function stampSubIssueId(snapshotDir, file, id, config) {
149
151
  const p = path.join(snapshotDir, file)
150
152
  const raw = fs.readFileSync(p, 'utf-8')
151
153
  const { fmLines, body, had } = splitFrontmatter(raw)
152
- const patched = patchFrontmatterLines(fmLines, { linear_issue_id: String(id) })
154
+ const patched = patchFrontmatterLines(fmLines, { [fieldsOf(config).issueId]: String(id) })
153
155
  const fm = `---\n${patched.join('\n')}\n---\n`
154
156
  fs.writeFileSync(p, had ? fm + body : fm + '\n' + raw, 'utf-8')
155
157
  }