@skitterbyte/skitterspec-linear 18.3.0 → 19.0.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.
@@ -30,10 +30,7 @@
30
30
  */
31
31
 
32
32
  // The states, the row shape and the combining rule are the kit's
33
- // (`provider-kit/src/doctor.js`); the checks below are Linear's. A ladder whose
34
- // last rung never closes an issue is a real problem for most projects and a
35
- // deliberate choice for some, and only the project knows which — which is what
36
- // the kit's `warn` state exists for.
33
+ // (`provider-kit/src/doctor.js`); the checks below are Linear's.
37
34
  const { DOCTOR_STATES: STATES, doctorRow: row, combineDoctorChecks } = require('../provider-kit/src/doctor.js')
38
35
 
39
36
  /**
@@ -56,73 +53,14 @@ function runChecks(state = {}) {
56
53
  keyCheck(state.key, state.tracker),
57
54
  identityCheck(state.identity, state.tracker),
58
55
  remoteCheck(state.remote),
59
- ladderCheck(state.ladder, state.tracker),
60
56
  mcpCheck(state.mcp, state.tracker, state.project, state.remote),
61
57
  ]
58
+ // A retired config key is a stale file, not a broken one (provider-kit
59
+ // `retiredKeysRow`): present only when the config still carries one.
60
+ if (state.retired) checks.push(state.retired)
62
61
  return combineDoctorChecks(checks)
63
62
  }
64
63
 
65
- /**
66
- * The deployment ladder's shape, when one is declared.
67
- *
68
- * WHAT COULD FOOL THIS CHECK, and why it is a `warn` rather than a refusal: a
69
- * workspace can close an issue by automation (a merged PR, a linked release)
70
- * rather than by the last rung's own type, and a ladder that stops at a
71
- * `started` state is then perfectly healthy. Only the project knows which it is.
72
- *
73
- * It needs the workspace's state TYPES, which only the API transport returns —
74
- * `--workspace-states` and the MCP path carry names alone. Without them the row
75
- * is `skipped`: not knowing a type is not evidence of a bad one.
76
- */
77
- function ladderCheck(s = {}, tracker = {}) {
78
- if (!tracker.present) return row('ladder', 'ladder', 'skipped', 'no tracker configured')
79
- const stages = Array.isArray(s.stages) ? s.stages : []
80
- if (!stages.length) {
81
- return row('ladder', 'ladder', 'skipped', 'no deployment ladder declared')
82
- }
83
-
84
- const summary = stages.map((st) => `${st.key} -> ${st.state}`).join(', ')
85
- const states = Array.isArray(s.workspaceStates) ? s.workspaceStates : null
86
- if (!states) {
87
- return row('ladder', 'ladder', 'skipped', `${stages.length} rung(s), unchecked: ${summary}`)
88
- }
89
-
90
- const byName = new Map(
91
- states.filter((st) => st && typeof st.name === 'string').map((st) => [st.name.toLowerCase().trim(), st]),
92
- )
93
- // A list that arrived EMPTY, or held nothing with a name, cannot prove a rung
94
- // is absent — it is a lookup that saw nothing, not a workspace without these
95
- // states. Accusing every rung off that would be the exact absence-as-evidence
96
- // mistake the negative-checks rule exists for.
97
- if (!byName.size) {
98
- return row('ladder', 'ladder', 'skipped', `${stages.length} rung(s), unchecked: ${summary}`)
99
- }
100
- const unknown = stages.filter((st) => !byName.has(String(st.state).toLowerCase().trim()))
101
- if (unknown.length) {
102
- return row(
103
- 'ladder',
104
- 'ladder',
105
- 'broken',
106
- `rung state(s) not in this workspace: ${unknown.map((st) => `${st.key} -> "${st.state}"`).join(', ')}` +
107
- ' — Linear silently ignores an unknown state, so these would move nothing',
108
- '/spec-linear-setup',
109
- )
110
- }
111
-
112
- const last = stages[stages.length - 1]
113
- const type = (byName.get(String(last.state).toLowerCase().trim()) || {}).type
114
- if (type !== 'completed') {
115
- return row(
116
- 'ladder',
117
- 'ladder',
118
- 'warn',
119
- `ends at "${last.state}" (type: ${type || 'unknown'}) — an issue finishing the ladder never reaches a ` +
120
- 'completed state. Add a final rung, or ignore this if Linear automation closes them.',
121
- )
122
- }
123
- return row('ladder', 'ladder', 'ok', `${stages.length} rung(s): ${summary}`)
124
- }
125
-
126
64
  function scaffoldCheck(s = {}) {
127
65
  if (!s.specsDir) {
128
66
  return row('scaffold', 'scaffold', 'missing', 'no specs/ folder', 'skitterspec init')
@@ -98,52 +98,6 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
98
98
  }
99
99
  }
100
100
 
101
- // Merge (and validate) `release.stages` — the project's deployment ladder.
102
- //
103
- // Loud on a malformed entry: this list names tracker states, and a tracker
104
- // that silently ignores an unknown state would let a half-typed ladder push
105
- // clean and move nothing — so a bad shape fails here, at load, rather than at
106
- // the first deploy nobody is watching. An ABSENT `release` block is not an
107
- // error: it is the opt-out, and the whole feature is unused without it.
108
- function mergeReleaseStages(base, parsed) {
109
- const value = parsed.stages
110
- if (value === undefined) return
111
- if (!Array.isArray(value)) {
112
- throw new Error(
113
- `Invalid ${configFile}: release.stages = ${JSON.stringify(value)} ` +
114
- '(expected an array of { key, state })',
115
- )
116
- }
117
- const stages = []
118
- const seen = new Set()
119
- value.forEach((entry, i) => {
120
- if (!isObject(entry)) {
121
- throw new Error(
122
- `Invalid ${configFile}: release.stages[${i}] = ${JSON.stringify(entry)} ` +
123
- '(expected { key, state })',
124
- )
125
- }
126
- for (const field of ['key', 'state']) {
127
- if (typeof entry[field] !== 'string' || !entry[field].trim()) {
128
- throw new Error(
129
- `Invalid ${configFile}: release.stages[${i}].${field} = ${JSON.stringify(entry[field])} ` +
130
- '(expected a non-empty string)',
131
- )
132
- }
133
- }
134
- const key = entry.key.trim()
135
- if (seen.has(key)) {
136
- throw new Error(
137
- `Invalid ${configFile}: release.stages[${i}].key = ${JSON.stringify(key)} is a duplicate ` +
138
- '(a stage key is how CI names the rung, so it must be unique)',
139
- )
140
- }
141
- seen.add(key)
142
- stages.push({ key, state: entry.state.trim() })
143
- })
144
- base.stages = stages
145
- }
146
-
147
101
  // Merge (and validate) release.ignorePaths — the path prefixes whose commits
148
102
  // are bookkeeping. Loud on anything but an array of non-empty strings: a bad
149
103
  // value that quietly fell back would let a project believe it had opted out
@@ -186,13 +140,112 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
186
140
  }
187
141
  }
188
142
 
143
+ // Merge (and validate) `states`. A bucket's value is a string — the one state
144
+ // push writes, exactly as it always was — or a non-empty array whose FIRST
145
+ // name is the one push writes and whose rest are read-only aliases: tracker
146
+ // states that also mean this bucket ("Blocked" for in-progress). The first
147
+ // name lands in `states[bucket]`, so every writer is unchanged; the rest go
148
+ // to `stateAliases[bucket]`, read only by code that interprets a remote state.
149
+ //
150
+ // An ALIAS in two buckets is refused: it would make a remote state mean two
151
+ // things, and which one won would be an accident of iteration order. Two
152
+ // buckets sharing one written name stays legal, as it always was — a tracker
153
+ // with no Cancelled state maps cancelled to "Done" — so only a name that an
154
+ // alias contributes is checked.
155
+ function mergeStates(base, parsed) {
156
+ const value = parsed.states
157
+ if (!isObject(value)) return
158
+ const aliases = {}
159
+ for (const bucket of Object.keys(base.states)) {
160
+ const entry = value[bucket]
161
+ if (entry === undefined) continue
162
+ if (typeof entry === 'string') {
163
+ if (entry.trim()) base.states[bucket] = entry.trim()
164
+ continue
165
+ }
166
+ if (!Array.isArray(entry) || !entry.length || entry.some((n) => typeof n !== 'string' || !n.trim())) {
167
+ throw new Error(
168
+ `Invalid ${configFile}: states.${bucket} = ${JSON.stringify(entry)} ` +
169
+ '(expected a state name, or a non-empty array of them — the first is what push writes)',
170
+ )
171
+ }
172
+ const names = entry.map((n) => n.trim())
173
+ base.states[bucket] = names[0]
174
+ aliases[bucket] = names.slice(1)
175
+ }
176
+ const owner = new Map()
177
+ for (const bucket of Object.keys(base.states)) {
178
+ const key = base.states[bucket].toLowerCase()
179
+ if (!owner.has(key)) owner.set(key, bucket)
180
+ }
181
+ for (const bucket of Object.keys(aliases)) {
182
+ for (const name of aliases[bucket]) {
183
+ const key = name.toLowerCase()
184
+ if (owner.has(key) && owner.get(key) !== bucket) {
185
+ throw new Error(
186
+ `Invalid ${configFile}: states name ${JSON.stringify(name)} is in both ` +
187
+ `${owner.get(key)} and ${bucket} (a tracker state can mean only one bucket)`,
188
+ )
189
+ }
190
+ owner.set(key, bucket)
191
+ }
192
+ }
193
+ base.stateAliases = aliases
194
+ }
195
+
189
196
  return {
197
+ mergeStates,
190
198
  mergeFieldOwnership,
191
199
  mergePhaseMapping,
192
- mergeReleaseStages,
193
200
  mergeReleaseIgnorePaths,
194
201
  mergeKeyedFields,
195
202
  }
196
203
  }
197
204
 
198
- module.exports = { isObject, stringList, assign, makeMergeHelpers }
205
+ // Keys no provider reads any more. The merge already ignores them, as it does
206
+ // every unknown key — so a config still carrying one is a stale file, not a
207
+ // broken one, and `doctor` says so as a `warn` without touching the exit code.
208
+ //
209
+ // WHAT WOULD FOOL THIS: it reads the committed file, so a key set only in a
210
+ // working-tree edit is still reported — which is the file a person would edit.
211
+ const RETIRED_KEYS = Object.freeze([
212
+ { path: ['releases'], name: 'releases' },
213
+ { path: ['release', 'stages'], name: 'release.stages' },
214
+ ])
215
+
216
+ // The retired keys present in a parsed config. Not an object, or none present,
217
+ // is `[]`: nothing to say is the safe answer to every cannot-tell.
218
+ function retiredKeys(parsed) {
219
+ if (!isObject(parsed)) return []
220
+ return RETIRED_KEYS.filter(({ path }) => {
221
+ let node = parsed
222
+ for (const key of path) {
223
+ if (!isObject(node) || !(key in node)) return false
224
+ node = node[key]
225
+ }
226
+ return true
227
+ }).map((k) => k.name)
228
+ }
229
+
230
+ // A doctor row naming the retired keys in the config at `file`, or null when
231
+ // there are none — or when the file cannot be read or parsed, which is the
232
+ // loader's to report, not this row's.
233
+ function retiredKeysRow(file, configFile, row) {
234
+ let parsed = null
235
+ try {
236
+ parsed = JSON.parse(require('node:fs').readFileSync(file, 'utf-8'))
237
+ } catch {
238
+ return null
239
+ }
240
+ const names = retiredKeys(parsed)
241
+ if (!names.length) return null
242
+ return row(
243
+ 'retired',
244
+ 'Retired config',
245
+ 'warn',
246
+ `${names.join(', ')} in ${configFile} is no longer read — release and deploy state is the host project's to write (see \`spec-sync released --json\`)`,
247
+ `remove ${names.join(', ')} from ${configFile}`,
248
+ )
249
+ }
250
+
251
+ module.exports = { isObject, stringList, assign, makeMergeHelpers, retiredKeys, retiredKeysRow, RETIRED_KEYS }
@@ -0,0 +1,71 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * `spec-sync list --mine | --by <user>` — whose tickets to list.
5
+ *
6
+ * Linear defined the contract (`linear/src/cli-sync.js`, decision 9 of
7
+ * `feat-linear-assignment`); this is the same contract for every provider that
8
+ * lists over the API, so the two sentences below mean the same thing anywhere:
9
+ *
10
+ * - `--mine` with an UNKNOWN identity lists nothing and exits 0. Identity is
11
+ * an ordinary unknown (a bot token, an offline machine). What must never
12
+ * happen is dropping the filter and printing everyone's work under a
13
+ * heading that promised yours.
14
+ * - `--by` that matches nobody, or more than one person, exits 1. The
15
+ * argument is wrong and only the caller can fix it — the same shape as an
16
+ * unknown `--state` — and a fallback to everyone would be the same lie.
17
+ *
18
+ * Returns `{ assignee: { id, name } | null }` to carry on with, or
19
+ * `{ code, lines }` to print and stop.
20
+ */
21
+ async function resolveListAssignee({ flags, config, env, adapter, resolveIdentity, displayNameOf, tracker, prog }) {
22
+ if (flags.mine && flags.by) {
23
+ return {
24
+ code: 1,
25
+ lines: [
26
+ `${prog} list: --mine and --by both filter by assignee, so they cannot be combined`,
27
+ ' use --mine for your own, or --by <user> for someone else.',
28
+ ],
29
+ }
30
+ }
31
+ if (flags.mine) {
32
+ const who = await resolveIdentity(config, env, { adapter })
33
+ if (!who || !who.ok) {
34
+ return {
35
+ code: 0,
36
+ lines: [
37
+ `${prog} list: --mine needs to know who you are, and it does not (${(who && who.reason) || 'no identity'})`,
38
+ ' run `spec-sync whoami --set <id>` to say so, or use --by <user>.',
39
+ ],
40
+ }
41
+ }
42
+ return { assignee: { id: who.id, name: who.name || who.id } }
43
+ }
44
+ if (flags.by) {
45
+ const term = String(flags.by)
46
+ let found
47
+ try {
48
+ found = await adapter.searchUsers(term, { limit: 50 })
49
+ } catch (error) {
50
+ return { code: 1, lines: [`${prog} list: could not search users (${error.message})`] }
51
+ }
52
+ const users = (found && found.users) || []
53
+ if (!users.length) {
54
+ return {
55
+ code: 1,
56
+ lines: [`${prog} list: no ${tracker} user matches ${JSON.stringify(term)}`, ' `spec-sync users <term>` lists who there is.'],
57
+ }
58
+ }
59
+ if (users.length > 1) {
60
+ const lines = [`${prog} list: ${users.length} users match ${JSON.stringify(term)}`]
61
+ for (const u of users.slice(0, 10)) lines.push(` ${displayNameOf(u) || '(unnamed)'}${u.email ? ` ${u.email}` : ''}`)
62
+ if (users.length > 10) lines.push(` … and ${users.length - 10} more`)
63
+ lines.push(' narrow it — an email address matches exactly one person.')
64
+ return { code: 1, lines }
65
+ }
66
+ return { assignee: { id: users[0].id, name: displayNameOf(users[0]) || users[0].id } }
67
+ }
68
+ return { assignee: null }
69
+ }
70
+
71
+ module.exports = { resolveListAssignee }
@@ -0,0 +1,35 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Shared pieces of `spec-sync list`: what `--state` means, and how a row's
5
+ * board state and its spec's own status are put side by side.
6
+ */
7
+
8
+ const { remoteStateReading, stateNamesFor, LIFECYCLE_BUCKETS } = require('../../sync-core')
9
+
10
+ // `--state` takes a lifecycle bucket as well as a tracker state. A bucket
11
+ // expands to every tracker name it has (`stateNamesFor`, aliases included); any
12
+ // other value is a tracker state, matched as it always was.
13
+ function expandStateArgs(args, config) {
14
+ return (args || []).flatMap((arg) => (LIFECYCLE_BUCKETS.includes(arg) ? stateNamesFor(arg, config) : [arg]))
15
+ }
16
+
17
+ // The spec's status beside the board's, and whether they disagree. A board
18
+ // state that maps to no bucket never disagrees: it is somewhere push does not
19
+ // manage, which is not a claim about the spec. Nor does a row whose spec is not
20
+ // on this machine — there is nothing to disagree WITH.
21
+ function specColumn(stateName, spec, config) {
22
+ const specStatus = spec ? spec.bucket : null
23
+ const seen = stateName == null ? null : remoteStateReading({ state: { name: stateName } }, config)
24
+ const disagrees = Boolean(specStatus && seen && seen.mapped && seen.bucket !== specStatus)
25
+ return { specStatus, disagrees }
26
+ }
27
+
28
+ // The cell itself: `in-progress`, `≠ backlog` when it disagrees, `—` when the
29
+ // spec is not here.
30
+ function specCell({ specStatus, disagrees }) {
31
+ if (!specStatus) return '—'
32
+ return disagrees ? `≠ ${specStatus}` : specStatus
33
+ }
34
+
35
+ module.exports = { expandStateArgs, specColumn, specCell }
@@ -24,7 +24,7 @@ const IDENTIFIER_RE = /\b[A-Z][A-Z0-9]*-\d+\b/g
24
24
  // how `owner/repo#123` names ANOTHER repo's issue. Prose is excluded by the
25
25
  // trailer anchor (only a `Refs:` line is scanned); the cross-repo form is
26
26
  // excluded by the lookbehind, so a ref into some other repo never lands on this
27
- // one's release — the GitHub twin of `partitionStageMoves`' foreign team key.
27
+ // one's release.
28
28
  const GITHUB_REF_RE = /(?<![\w/.-])#\d+\b/g
29
29
  // A `Refs:` trailer line. Anchored, so it is a line of its own — never prose
30
30
  // that happens to mention the word.
@@ -175,95 +175,45 @@ function ticketsInRange(commits, options = {}) {
175
175
  }
176
176
 
177
177
  /**
178
- * Split a release's tickets into the ones a stage move may touch and the ones it
179
- * must not, with a reason for every exclusion.
178
+ * Name the spec behind each ticket a range contains, so a consumer can act on
179
+ * a release without a second lookup.
180
180
  *
181
- * Three reasons to leave a ticket alone, and each is a case where acting would
182
- * be worse than not acting:
181
+ * A ref no spec has stamped keeps `spec: null` and `url: null` — never a guess
182
+ * from a similar folder name. It may be tracker-only work, or a typo in a
183
+ * trailer, and a consumer acting on an invented match is worse than one told
184
+ * there was none.
183
185
  *
184
- * - **foreign** — the ref is not this repo's team. A range can carry another
185
- * team's ref (a shared dependency, a quoted ticket), and writing to a team
186
- * this repo was never configured for is the worst failure available here.
187
- * - **unlinked** — the ref is this team's, but no spec in the repo claims it.
188
- * It may be tracker-only work, or a typo in a trailer. Either way nothing
189
- * here knows what it is, so it is reported, not moved.
190
- * - **unfinished** — a spec that has not reached the ceded bucket. Its code
191
- * really is in the release (it landed via `/spec-to-main`), but push still
192
- * owns its workflow state and would bounce it straight back. Exactly one
193
- * writer per issue at any moment beats a visible flip-flop.
194
- *
195
- * Pure: it takes the spec list as data, so the rules are testable without a repo.
186
+ * Pure: it takes the spec list as data (`listSpecs` rows), so it is testable
187
+ * without a repo.
196
188
  */
197
- function partitionStageMoves({ tickets, teamKey, specs, cededBucket = 'complete' }) {
198
- const bucketOf = new Map()
199
- for (const spec of specs || []) {
200
- if (spec && spec.identifier) bucketOf.set(spec.identifier, spec.bucket)
201
- }
202
- const key = String(teamKey || '').trim().toUpperCase()
203
- const movable = []
204
- const foreign = []
205
- const unlinked = []
206
- const unfinished = []
207
- for (const ticket of tickets || []) {
208
- const ref = ticket && ticket.ref
209
- if (!ref) continue
210
- if (key && !ref.toUpperCase().startsWith(`${key}-`)) {
211
- foreign.push(ticket)
212
- } else if (!bucketOf.has(ref)) {
213
- unlinked.push(ticket)
214
- } else if (bucketOf.get(ref) !== cededBucket) {
215
- unfinished.push({ ...ticket, bucket: bucketOf.get(ref) })
216
- } else {
217
- movable.push(ticket)
218
- }
189
+ function nameTickets(tickets, specs) {
190
+ const byRef = new Map()
191
+ for (const s of specs || []) {
192
+ if (s && s.identifier && !byRef.has(s.identifier)) byRef.set(s.identifier, s)
219
193
  }
220
- return { movable, foreign, unlinked, unfinished }
194
+ return (tickets || []).map((t) => {
195
+ const s = byRef.get(t.ref)
196
+ return { ...t, spec: s ? s.spec : null, url: s ? s.url || null : null }
197
+ })
221
198
  }
222
199
 
223
- /**
224
- * Whether moving from `fromState` to the rung `toKey` runs against the declared
225
- * order — and if so, how to say it.
226
- *
227
- * WARNS, never refuses. A rollback from test and a hotfix going straight to prod
228
- * are both legitimate, and a check that blocked either would be wrong on healthy
229
- * input. An issue that is on no rung yet is entering the ladder, which is the
230
- * normal case and says nothing.
231
- *
232
- * `lifecycleStates` is the bucket map's own state names, and a state among them
233
- * means the issue is at its LIFECYCLE position, not on a rung — even when the
234
- * two names coincide. They routinely do: `states.complete` and a final `prod`
235
- * rung are both naturally "Done", and without this a spec that had merely been
236
- * completed would read as already deployed to prod, so its first real deploy
237
- * would be warned about as a move backwards. Bucket wins over ladder here for
238
- * the same reason it wins in `bucketForState`.
239
- *
240
- * @returns {string|null}
241
- */
242
- function stageOrderWarning(stages, fromState, toKey, lifecycleStates = []) {
243
- const list = Array.isArray(stages) ? stages : []
244
- const to = list.findIndex((s) => s && s.key === toKey)
245
- if (to < 0) return null
246
- const want = String(fromState || '').toLowerCase().trim()
247
- if (!want) return null
248
- const lifecycle = new Set(
249
- (Array.isArray(lifecycleStates) ? lifecycleStates : [])
250
- .filter((n) => typeof n === 'string')
251
- .map((n) => n.toLowerCase().trim()),
200
+ // The answer a removed release verb gives (`release`, `stage`). Exit 1, not a
201
+ // quiet 0: a pipeline still calling one must learn it no longer mirrors
202
+ // anything, rather than go on believing it does.
203
+ function refuseRemovedVerb(out, program, verb) {
204
+ out.write(
205
+ `${program} ${verb}: removed — skitterspec no longer writes release or deploy state; ` +
206
+ `\`${program} released <range> --json\` lists the tickets a range contains, for your own tooling to act on\n`,
252
207
  )
253
- if (lifecycle.has(want)) return null
254
- const from = list.findIndex((s) => s && typeof s.state === 'string' && s.state.toLowerCase().trim() === want)
255
- if (from < 0) return null
256
- if (to < from) return `moves back from "${list[from].key}"`
257
- if (to > from + 1) return `skips ${to - from - 1} rung(s) from "${list[from].key}"`
258
- return null
208
+ return 1
259
209
  }
260
210
 
261
211
  module.exports = {
262
212
  ticketsInRange,
213
+ refuseRemovedVerb,
214
+ nameTickets,
263
215
  refsInBody,
264
216
  onlyIgnoredPaths,
265
- partitionStageMoves,
266
- stageOrderWarning,
267
217
  IDENTIFIER_RE,
268
218
  GITHUB_REF_RE,
269
219
  }
@@ -14,7 +14,16 @@
14
14
  const fs = require('node:fs')
15
15
  const path = require('node:path')
16
16
 
17
- const { BUCKETS, findSpecFolder } = require('../../../env/resolve.js')
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
- const field = fieldsOf(config).identifier
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 data[field] ? String(data[field]) : null
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
- specs.push({ spec: name, bucket, identifier: linkedIdentifier(overviewPath, config) })
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, titleFromText, validateStates, stateSuggestions, stageForState, remoteStage, phaseModeFor, LADDER_ORIGIN_BUCKET } = require('./src/normalize.js')
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,