@skitterbyte/skitterspec-linear 18.3.1 → 19.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 +170 -1
- package/README.md +9 -7
- package/assets/core/SETUP.md +4 -4
- package/assets/core/env.config.md +1 -1
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +59 -48
- package/assets/rules/spec-planning.md +35 -12
- package/assets/rules/spec-reports.md +47 -6
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +32 -9
- package/assets/skills/spec-bug/SKILL.md +6 -4
- package/assets/skills/spec-hotfix/SKILL.md +4 -2
- package/assets/skills/spec-linear-setup/SKILL.md +9 -35
- package/assets/skills/spec-list/SKILL.md +13 -1
- package/assets/skills/spec-next/SKILL.md +5 -3
- package/assets/skills/spec-push/SKILL.md +1 -1
- package/assets/skills/spec-status/SKILL.md +30 -26
- package/assets/skills/spec-sync/SKILL.md +6 -5
- package/package.json +1 -1
- package/src/cli.js +114 -28
- package/src/env/resolve.js +11 -4
- package/src/env/review.js +126 -2
- package/src/vendor/linear/api.js +30 -1
- package/src/vendor/linear/cli-sync.js +64 -269
- package/src/vendor/linear/config.js +30 -49
- package/src/vendor/linear/doctor.js +4 -66
- package/src/vendor/provider-kit/src/config.js +101 -48
- package/src/vendor/provider-kit/src/list-assignee.js +71 -0
- package/src/vendor/provider-kit/src/list-rows.js +35 -0
- package/src/vendor/provider-kit/src/released.js +27 -77
- package/src/vendor/provider-kit/src/specs.js +89 -7
- package/src/vendor/sync-core/index.js +3 -4
- package/src/vendor/sync-core/src/compare.js +6 -6
- package/src/vendor/sync-core/src/normalize.js +60 -59
- package/assets/core/ci-stages.md +0 -110
- package/src/vendor/provider-kit/src/releases.js +0 -380
|
@@ -14,7 +14,16 @@
|
|
|
14
14
|
const fs = require('node:fs')
|
|
15
15
|
const path = require('node:path')
|
|
16
16
|
|
|
17
|
-
const {
|
|
17
|
+
const { execFileSync } = require('node:child_process')
|
|
18
|
+
|
|
19
|
+
const {
|
|
20
|
+
BUCKETS,
|
|
21
|
+
findSpecFolder,
|
|
22
|
+
resolveSpec,
|
|
23
|
+
liveWorktreePaths,
|
|
24
|
+
resolvePrimaryCheckout,
|
|
25
|
+
} = require('../../../env/resolve.js')
|
|
26
|
+
const { loadEnvConfig } = require('../../../env/config.js')
|
|
18
27
|
const { readSnapshot, parseFrontmatter, lintPhases, fieldsOf, projectionOf, compareStored } = require('../../sync-core')
|
|
19
28
|
|
|
20
29
|
function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
@@ -45,22 +54,32 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
|
45
54
|
// Read a spec's stamped identifier without throwing: an unlinked spec, an
|
|
46
55
|
// unreadable file and a spec with no frontmatter all read as `null`.
|
|
47
56
|
function linkedIdentifier(overviewPath, config) {
|
|
48
|
-
|
|
57
|
+
return linkedFields(overviewPath, config).identifier
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// The stamped identifier AND url, each `null` when absent. The url is only
|
|
61
|
+
// ever what a push stamped — never built from the identifier, because a url
|
|
62
|
+
// constructed here would be a guess about a tracker's address scheme.
|
|
63
|
+
function linkedFields(overviewPath, config) {
|
|
64
|
+
const fields = fieldsOf(config)
|
|
49
65
|
let raw
|
|
50
66
|
try {
|
|
51
67
|
raw = fs.readFileSync(overviewPath, 'utf-8')
|
|
52
68
|
} catch {
|
|
53
|
-
return null
|
|
69
|
+
return { identifier: null, url: null }
|
|
54
70
|
}
|
|
55
71
|
const { data } = parseFrontmatter(raw)
|
|
56
|
-
return
|
|
72
|
+
return {
|
|
73
|
+
identifier: data[fields.identifier] ? String(data[fields.identifier]) : null,
|
|
74
|
+
url: fields.url && data[fields.url] ? String(data[fields.url]) : null,
|
|
75
|
+
}
|
|
57
76
|
}
|
|
58
77
|
|
|
59
78
|
// Every spec under specs/<bucket>/, paired with the tracker issue it is
|
|
60
79
|
// linked to (`null` when it has never been pushed). Folder specs read
|
|
61
80
|
// `snapshot.overviewFile`; legacy bare `<name>.md` specs read the file
|
|
62
81
|
// itself. Sorted for stable output.
|
|
63
|
-
function listSpecs(dir, config) {
|
|
82
|
+
function listSpecs(dir, config, options = {}) {
|
|
64
83
|
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
65
84
|
const specs = []
|
|
66
85
|
for (const bucket of BUCKETS) {
|
|
@@ -83,12 +102,75 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
|
83
102
|
} else {
|
|
84
103
|
continue
|
|
85
104
|
}
|
|
86
|
-
|
|
105
|
+
const linked = linkedFields(overviewPath, config)
|
|
106
|
+
const row = { spec: name, bucket, identifier: linked.identifier }
|
|
107
|
+
// Opt-in, so every listing that never asked for a url keeps its shape.
|
|
108
|
+
if (options.urls) row.url = linked.url
|
|
109
|
+
specs.push(row)
|
|
87
110
|
}
|
|
88
111
|
}
|
|
89
112
|
return specs.sort((a, b) => a.spec.localeCompare(b.spec))
|
|
90
113
|
}
|
|
91
114
|
|
|
115
|
+
// `listSpecs`, but each spec's BUCKET read from where that spec actually
|
|
116
|
+
// lives. `/spec-start` moves a spec to `in-progress/` on its own branch, so
|
|
117
|
+
// on the base branch an in-flight spec still reads `backlog` — and a spec
|
|
118
|
+
// authored in its own worktree and not yet landed is not here at all. Each
|
|
119
|
+
// live worktree is read too, and a spec found in ITS OWN worktree (the path
|
|
120
|
+
// `resolveSpec` names for it) wins over every other copy. `source` says
|
|
121
|
+
// which: `here`, `worktree`, or `other-tree` for a spec only some other
|
|
122
|
+
// worktree carries.
|
|
123
|
+
//
|
|
124
|
+
// WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is
|
|
125
|
+
// still live, so a finished spec can read from a stale tree. And with no
|
|
126
|
+
// `env.config.json` there is no worktree layout to resolve, so this is
|
|
127
|
+
// exactly `listSpecs` — the current tree's answer, as before.
|
|
128
|
+
function listSpecsLive(dir, config) {
|
|
129
|
+
const here = listSpecs(dir, config).map((s) => ({ ...s, source: 'here' }))
|
|
130
|
+
const git = (args) => {
|
|
131
|
+
try {
|
|
132
|
+
return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
|
|
133
|
+
} catch {
|
|
134
|
+
return null
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
let primary
|
|
138
|
+
let env
|
|
139
|
+
try {
|
|
140
|
+
primary = resolvePrimaryCheckout(dir, git) || dir
|
|
141
|
+
env = loadEnvConfig(primary)
|
|
142
|
+
} catch {
|
|
143
|
+
return here
|
|
144
|
+
}
|
|
145
|
+
if (!env.present) return here
|
|
146
|
+
// Compared as REAL paths: git reports a worktree resolved through
|
|
147
|
+
// symlinks (macOS /var → /private/var) where `resolveSpec` does not.
|
|
148
|
+
const real = (p) => {
|
|
149
|
+
try {
|
|
150
|
+
return fs.realpathSync(p)
|
|
151
|
+
} catch {
|
|
152
|
+
return path.resolve(p)
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
const self = real(dir)
|
|
156
|
+
const byName = new Map(here.map((s) => [s.spec, s]))
|
|
157
|
+
for (const listed of liveWorktreePaths(git)) {
|
|
158
|
+
const tree = real(listed)
|
|
159
|
+
if (tree === self) continue
|
|
160
|
+
for (const s of listSpecs(tree, config)) {
|
|
161
|
+
let own = null
|
|
162
|
+
try {
|
|
163
|
+
own = real(resolveSpec(s.spec, primary, env.config, { searchDirs: [tree] }).worktreePath)
|
|
164
|
+
} catch {
|
|
165
|
+
own = null
|
|
166
|
+
}
|
|
167
|
+
if (own === tree) byName.set(s.spec, { ...s, source: 'worktree' })
|
|
168
|
+
else if (!byName.has(s.spec)) byName.set(s.spec, { ...s, source: 'other-tree' })
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
return [...byName.values()].sort((a, b) => a.spec.localeCompare(b.spec))
|
|
172
|
+
}
|
|
173
|
+
|
|
92
174
|
// Resolve a spec argument to its folder, or null with a message on stdout.
|
|
93
175
|
// EVERY failure path here must print and EVERY caller must return a non-zero
|
|
94
176
|
// code: a push skill checks $? before it applies a plan, so a resolve failure
|
|
@@ -160,7 +242,7 @@ function makeSpecHelpers({ program = 'spec-sync' } = {}) {
|
|
|
160
242
|
return lines
|
|
161
243
|
}
|
|
162
244
|
|
|
163
|
-
return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr, verifyLines }
|
|
245
|
+
return { resolveSnapshotDir, specIdentifier, linkedIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr, verifyLines }
|
|
164
246
|
}
|
|
165
247
|
|
|
166
248
|
module.exports = { makeSpecHelpers }
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
* stored matches what was sent — it merges nothing (see `src/verify.js`).
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
|
-
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState,
|
|
16
|
+
const { ownsField, normalizeLocal, LIFECYCLE_BUCKETS, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, remoteStateReading, stateNamesFor, titleFromText, validateStates, stateSuggestions, phaseModeFor } = require('./src/normalize.js')
|
|
17
17
|
const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify, remoteDescriptionEdited, remoteSubIssueEdited } = require('./src/compare.js')
|
|
18
18
|
const { readBase, writeBase } = require('./src/base.js')
|
|
19
19
|
const { push, recordPush, projectionOf } = require('./src/push.js')
|
|
@@ -41,12 +41,11 @@ module.exports = {
|
|
|
41
41
|
push,
|
|
42
42
|
recordPush,
|
|
43
43
|
remoteWorkflowState,
|
|
44
|
+
remoteStateReading,
|
|
45
|
+
stateNamesFor,
|
|
44
46
|
titleFromText,
|
|
45
47
|
validateStates,
|
|
46
48
|
stateSuggestions,
|
|
47
|
-
stageForState,
|
|
48
|
-
remoteStage,
|
|
49
|
-
LADDER_ORIGIN_BUCKET,
|
|
50
49
|
hashField,
|
|
51
50
|
stableStringify,
|
|
52
51
|
readBase,
|
|
@@ -58,12 +58,12 @@ function specIssueHash(p) {
|
|
|
58
58
|
|
|
59
59
|
// Per-field hashes of the same two values.
|
|
60
60
|
//
|
|
61
|
-
// They are hashed SEPARATELY because
|
|
62
|
-
//
|
|
63
|
-
//
|
|
64
|
-
//
|
|
65
|
-
//
|
|
66
|
-
// description without re-asserting a state
|
|
61
|
+
// They are hashed SEPARATELY because skitterspec tells the tracker about its
|
|
62
|
+
// own transitions and nothing else. The description is resent whenever it
|
|
63
|
+
// changes; the state only when the spec itself moves. Welding the two meant any
|
|
64
|
+
// prose edit re-emitted the state and dragged back an issue someone had moved
|
|
65
|
+
// on the tracker — which is theirs to do. Diffing them apart is what lets a
|
|
66
|
+
// push touch the description without re-asserting a state.
|
|
67
67
|
function specIssueFieldHashes(p, config) {
|
|
68
68
|
const hashes = {
|
|
69
69
|
description: hashField(p.description ?? null),
|
|
@@ -405,15 +405,39 @@ function readSnapshot(snapshotDir, config) {
|
|
|
405
405
|
return { frontmatter: data, title, sections, phases, body }
|
|
406
406
|
}
|
|
407
407
|
|
|
408
|
+
// The headings a bug-shaped spec's ticket leads with, in this order, when the
|
|
409
|
+
// spec has them. A Bug ticket is read for its repro before anything else, and
|
|
410
|
+
// the feature overview order buries it. Sections a spec does not have are
|
|
411
|
+
// skipped, never invented — a legacy bug spec with feature-shaped sections
|
|
412
|
+
// renders exactly as it always did.
|
|
413
|
+
const BUG_LEAD_SECTIONS = ['Symptom', 'Repro', 'Expected', 'Actual', 'Root cause', 'Failing test (red)', 'Fix']
|
|
414
|
+
|
|
415
|
+
// A spec's kind off its folder prefix — the same convention the providers'
|
|
416
|
+
// `specKindOf` reads, kept local because sync-core depends on no other package.
|
|
417
|
+
function bugShaped(snapshotDir) {
|
|
418
|
+
const name = path.basename(String(snapshotDir || ''))
|
|
419
|
+
return name.startsWith('bug-') || name.startsWith('hotfix-')
|
|
420
|
+
}
|
|
421
|
+
|
|
408
422
|
// Build the pushed description: the overview prose with local-only sections
|
|
409
423
|
// removed. Keeps the title line for context. `extraSkip` drops additional
|
|
410
424
|
// sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
|
|
411
425
|
// the phase list isn't duplicated in the description — Decision 5).
|
|
412
|
-
|
|
426
|
+
// `leadSections` names headings to emit FIRST, in its order, matched
|
|
427
|
+
// case-insensitively; the rest follow in document order. Empty means document
|
|
428
|
+
// order throughout — byte-identical to before the parameter existed.
|
|
429
|
+
function buildDescription(title, sections, localOnlySections, extraSkip = [], dialect, leadSections = []) {
|
|
413
430
|
const skip = new Set([...(localOnlySections || []), ...extraSkip])
|
|
414
431
|
const parts = []
|
|
415
432
|
if (title) parts.push(`# ${title}`)
|
|
416
|
-
|
|
433
|
+
const entries = Object.entries(sections)
|
|
434
|
+
const lead = []
|
|
435
|
+
for (const want of leadSections) {
|
|
436
|
+
const hit = entries.find(([heading]) => heading.toLowerCase() === want.toLowerCase())
|
|
437
|
+
if (hit) lead.push(hit)
|
|
438
|
+
}
|
|
439
|
+
const ordered = [...lead, ...entries.filter((e) => !lead.includes(e))]
|
|
440
|
+
for (const [heading, content] of ordered) {
|
|
417
441
|
if (skip.has(heading)) continue
|
|
418
442
|
parts.push(`## ${heading}\n\n${content}`.trim())
|
|
419
443
|
}
|
|
@@ -706,6 +730,10 @@ function normalizeLocal(snapshotDir, config) {
|
|
|
706
730
|
config.sync.localOnlySections,
|
|
707
731
|
phasesCarriedBySubIssues ? ['Phases'] : [],
|
|
708
732
|
dialect,
|
|
733
|
+
// A bug or hotfix spec's ticket leads with the bug sections — a
|
|
734
|
+
// different render of the same overview, so the Bug form opens on the
|
|
735
|
+
// repro rather than the feature-shaped prose.
|
|
736
|
+
bugShaped(snapshotDir) ? BUG_LEAD_SECTIONS : [],
|
|
709
737
|
),
|
|
710
738
|
inlined,
|
|
711
739
|
tasksMode,
|
|
@@ -751,39 +779,27 @@ function phasesWithheld(snapshotDir, config) {
|
|
|
751
779
|
|
|
752
780
|
// --- remote projection ------------------------------------------------------
|
|
753
781
|
|
|
754
|
-
//
|
|
755
|
-
//
|
|
756
|
-
//
|
|
757
|
-
//
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
if (state == null) return null
|
|
763
|
-
const want = String(state).toLowerCase().trim()
|
|
764
|
-
const stages = (config && config.release && config.release.stages) || []
|
|
765
|
-
if (!Array.isArray(stages)) return null
|
|
766
|
-
return stages.find((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want) || null
|
|
782
|
+
// Every tracker state NAME that means this bucket: the one push writes
|
|
783
|
+
// (`states[bucket]`) first, then its read-only aliases (`stateAliases[bucket]`,
|
|
784
|
+
// from the array form of `states`). Readers use the whole list; writers only
|
|
785
|
+
// ever use `states[bucket]`, so an alias can never be written.
|
|
786
|
+
function stateNamesFor(bucket, config) {
|
|
787
|
+
const primary = config && config.states && config.states[bucket]
|
|
788
|
+
const aliases = (config && config.stateAliases && config.stateAliases[bucket]) || []
|
|
789
|
+
return [primary, ...(Array.isArray(aliases) ? aliases : [])].filter((n) => typeof n === 'string' && n)
|
|
767
790
|
}
|
|
768
791
|
|
|
769
792
|
// Map a remote workflow-state name back to the local lifecycle bucket (the
|
|
770
793
|
// vocabulary `spec_status` uses) via config.states, so local and remote
|
|
771
794
|
// workflowState hash equal when semantically equal. Falls back to a lowercased
|
|
772
795
|
// raw value when the state isn't one of the configured names.
|
|
773
|
-
//
|
|
774
|
-
// A DECLARED DEPLOYMENT STAGE reads as `complete`, deliberately. Without this
|
|
775
|
-
// the fallback lowercases it — "On Test" becomes "on test", which equals no
|
|
776
|
-
// bucket — and every deployed spec reports as drifted forever, for the whole
|
|
777
|
-
// time it sits in the pipeline. The project told us these states are downstream
|
|
778
|
-
// of a finished spec, so they are not a disagreement about where the spec is.
|
|
779
796
|
function bucketForState(state, config) {
|
|
780
797
|
if (state == null) return null
|
|
781
798
|
const states = (config && config.states) || {}
|
|
782
799
|
const want = String(state).toLowerCase().trim()
|
|
783
|
-
for (const
|
|
784
|
-
if (
|
|
800
|
+
for (const bucket of Object.keys(states)) {
|
|
801
|
+
if (stateNamesFor(bucket, config).some((name) => name.toLowerCase().trim() === want)) return bucket
|
|
785
802
|
}
|
|
786
|
-
if (stageForState(state, config)) return LADDER_ORIGIN_BUCKET
|
|
787
803
|
return want
|
|
788
804
|
}
|
|
789
805
|
|
|
@@ -818,11 +834,20 @@ function remoteWorkflowState(issue, config) {
|
|
|
818
834
|
return name != null ? bucketForState(name, config) : null
|
|
819
835
|
}
|
|
820
836
|
|
|
821
|
-
//
|
|
822
|
-
//
|
|
823
|
-
//
|
|
824
|
-
|
|
825
|
-
|
|
837
|
+
// What the drift report needs to know about a remote issue's state: its name,
|
|
838
|
+
// the bucket it maps to, and whether it maps to one at all. Null when the
|
|
839
|
+
// payload carried no state — a cannot-tell, never an answer.
|
|
840
|
+
//
|
|
841
|
+
// AN UNMAPPED STATE IS NOT A DISAGREEMENT. A tracker grows states skitterspec
|
|
842
|
+
// never names ("Blocked", "Next Sprint"), and a ticket a person moved into one
|
|
843
|
+
// is not wrong about the spec — it is somewhere push does not manage, and push
|
|
844
|
+
// will not move it until the spec itself moves. `mapped` is what lets a report
|
|
845
|
+
// say that rather than accuse it.
|
|
846
|
+
function remoteStateReading(issue, config) {
|
|
847
|
+
const name = remoteStateName(issue || {}, config)
|
|
848
|
+
if (name == null) return null
|
|
849
|
+
const bucket = bucketForState(name, config)
|
|
850
|
+
return { name: String(name), bucket, mapped: LIFECYCLE_BUCKETS.includes(bucket) }
|
|
826
851
|
}
|
|
827
852
|
|
|
828
853
|
// A Linear issue title is plain text, so markdown emphasis is noise there — and
|
|
@@ -897,24 +922,16 @@ function titleFromText(text, max = 100) {
|
|
|
897
922
|
return stripTitleMarkup(title)
|
|
898
923
|
}
|
|
899
924
|
|
|
900
|
-
// Every state NAME the config points at: the lifecycle bucket map
|
|
901
|
-
// project's deployment ladder when it declares one. Both reach Linear the same
|
|
902
|
-
// way and fail the same way, so both are checked by the same lookup.
|
|
925
|
+
// Every state NAME the config points at: the lifecycle bucket map.
|
|
903
926
|
function configuredStateNames(config) {
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
if (stage && typeof stage.state === 'string') names.push(stage.state)
|
|
908
|
-
}
|
|
909
|
-
return names
|
|
927
|
+
// The WRITTEN names only. An alias is never written, so one the workspace
|
|
928
|
+
// lacks cannot strand a push; `stateSuggestions` still names it in reports.
|
|
929
|
+
return Object.values((config && config.states) || {}).filter((v) => typeof v === 'string')
|
|
910
930
|
}
|
|
911
931
|
|
|
912
932
|
// Which configured state NAMES are absent from the live workspace. The skill
|
|
913
933
|
// fetches the workspace's project-status names over MCP and passes them here;
|
|
914
934
|
// a non-empty result means a typo/rename that Linear would silently no-op.
|
|
915
|
-
//
|
|
916
|
-
// A project with no `release.stages` contributes nothing here, so the ladder
|
|
917
|
-
// cannot make this accuse a config that was fine before it existed.
|
|
918
935
|
function validateStates(config, workspaceStates) {
|
|
919
936
|
const configured = configuredStateNames(config)
|
|
920
937
|
const have = new Set((workspaceStates || []).map((s) => String(s).toLowerCase().trim()))
|
|
@@ -953,21 +970,6 @@ function stateSuggestions(config, workspaceStates) {
|
|
|
953
970
|
const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
|
|
954
971
|
out.push({ bucket, configured, suggestion, label: `states.${bucket}` })
|
|
955
972
|
}
|
|
956
|
-
// Deployment-ladder rungs, reported the same way. No suggestion is offered:
|
|
957
|
-
// BUCKET_WORDS describes lifecycle vocabulary, and a stage name is the
|
|
958
|
-
// project's own — guessing "On Test" meant "In Progress" would be worse than
|
|
959
|
-
// saying nothing.
|
|
960
|
-
const stages = (config && config.release && config.release.stages) || []
|
|
961
|
-
for (const stage of Array.isArray(stages) ? stages : []) {
|
|
962
|
-
if (!stage || typeof stage.state !== 'string') continue
|
|
963
|
-
if (have.has(stage.state.toLowerCase().trim())) continue
|
|
964
|
-
out.push({
|
|
965
|
-
bucket: null,
|
|
966
|
-
configured: stage.state,
|
|
967
|
-
suggestion: null,
|
|
968
|
-
label: `release.stages[${stage.key}]`,
|
|
969
|
-
})
|
|
970
|
-
}
|
|
971
973
|
return out
|
|
972
974
|
}
|
|
973
975
|
|
|
@@ -991,8 +993,7 @@ module.exports = {
|
|
|
991
993
|
canonicalRemoteStatus,
|
|
992
994
|
bucketForState,
|
|
993
995
|
LIFECYCLE_BUCKETS,
|
|
994
|
-
stageForState,
|
|
995
|
-
remoteStage,
|
|
996
996
|
remoteWorkflowState,
|
|
997
|
-
|
|
997
|
+
remoteStateReading,
|
|
998
|
+
stateNamesFor,
|
|
998
999
|
}
|
package/assets/core/ci-stages.md
DELETED
|
@@ -1,110 +0,0 @@
|
|
|
1
|
-
# Wiring a deploy pipeline to Linear
|
|
2
|
-
|
|
3
|
-
How a CI/CD pipeline moves a release's tickets along the ladder declared in
|
|
4
|
-
`linear.config.json` → `release.stages`. Read `linear.config.md` → "The
|
|
5
|
-
deployment ladder" first for the config itself; this page is the pipeline half.
|
|
6
|
-
|
|
7
|
-
Nothing here applies until a ladder is declared. Without one, `spec-sync stage`
|
|
8
|
-
refuses and every other command behaves as it always has.
|
|
9
|
-
|
|
10
|
-
## The model
|
|
11
|
-
|
|
12
|
-
A spec's lifecycle ends at `complete`. Everything after that is a fact about an
|
|
13
|
-
**environment**, which no folder under `specs/` can derive — so the repo hands
|
|
14
|
-
off. The handoff point is one-way and automatic:
|
|
15
|
-
|
|
16
|
-
```
|
|
17
|
-
/spec-complete → states.complete (the repo's last word on state)
|
|
18
|
-
CI: spec-sync stage test → release.stages test (the pipeline's, from here on)
|
|
19
|
-
CI: spec-sync stage prod → release.stages prod
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
Once a spec is complete, pushes stop re-asserting its workflow state, so the
|
|
23
|
-
pipeline is the only writer. Editing a finished spec's prose still updates the
|
|
24
|
-
mirror's description; it will not drag the ticket back out of the pipeline.
|
|
25
|
-
|
|
26
|
-
## What a stage step runs
|
|
27
|
-
|
|
28
|
-
```sh
|
|
29
|
-
skitterspec spec-sync stage <key> <previous-tag>..<this-tag> --apply
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
- **Pass the range explicitly.** With no range it defaults to
|
|
33
|
-
`git describe --tags --abbrev=0`..HEAD, which is a developer convenience — a
|
|
34
|
-
pipeline knows exactly which tag it is deploying, and should say so. The
|
|
35
|
-
resolved range is printed on every run either way.
|
|
36
|
-
- **Drop `--apply` to dry-run.** Same output, no writes. Worth running in a
|
|
37
|
-
pre-deploy job.
|
|
38
|
-
- **`--json`** for a machine-readable result: the moves, the skips by category,
|
|
39
|
-
and the commit counts.
|
|
40
|
-
- **Exit code is 0 unless a write failed**, so a failed move fails the stage.
|
|
41
|
-
A range with nothing to move is a success, not a failure.
|
|
42
|
-
|
|
43
|
-
The tickets come from `Refs:` trailers on the commits in the range (see the
|
|
44
|
-
`commit-trailers` rule). A commit with no trailer is counted and reported, never
|
|
45
|
-
guessed at.
|
|
46
|
-
|
|
47
|
-
## Setup
|
|
48
|
-
|
|
49
|
-
1. **A ladder in `linear.config.json`** — via `/spec-linear-setup`, or
|
|
50
|
-
`spec-sync init-config --stage test="On Test" --stage prod="Done"`.
|
|
51
|
-
2. **An API key as a pipeline secret**, exposed as the env var named by
|
|
52
|
-
`auth.keyEnv` (default `LINEAR_API_KEY`). The config names the *variable*,
|
|
53
|
-
never the key. `--apply` needs the API transport and refuses over MCP.
|
|
54
|
-
3. **Full history for the range** (CI: `fetch-depth: 0`). Fetching tags is not
|
|
55
|
-
enough on its own: it makes the tag *resolve* without deepening the history,
|
|
56
|
-
so `git log <tag>..HEAD` would return only the commits the clone happens to
|
|
57
|
-
hold. `stage` and `released` check this and **refuse** rather than report a
|
|
58
|
-
partial range, so a shallow checkout fails the step loudly instead of
|
|
59
|
-
deploying a release that quietly leaves tickets behind.
|
|
60
|
-
4. **Run `spec-sync doctor --check-remote` once** after setup. It reports the
|
|
61
|
-
ladder's rungs against the workspace and warns if the last rung never closes
|
|
62
|
-
an issue.
|
|
63
|
-
|
|
64
|
-
### Azure Pipelines
|
|
65
|
-
|
|
66
|
-
```yaml
|
|
67
|
-
- task: Bash@3
|
|
68
|
-
displayName: Mark tickets as deployed to test
|
|
69
|
-
env:
|
|
70
|
-
LINEAR_API_KEY: $(LinearApiKey) # a secret variable, not inline
|
|
71
|
-
inputs:
|
|
72
|
-
targetType: inline
|
|
73
|
-
script: |
|
|
74
|
-
set -euo pipefail
|
|
75
|
-
npx skitterspec spec-sync stage test "$(PreviousTag)..$(Build.SourceBranchName)" --apply
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
Repeat per environment with a different `<key>`: a post-deploy step on the test
|
|
79
|
-
stage runs `stage test`, the demo approval gate runs `stage demo`, the production
|
|
80
|
-
deploy runs `stage prod`.
|
|
81
|
-
|
|
82
|
-
## Why not call the API directly
|
|
83
|
-
|
|
84
|
-
A hand-rolled `curl` to Linear's GraphQL endpoint loses three things this command
|
|
85
|
-
has, and the loss is silent in all three cases:
|
|
86
|
-
|
|
87
|
-
- **State-name validation.** Linear **silently ignores** an unknown workflow
|
|
88
|
-
state: the mutation succeeds, and the issue never moves. `stage` resolves the
|
|
89
|
-
target state before its first write and refuses if the workspace lacks it.
|
|
90
|
-
- **The skip rules.** A range carries refs that must not be moved — another
|
|
91
|
-
team's, ones no spec claims, and specs that have not finished. A blanket loop
|
|
92
|
-
over every ref in the log moves all of them.
|
|
93
|
-
- **Retries and error classification.** The adapter retries transient failures;
|
|
94
|
-
a bare `curl` reports a 500 as success if you forget to check.
|
|
95
|
-
|
|
96
|
-
## What it will not move, and why
|
|
97
|
-
|
|
98
|
-
Every skipped ref is named in the output with its reason — a silent exclusion and
|
|
99
|
-
a successful move look identical in a pipeline log.
|
|
100
|
-
|
|
101
|
-
| Skipped | Reason |
|
|
102
|
-
|---|---|
|
|
103
|
-
| another team's ref | not `linear.teamKey`; writing to an unconfigured team is the worst failure available here |
|
|
104
|
-
| no spec claims it | tracker-only work, or a typo in a trailer — nothing here can tell which |
|
|
105
|
-
| spec not complete | it landed via `/spec-to-main`; push still owns its state and would bounce it back |
|
|
106
|
-
| unreadable | Linear did not return the issue; dropped rather than guessed at |
|
|
107
|
-
|
|
108
|
-
A move that runs against the declared order — backwards, or skipping a rung —
|
|
109
|
-
**warns and proceeds**. A rollback from test and a hotfix going straight to prod
|
|
110
|
-
are both legitimate, and refusing either would be wrong on healthy input.
|