@skitterbyte/skitterspec-linear 19.14.0 → 19.16.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/README.md +2 -0
- package/assets/claude-md-section.md +12 -0
- package/assets/core/env.config.md +25 -3
- package/assets/hooks/main-guard.cjs +73 -6
- package/assets/hooks/project-guard.cjs +80 -6
- package/assets/hooks/review-gate.cjs +73 -6
- package/assets/review/page.html +2 -1
- package/assets/rules/commit-trailers.md +2 -2
- package/assets/rules/offered-unblocks.md +22 -0
- package/assets/rules/spec-planning.md +12 -1
- package/assets/skills/no-spec/SKILL.md +5 -0
- package/assets/skills/spec/SKILL.md +20 -3
- package/assets/skills/spec-bug/SKILL.md +8 -2
- package/assets/skills/spec-complete/SKILL.md +28 -2
- package/assets/skills/spec-diff/SKILL.md +5 -0
- package/assets/skills/spec-hotfix/SKILL.md +8 -2
- package/assets/skills/spec-idea/SKILL.md +5 -0
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-next/SKILL.md +18 -0
- package/assets/skills/spec-park/SKILL.md +92 -0
- package/assets/skills/spec-resume/SKILL.md +153 -0
- package/assets/skills/spec-start/SKILL.md +6 -2
- package/assets/skills/spec-status/SKILL.md +1 -1
- package/assets/skills/spec-sync/SKILL.md +12 -12
- package/assets/skills/spec-to-main/SKILL.md +5 -1
- package/assets/skills/spec-todo/SKILL.md +5 -2
- package/package.json +1 -1
- package/src/cli.js +311 -15
- package/src/env/base.js +21 -5
- package/src/env/basepin.js +62 -0
- package/src/env/bootstrap.js +3 -1
- package/src/env/checks.js +49 -0
- package/src/env/config.js +48 -1
- package/src/env/hooks.js +53 -4
- package/src/env/provision.js +10 -2
- package/src/env/resolve.js +66 -13
- package/src/env/resume.js +234 -0
- package/src/env/review.js +4 -1
- package/src/env/serve.js +3 -0
- package/src/ideacmd.js +11 -1
- package/src/init.js +287 -49
- package/src/tada/todo.js +19 -4
- package/src/vendor/linear/cli-sync.js +3 -3
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Going back into a spec that is already in flight (feat-spec-resume) — the
|
|
5
|
+
* engine behind `skitterspec spec-env resume <name|#N>`.
|
|
6
|
+
*
|
|
7
|
+
* A spec that waits on something outside the repo — a deploy, another
|
|
8
|
+
* project's release, a soak period — is left and come back to. Coming back is
|
|
9
|
+
* not starting: nothing here moves a bucket, assigns anyone or touches a
|
|
10
|
+
* tracker. It answers three things, and the skill acts on them:
|
|
11
|
+
*
|
|
12
|
+
* - which spec the argument means (a folder name, or a tracker ref read off
|
|
13
|
+
* each copy's frontmatter through `branch.identifierField`),
|
|
14
|
+
* - whether it can be resumed (only `in-progress` — read from the spec's OWN
|
|
15
|
+
* copy, since the base branch goes on reading `backlog` for the life of a
|
|
16
|
+
* spec), and how to rebuild its worktree when this machine has none,
|
|
17
|
+
* - what it is blocked on (`> **Blocked on:**`, on the overview or a phase).
|
|
18
|
+
*
|
|
19
|
+
* Pure: callers hand in the copies they could read and whether the worktree
|
|
20
|
+
* and branches exist. `cli.js` does the reading.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const { phaseProgress } = require('./phases.js')
|
|
24
|
+
const { shellPath } = require('./project.js')
|
|
25
|
+
|
|
26
|
+
// Same grammar as `specstate.js`'s header(): a blockquote `**Field:**` line.
|
|
27
|
+
function headerValue(text, field) {
|
|
28
|
+
const m = new RegExp(`^>\\s*\\*\\*${field}:\\*\\*[ \\t]*(.*)$`, 'm').exec(String(text || ''))
|
|
29
|
+
if (!m) return null
|
|
30
|
+
const value = m[1].trim()
|
|
31
|
+
return value && value !== '—' && value !== '-' ? value : null
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// A real calendar date, or null. `2026-02-31` is not one, and a malformed
|
|
35
|
+
// `until` must stay text rather than become a date someone acts on.
|
|
36
|
+
function calendarDate(s) {
|
|
37
|
+
if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return null
|
|
38
|
+
const d = new Date(`${s}T00:00:00Z`)
|
|
39
|
+
return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s ? s : null
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* One `Blocked on:` value → `{ text, until }`. A trailing `(until YYYY-MM-DD)`
|
|
44
|
+
* is the only part read as data; anything else — including an `until` that is
|
|
45
|
+
* not a real date — stays in `text`, so a typo is shown rather than obeyed.
|
|
46
|
+
*/
|
|
47
|
+
function parseBlockedOn(value) {
|
|
48
|
+
if (!value) return null
|
|
49
|
+
const m = /^(.*?)\s*\(until\s+([^)]*)\)\s*$/.exec(value)
|
|
50
|
+
const until = m ? calendarDate(m[2].trim()) : null
|
|
51
|
+
return until ? { text: m[1].trim() || value, until } : { text: value, until: null }
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Every blocker a spec records: the overview's (`where: 'spec'`), then each
|
|
56
|
+
* phase file's (`where: <phase number>`), in phase order.
|
|
57
|
+
*
|
|
58
|
+
* @param {{ overview: string, phases?: Array<{ n: number, text: string }> }} copy
|
|
59
|
+
* @returns {Array<{ where: 'spec'|number, text: string, until: string|null }>}
|
|
60
|
+
*/
|
|
61
|
+
function blockers(copy) {
|
|
62
|
+
const out = []
|
|
63
|
+
const spec = parseBlockedOn(headerValue(copy && copy.overview, 'Blocked on'))
|
|
64
|
+
if (spec) out.push({ where: 'spec', ...spec })
|
|
65
|
+
const phases = ((copy && copy.phases) || []).filter((p) => p && typeof p.text === 'string')
|
|
66
|
+
for (const p of [...phases].sort((a, b) => a.n - b.n)) {
|
|
67
|
+
const b = parseBlockedOn(headerValue(p.text, 'Blocked on'))
|
|
68
|
+
if (b) out.push({ where: p.n, ...b })
|
|
69
|
+
}
|
|
70
|
+
return out
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The blocker that stands in front of the NEXT build, or null.
|
|
75
|
+
*
|
|
76
|
+
* The next build is the first phase not `✅` — the one `/spec-next` would
|
|
77
|
+
* pick. A spec-level blocker holds every phase; a phase's own holds only that
|
|
78
|
+
* phase. A blocker on a LATER phase is not this build's business and says
|
|
79
|
+
* nothing: a spec planned to wait at phase 4 builds phases 1–3 unhindered.
|
|
80
|
+
* Nothing left to build means nothing to block.
|
|
81
|
+
*/
|
|
82
|
+
function blockingNext(copy) {
|
|
83
|
+
const all = blockers(copy)
|
|
84
|
+
const phases = ((copy && copy.phases) || []).filter((p) => p && typeof p.text === 'string')
|
|
85
|
+
const heading = (t) => (t.split('\n').find((l) => /^#\s/.test(l)) || '').trim()
|
|
86
|
+
const next = [...phases].sort((a, b) => a.n - b.n).find((p) => !heading(p.text).endsWith('✅'))
|
|
87
|
+
if (!next) return null
|
|
88
|
+
return all.find((b) => b.where === 'spec') || all.find((b) => b.where === next.n) || null
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// A frontmatter field off an overview's text — the in-memory twin of
|
|
92
|
+
// resolve.js `readFrontmatterField`, for copies read off a branch.
|
|
93
|
+
function frontmatterField(text, field) {
|
|
94
|
+
if (!field) return null
|
|
95
|
+
const fm = /^---\n([\s\S]*?)\n---/.exec(String(text || ''))
|
|
96
|
+
if (!fm) return null
|
|
97
|
+
const m = new RegExp(`^${field}:\\s*(.+)$`, 'm').exec(fm[1])
|
|
98
|
+
return m ? m[1].trim().replace(/^["']|["']$/g, '') || null : null
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// `#241`, `241` and `"#241"` are one ticket; `ABC-88` only ever matches itself.
|
|
102
|
+
function sameRef(a, b) {
|
|
103
|
+
const norm = (s) => String(s).trim().replace(/^#/, '').toLowerCase()
|
|
104
|
+
return Boolean(a) && Boolean(b) && norm(a) === norm(b)
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// Which copy speaks for a spec: its own worktree, then a branch (local before
|
|
108
|
+
// remote-tracking), then the checkout the command was run from.
|
|
109
|
+
const RANK = { worktree: 0, branch: 1, here: 2 }
|
|
110
|
+
function rank(c) {
|
|
111
|
+
return RANK[c.origin] * 2 + (c.origin === 'branch' && !c.local ? 1 : 0)
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* The copy an argument means, or a refusal.
|
|
116
|
+
*
|
|
117
|
+
* A FOLDER NAME WINS OVER A REF. Folder names carry a kind prefix
|
|
118
|
+
* (`feat-`, `bug-`…) and tracker refs do not, so the two cannot collide in
|
|
119
|
+
* practice — but if one ever did, the name someone typed for a folder is the
|
|
120
|
+
* more specific claim.
|
|
121
|
+
*
|
|
122
|
+
* A REF THAT MATCHES NOTHING NAMES NOTHING. It never falls back to the nearest
|
|
123
|
+
* spec or the only one provisioned: resuming the wrong spec writes into a
|
|
124
|
+
* branch nobody asked about. Without `branch.identifierField` a ref cannot be
|
|
125
|
+
* read at all, and the refusal says that rather than "not found".
|
|
126
|
+
*
|
|
127
|
+
* @param {string} arg
|
|
128
|
+
* @param {Array<{ folder, bucket, origin: 'worktree'|'branch'|'here', local?, ref?, overview, phases }>} copies
|
|
129
|
+
* @param {string} [identifierField]
|
|
130
|
+
*/
|
|
131
|
+
function findTarget(arg, copies, identifierField) {
|
|
132
|
+
const wanted = String(arg || '').trim()
|
|
133
|
+
if (!wanted) return { refused: 'no spec given — /spec-resume <name> or /spec-resume #<ticket>' }
|
|
134
|
+
const best = (list) => [...list].sort((a, b) => rank(a) - rank(b))[0]
|
|
135
|
+
const byName = copies.filter((c) => c.folder === wanted)
|
|
136
|
+
if (byName.length) return { target: best(byName), by: 'name' }
|
|
137
|
+
|
|
138
|
+
if (!identifierField) {
|
|
139
|
+
return {
|
|
140
|
+
refused:
|
|
141
|
+
`no spec named ${wanted}` +
|
|
142
|
+
(/^#?[\w-]*\d+$/.test(wanted)
|
|
143
|
+
? ', and a ticket ref cannot be looked up: branch.identifierField is not set in env.config.json'
|
|
144
|
+
: ''),
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
const byRef = copies.filter((c) => sameRef(frontmatterField(c.overview, identifierField), wanted))
|
|
148
|
+
const folders = [...new Set(byRef.map((c) => c.folder))]
|
|
149
|
+
if (!folders.length) return { refused: `no spec named or linked to ${wanted}` }
|
|
150
|
+
if (folders.length > 1) {
|
|
151
|
+
return { refused: `${wanted} is linked from more than one spec (${folders.join(', ')}) — name the one you mean` }
|
|
152
|
+
}
|
|
153
|
+
return { target: best(byRef), by: 'ref' }
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* The full answer for a found copy.
|
|
158
|
+
*
|
|
159
|
+
* @param {object} target the copy `findTarget` chose
|
|
160
|
+
* @param {object} env what the caller could see:
|
|
161
|
+
* `{ branch, worktreePath, worktreeExists, localBranch, remoteBranch, remote, identifierField }`
|
|
162
|
+
*/
|
|
163
|
+
function planResume(target, env) {
|
|
164
|
+
const progress = phaseProgress((target.phases || []).map((p) => ({ content: p.text })))
|
|
165
|
+
const base = {
|
|
166
|
+
spec: target.folder,
|
|
167
|
+
bucket: target.bucket,
|
|
168
|
+
source: target.origin,
|
|
169
|
+
branch: env.branch,
|
|
170
|
+
identifier: frontmatterField(target.overview, env.identifierField),
|
|
171
|
+
progress: { done: progress.done, total: progress.total, current: progress.current },
|
|
172
|
+
blockers: blockers(target),
|
|
173
|
+
blocking: blockingNext(target),
|
|
174
|
+
worktree: { path: env.worktreePath, present: Boolean(env.worktreeExists) },
|
|
175
|
+
}
|
|
176
|
+
if (target.bucket !== 'in-progress') {
|
|
177
|
+
const how =
|
|
178
|
+
target.bucket === 'backlog'
|
|
179
|
+
? ' — it was never started; /spec-start puts it in flight'
|
|
180
|
+
: ' — there is nothing left to resume'
|
|
181
|
+
return { ok: false, ...base, refused: `${target.folder} is in ${target.bucket}${how}` }
|
|
182
|
+
}
|
|
183
|
+
if (env.worktreeExists) return { ok: true, ...base, commands: [], then: [] }
|
|
184
|
+
|
|
185
|
+
// NEVER `-b` WITHOUT A BRANCH TO ATTACH. A fresh fork from base would hand
|
|
186
|
+
// back an empty tree with the spec's work out of reach — that is a start,
|
|
187
|
+
// and starting is /spec-start's. So: the local branch, else the remote's,
|
|
188
|
+
// else a refusal.
|
|
189
|
+
let commands
|
|
190
|
+
if (env.localBranch) {
|
|
191
|
+
commands = [`git worktree add ${shellPath(env.worktreePath)} ${env.branch}`]
|
|
192
|
+
} else if (env.remoteBranch) {
|
|
193
|
+
commands = [
|
|
194
|
+
`git fetch ${env.remote} ${env.branch}`,
|
|
195
|
+
`git worktree add ${shellPath(env.worktreePath)} -b ${env.branch} --track ${env.remote}/${env.branch}`,
|
|
196
|
+
]
|
|
197
|
+
} else {
|
|
198
|
+
return {
|
|
199
|
+
ok: false,
|
|
200
|
+
...base,
|
|
201
|
+
refused: `${target.folder} has no worktree and no ${env.branch} branch here or on ${env.remote} — nothing to resume from`,
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
return { ok: true, ...base, commands, then: [`skitterspec spec-env bootstrap ${target.folder}`] }
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
function blockerLine(b) {
|
|
208
|
+
const where = b.where === 'spec' ? 'spec' : `phase ${b.where}`
|
|
209
|
+
return `${where} — ${b.text}${b.until ? ` (until ${b.until})` : ''}`
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** The text report — what `spec-env resume` prints without `--json`. */
|
|
213
|
+
function resumeLines(r) {
|
|
214
|
+
if (r.refusedOnly) return [`spec-env resume: refused — ${r.refused}`]
|
|
215
|
+
const lines = [`spec-env resume: ${r.spec} (${r.bucket}, on ${r.branch})`]
|
|
216
|
+
if (r.identifier) lines.push(` ticket: ${r.identifier}`)
|
|
217
|
+
const { done, total, current } = r.progress
|
|
218
|
+
lines.push(
|
|
219
|
+
` phases: ${total ? `${done} of ${total} done${current ? `, phase ${current} in progress` : ''}` : 'no phase files'}`,
|
|
220
|
+
)
|
|
221
|
+
for (const b of r.blockers) lines.push(` blocked: ${blockerLine(b)}${r.blocking && b.where === r.blocking.where ? ' ← holds the next build' : ''}`)
|
|
222
|
+
if (!r.ok) {
|
|
223
|
+
lines.push(` refused: ${r.refused}`)
|
|
224
|
+
return lines
|
|
225
|
+
}
|
|
226
|
+
lines.push(` worktree: ${r.worktree.path}${r.worktree.present ? '' : ' (missing — provision below)'}`)
|
|
227
|
+
if (r.commands.length) {
|
|
228
|
+
lines.push('', ' to provision, run:', ...r.commands.map((c) => ` ${c}`))
|
|
229
|
+
lines.push('', ' then, run:', ...r.then.map((c) => ` ${c}`))
|
|
230
|
+
}
|
|
231
|
+
return lines
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
module.exports = { blockers, blockingNext, parseBlockedOn, findTarget, planResume, resumeLines, blockerLine, frontmatterField, sameRef }
|
package/src/env/review.js
CHANGED
|
@@ -316,7 +316,7 @@ function readerOffMachine(reader) {
|
|
|
316
316
|
* `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
|
|
317
317
|
* caller's declaration about the work, not a reading of the gate.
|
|
318
318
|
*/
|
|
319
|
-
function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
|
|
319
|
+
function collectReview({ spec, git, mode = 'working', ref, base = null, baseGap = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
|
|
320
320
|
// WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
|
|
321
321
|
// reads the spec's worktree, and for those the two are the same path — so
|
|
322
322
|
// `treePath` left null keeps the existing behaviour exactly. The `docs` mode
|
|
@@ -424,6 +424,9 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
|
|
|
424
424
|
// "everything since main, because there was nothing uncommitted" are
|
|
425
425
|
// different answers to "what am I looking at".
|
|
426
426
|
fellBack,
|
|
427
|
+
// Set when a gap pin chose `base` (`gapNote`): the page says so beside it,
|
|
428
|
+
// because "since master" reads as a decision nobody made otherwise.
|
|
429
|
+
baseGap: base ? baseGap : null,
|
|
427
430
|
generatedAt: now,
|
|
428
431
|
// Is there a phase left for `/spec-next` to build? The page needs it to
|
|
429
432
|
// know whether offering `Commit & Continue` means anything — and it is read
|
package/src/env/serve.js
CHANGED
|
@@ -35,6 +35,7 @@ const {
|
|
|
35
35
|
allSpecs,
|
|
36
36
|
resolveSpec,
|
|
37
37
|
resolveBaseBranch,
|
|
38
|
+
gapNote,
|
|
38
39
|
isEpic,
|
|
39
40
|
} = require('./resolve.js')
|
|
40
41
|
const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
|
|
@@ -641,6 +642,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
641
642
|
mode,
|
|
642
643
|
ref,
|
|
643
644
|
base: baseName,
|
|
645
|
+
baseGap: baseName ? gapNote(config, trimmed) : null,
|
|
644
646
|
now,
|
|
645
647
|
notes,
|
|
646
648
|
gate,
|
|
@@ -664,6 +666,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
|
|
|
664
666
|
mode: 'branch',
|
|
665
667
|
ref: mergeBase,
|
|
666
668
|
base: fallbackBase,
|
|
669
|
+
baseGap: gapNote(config, trimmed),
|
|
667
670
|
now,
|
|
668
671
|
notes,
|
|
669
672
|
gate,
|
package/src/ideacmd.js
CHANGED
|
@@ -154,7 +154,17 @@ function refuse(out, flags, reason, extra = {}) {
|
|
|
154
154
|
|
|
155
155
|
async function fileStore(sub, positional, flags, { cwd, now, out }) {
|
|
156
156
|
const ctx = fileContext(cwd)
|
|
157
|
-
if (!ctx.base)
|
|
157
|
+
if (!ctx.base) {
|
|
158
|
+
// A rolling base in its gap carries the engine's offer
|
|
159
|
+
// (`.claude/rules/offered-unblocks.md`): the refusal, then the way out.
|
|
160
|
+
const offer = ctx.refused && ctx.refused.offer
|
|
161
|
+
if (!offer) return refuse(out, flags, ctx.refused ? ctx.refused.message : 'cannot resolve the base branch')
|
|
162
|
+
write(out, flags, { ok: false, refused: ctx.refused.message, offer }, [
|
|
163
|
+
`idea: ${ctx.refused.message}`,
|
|
164
|
+
` offer: ${offer.label} — ${offer.command}`,
|
|
165
|
+
])
|
|
166
|
+
return 1
|
|
167
|
+
}
|
|
158
168
|
const { tip, text } = readOnBase(ctx)
|
|
159
169
|
|
|
160
170
|
if (sub === 'list') {
|