@skitterbyte/skitterspec-linear 18.0.1 → 18.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/MIGRATION.md +81 -0
- package/assets/core/env.config.md +33 -9
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/assets/rules/spec-planning.md +4 -2
- package/assets/skills/spec-complete/SKILL.md +67 -25
- package/assets/skills/spec-hotfix/SKILL.md +21 -11
- package/assets/skills/spec-sync/SKILL.md +10 -1
- package/package.json +1 -1
- package/src/cli.js +289 -34
- package/src/env/config.js +14 -2
- package/src/env/hotfix.js +261 -15
- package/src/env/hotfixland.js +302 -0
- package/src/env/resolve.js +22 -8
- package/src/init.js +36 -4
- package/src/vendor/linear/api.js +43 -56
- package/src/vendor/linear/cli-sanitise.js +2 -2
- package/src/vendor/linear/cli-sync.js +87 -390
- package/src/vendor/linear/config.js +46 -171
- package/src/vendor/linear/credentials.js +40 -370
- package/src/vendor/linear/dialect.js +177 -0
- package/src/vendor/linear/doctor.js +7 -15
- package/src/vendor/linear/identity.js +20 -70
- package/src/vendor/linear/released.js +4 -222
- package/src/vendor/{sync-core/src → linear}/sanitise.js +4 -3
- package/src/vendor/provider-kit/index.js +41 -0
- package/src/vendor/provider-kit/src/adapter.js +23 -0
- package/src/vendor/provider-kit/src/apply.js +197 -0
- package/src/vendor/provider-kit/src/args.js +68 -0
- package/src/vendor/provider-kit/src/config.js +198 -0
- package/src/vendor/provider-kit/src/credentials.js +404 -0
- package/src/vendor/provider-kit/src/doctor.js +35 -0
- package/src/vendor/provider-kit/src/http.js +44 -0
- package/src/vendor/provider-kit/src/identity.js +93 -0
- package/src/vendor/provider-kit/src/md-compare.js +39 -0
- package/src/vendor/{sync-core/src/tables.js → provider-kit/src/md-tables.js} +10 -18
- package/src/vendor/provider-kit/src/prompt.js +50 -0
- package/src/vendor/provider-kit/src/released.js +226 -0
- package/src/vendor/provider-kit/src/specs.js +166 -0
- package/src/vendor/provider-kit/src/transport.js +22 -0
- package/src/vendor/sync-core/index.js +22 -5
- package/src/vendor/sync-core/src/compare.js +14 -12
- package/src/vendor/sync-core/src/dialect.js +51 -0
- package/src/vendor/sync-core/src/fields.js +36 -0
- package/src/vendor/sync-core/src/legacy.js +19 -9
- package/src/vendor/sync-core/src/normalize.js +30 -158
- package/src/vendor/sync-core/src/push.js +1 -1
- package/src/vendor/sync-core/src/retarget.js +21 -17
- package/src/vendor/sync-core/src/verify.js +24 -45
- 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 {
|
|
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.
|
|
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
|
|
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
|
|
566
|
-
return
|
|
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.
|
|
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
|
-
//
|
|
923
|
-
// `{ name, type }`); accept `status` / a bare string too for robustness.
|
|
924
|
-
|
|
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 ("
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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**:
|
|
7
|
-
* must never influence repo content. This reads a description back to
|
|
8
|
-
* it — it merges nothing, writes nothing, and feeds nothing into the
|
|
9
|
-
* or the snapshot. The repo remains the only source of truth; the
|
|
10
|
-
* a warning for a human. Without it, a parser that silently eats
|
|
11
|
-
* produces a mirror that looks pushed and is wrong, which is exactly
|
|
12
|
-
* nested-table corruption went unnoticed (see
|
|
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
|
|
15
|
-
*
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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, {
|
|
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
|
}
|