@skitterbyte/skitterspec-linear 19.7.0 → 19.9.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 +3 -1
- package/assets/claude-md-section.md +6 -0
- package/assets/core/env.config.json.example +5 -0
- package/assets/core/env.config.md +26 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +65 -12
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +31 -14
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-complete/SKILL.md +6 -0
- package/assets/skills/spec-epic-next/SKILL.md +83 -0
- package/assets/skills/spec-init/SKILL.md +35 -3
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/assets/skills/spec-start/SKILL.md +2 -2
- package/assets/skills/spec-tada/SKILL.md +153 -0
- package/bin/skitterspec-linear.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +473 -25
- package/src/env/config.js +57 -6
- package/src/env/epic.js +69 -19
- package/src/env/epicpage.js +87 -39
- package/src/env/epicread.js +41 -3
- package/src/env/integrate.js +48 -1
- package/src/env/nextaction.js +78 -1
- package/src/env/project.js +54 -3
- package/src/env/projectedit.js +148 -0
- package/src/env/resolve.js +1 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +44 -8
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/init.js +11 -3
- package/src/tada/commits.js +145 -0
- package/src/tada/digest.js +260 -0
- package/src/tada/format.js +37 -0
- package/src/tada/page.js +213 -0
- package/src/tada/repo.js +102 -0
- package/src/tada/serve.js +127 -0
- package/src/tada/specs.js +146 -0
- package/src/tada/transcripts.js +258 -0
- package/src/tada/window.js +156 -0
- package/src/vendor/provider-kit/src/apply.js +25 -1
- package/src/vendor/sync-core/src/compare.js +10 -2
- package/src/vendor/sync-core/src/push.js +14 -3
- /package/assets/commands/{epic.md → spec-epic.md} +0 -0
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Claude Code's session transcripts, read down to what a ta-da list needs:
|
|
5
|
+
* which prompts a person typed, where they were standing (cwd + git branch),
|
|
6
|
+
* and when. Everything else — tool calls, tool results, reminders, caveats —
|
|
7
|
+
* is dropped here, so the model is handed a digest and never a transcript.
|
|
8
|
+
*
|
|
9
|
+
* WHAT WOULD FOOL THIS: the transcript format is Claude Code's, not ours, and
|
|
10
|
+
* nothing promises it stays put. A renamed field would read as a day with no
|
|
11
|
+
* activity — an absence that proves nothing. So a file touched inside the
|
|
12
|
+
* window that yields no readable entry is reported as `cannot tell`, never
|
|
13
|
+
* silently as an idle day (`.claude/rules/negative-checks.md`).
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const fs = require('node:fs')
|
|
17
|
+
const os = require('node:os')
|
|
18
|
+
const path = require('node:path')
|
|
19
|
+
const readline = require('node:readline')
|
|
20
|
+
|
|
21
|
+
// Enough to recognise a prompt, short enough that a long day stays a digest.
|
|
22
|
+
const PROMPT_CHARS = 200
|
|
23
|
+
// Per session and place: the first few say what it set out to do, the last
|
|
24
|
+
// few where it ended up. The middle is counted, not shown.
|
|
25
|
+
const KEEP_HEAD = 3
|
|
26
|
+
const KEEP_TAIL = 3
|
|
27
|
+
|
|
28
|
+
// Built-in commands that move the session around rather than do work. Kept out
|
|
29
|
+
// so a recap is not half `/clear`; a skill's command is work and stays.
|
|
30
|
+
const HOUSEKEEPING = new Set([
|
|
31
|
+
'add-dir', 'clear', 'compact', 'config', 'context', 'cost', 'doctor', 'exit', 'fast',
|
|
32
|
+
'help', 'login', 'logout', 'memory', 'model', 'permissions', 'quit', 'resume', 'status',
|
|
33
|
+
])
|
|
34
|
+
|
|
35
|
+
/** Where Claude Code keeps transcripts — `CLAUDE_CONFIG_DIR` moves it. */
|
|
36
|
+
function defaultRoot(env = process.env) {
|
|
37
|
+
const base = env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude')
|
|
38
|
+
return path.join(base, 'projects')
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Every `<root>/<project>/<session>.jsonl` modified at or after `since`. A file
|
|
43
|
+
* last written before the window opened cannot hold an entry inside it, so
|
|
44
|
+
* this is a skip and not a guess. Subagent transcripts live a level deeper and
|
|
45
|
+
* are deliberately not read: their prompts were written by Claude, not typed.
|
|
46
|
+
*/
|
|
47
|
+
function listTranscripts(root, since) {
|
|
48
|
+
let projects
|
|
49
|
+
try {
|
|
50
|
+
projects = fs.readdirSync(root, { withFileTypes: true })
|
|
51
|
+
} catch {
|
|
52
|
+
return []
|
|
53
|
+
}
|
|
54
|
+
const out = []
|
|
55
|
+
for (const p of projects) {
|
|
56
|
+
if (!p.isDirectory()) continue
|
|
57
|
+
const dir = path.join(root, p.name)
|
|
58
|
+
let files
|
|
59
|
+
try {
|
|
60
|
+
files = fs.readdirSync(dir)
|
|
61
|
+
} catch {
|
|
62
|
+
continue
|
|
63
|
+
}
|
|
64
|
+
for (const f of files) {
|
|
65
|
+
if (!f.endsWith('.jsonl')) continue
|
|
66
|
+
const file = path.join(dir, f)
|
|
67
|
+
let stat
|
|
68
|
+
try {
|
|
69
|
+
stat = fs.statSync(file)
|
|
70
|
+
} catch {
|
|
71
|
+
continue
|
|
72
|
+
}
|
|
73
|
+
if (stat.isFile() && stat.mtime >= since) out.push(file)
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
return out.sort()
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* What a user entry says, reduced to one of:
|
|
81
|
+
* { text } a prompt someone typed
|
|
82
|
+
* { command, text } a slash command, kept as an event (`/spec-next`)
|
|
83
|
+
* null noise — dropped
|
|
84
|
+
*/
|
|
85
|
+
function readPrompt(content) {
|
|
86
|
+
if (typeof content !== 'string') return null // tool results, images
|
|
87
|
+
const s = content.trim()
|
|
88
|
+
if (!s) return null
|
|
89
|
+
const name = /<command-name>\s*([^<\s]+)\s*<\/command-name>/.exec(s)
|
|
90
|
+
if (name) {
|
|
91
|
+
const args = /<command-args>([\s\S]*?)<\/command-args>/.exec(s)
|
|
92
|
+
const command = name[1].startsWith('/') ? name[1] : `/${name[1]}`
|
|
93
|
+
if (HOUSEKEEPING.has(command.slice(1))) return null
|
|
94
|
+
return { command, text: cap(args ? args[1].trim() : '') }
|
|
95
|
+
}
|
|
96
|
+
// Caveats, command output, reminders, task notifications, a bare paste:
|
|
97
|
+
// all arrive as a tagged block, and none of them is something typed.
|
|
98
|
+
if (s.startsWith('<')) return null
|
|
99
|
+
// "[Request interrupted by user]" and its kind.
|
|
100
|
+
if (s.startsWith('[') && s.endsWith(']')) return null
|
|
101
|
+
return { text: cap(s) }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
function cap(s) {
|
|
105
|
+
const one = s.replace(/\s+/g, ' ').trim()
|
|
106
|
+
return one.length > PROMPT_CHARS ? `${one.slice(0, PROMPT_CHARS - 1)}…` : one
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* One transcript, read inside the window. Prompts are attributed to where the
|
|
111
|
+
* session stood when they were typed — a session that `cd`s into a worktree
|
|
112
|
+
* half-way through contributes to two places, which is the point.
|
|
113
|
+
*
|
|
114
|
+
* @returns {Promise<{ id, stamped: number, places: Array<{ cwd, branch,
|
|
115
|
+
* start, end, prompts: Array<{ at, text, command? }> }> }>}
|
|
116
|
+
*/
|
|
117
|
+
async function readSession(file, { since, until }) {
|
|
118
|
+
const id = path.basename(file, '.jsonl')
|
|
119
|
+
const places = new Map()
|
|
120
|
+
let cwd = null
|
|
121
|
+
let branch = null
|
|
122
|
+
// Entries carrying a timestamp we could parse, inside the window or not —
|
|
123
|
+
// the positive signal that this is still a format we can read.
|
|
124
|
+
let stamped = 0
|
|
125
|
+
|
|
126
|
+
const rl = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity })
|
|
127
|
+
for await (const line of rl) {
|
|
128
|
+
if (!line) continue
|
|
129
|
+
let e
|
|
130
|
+
try {
|
|
131
|
+
e = JSON.parse(line)
|
|
132
|
+
} catch {
|
|
133
|
+
continue // a half-written last line, or not ours to read
|
|
134
|
+
}
|
|
135
|
+
// Where the session stands is tracked from every entry, so a `cd` made by
|
|
136
|
+
// a tool call moves the prompts that follow it.
|
|
137
|
+
if (typeof e.cwd === 'string') cwd = e.cwd
|
|
138
|
+
if (typeof e.gitBranch === 'string' && e.gitBranch) branch = e.gitBranch
|
|
139
|
+
const at = Date.parse(e.timestamp)
|
|
140
|
+
if (Number.isNaN(at)) continue
|
|
141
|
+
stamped++
|
|
142
|
+
if (at < since.getTime() || at > until.getTime()) continue
|
|
143
|
+
// A compaction summary arrives as a user entry, written by Claude.
|
|
144
|
+
if (e.type !== 'user' || e.isMeta || e.isSidechain || e.isCompactSummary) continue
|
|
145
|
+
const p = readPrompt(e.message && e.message.content)
|
|
146
|
+
if (!p || !cwd) continue
|
|
147
|
+
const key = `${cwd}\0${branch || ''}`
|
|
148
|
+
if (!places.has(key)) places.set(key, { cwd, branch, start: e.timestamp, end: e.timestamp, prompts: [] })
|
|
149
|
+
const place = places.get(key)
|
|
150
|
+
place.end = e.timestamp
|
|
151
|
+
place.prompts.push({ at: e.timestamp, ...p })
|
|
152
|
+
}
|
|
153
|
+
return { id, stamped, launch: launchDir(path.basename(path.dirname(file))), places: [...places.values()] }
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* The directory a session was launched from, read back off its transcript
|
|
158
|
+
* folder's name — Claude Code writes `/Users/me/code/app` as
|
|
159
|
+
* `-Users-me-code-app`, flattening `/` and `.` alike to `-`.
|
|
160
|
+
*
|
|
161
|
+
* That flattening is lossy (`my-app` and `my/app` encode the same), so this
|
|
162
|
+
* decodes only by asking the disk: each `-` is tried as a separator and as a
|
|
163
|
+
* literal, keeping the spellings that exist. More than one survivor, or none,
|
|
164
|
+
* is cannot-tell and returns null — a guessed directory would fold a session
|
|
165
|
+
* into the wrong repo with nothing to show for it.
|
|
166
|
+
*/
|
|
167
|
+
function launchDir(name, existsOnDisk = fs.existsSync) {
|
|
168
|
+
if (!name.startsWith('-')) return null
|
|
169
|
+
const parts = name.slice(1).split('-')
|
|
170
|
+
// Each `-` has three readings, so the search is exponential in their count;
|
|
171
|
+
// past this many it is cannot-tell rather than a stall.
|
|
172
|
+
if (parts.length > 16) return null
|
|
173
|
+
const seen = new Map()
|
|
174
|
+
const exists = (p) => {
|
|
175
|
+
if (!seen.has(p)) seen.set(p, existsOnDisk(p))
|
|
176
|
+
return seen.get(p)
|
|
177
|
+
}
|
|
178
|
+
const found = []
|
|
179
|
+
const walk = (i, at, seg) => {
|
|
180
|
+
if (found.length > 1) return
|
|
181
|
+
if (i === parts.length) {
|
|
182
|
+
const full = path.join(at, seg)
|
|
183
|
+
if (exists(full)) found.push(full)
|
|
184
|
+
return
|
|
185
|
+
}
|
|
186
|
+
const next = parts[i]
|
|
187
|
+
// Close the segment here, if what it names exists so far.
|
|
188
|
+
if (seg && exists(path.join(at, seg))) walk(i + 1, path.join(at, seg), next)
|
|
189
|
+
// Or keep it open, through a literal `-` or a `.` (a dotfile, `app.web`).
|
|
190
|
+
if (seg !== '') {
|
|
191
|
+
walk(i + 1, at, `${seg}-${next}`)
|
|
192
|
+
walk(i + 1, at, `${seg}.${next}`)
|
|
193
|
+
} else {
|
|
194
|
+
walk(i + 1, at, `.${next}`)
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
walk(1, path.sep, parts[0])
|
|
198
|
+
return found.length === 1 ? found[0] : null
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** First and last few prompts, with the middle counted rather than shown. */
|
|
202
|
+
function trimPrompts(prompts) {
|
|
203
|
+
if (prompts.length <= KEEP_HEAD + KEEP_TAIL) return { prompts, omitted: 0 }
|
|
204
|
+
return {
|
|
205
|
+
prompts: [...prompts.slice(0, KEEP_HEAD), ...prompts.slice(-KEEP_TAIL)],
|
|
206
|
+
omitted: prompts.length - KEEP_HEAD - KEEP_TAIL,
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
// Enough of a transcript to see where its session ran. A session's first
|
|
211
|
+
// entries carry its cwd; reading the whole file to learn that is how listing
|
|
212
|
+
// every project would cost a minute.
|
|
213
|
+
const HEAD_BYTES = 64 * 1024
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Every directory any session ran in — read from the head of each transcript,
|
|
217
|
+
* plus the folder each session was launched from. All time, not a window: this
|
|
218
|
+
* answers "which projects do you work in", for `skitterspec project
|
|
219
|
+
* --categories`. Resolving them to repos is the caller's.
|
|
220
|
+
*/
|
|
221
|
+
function knownDirs(root) {
|
|
222
|
+
const dirs = new Set()
|
|
223
|
+
for (const file of listTranscripts(root, new Date(0))) {
|
|
224
|
+
const launch = launchDir(path.basename(path.dirname(file)))
|
|
225
|
+
if (launch) dirs.add(launch)
|
|
226
|
+
let head = ''
|
|
227
|
+
try {
|
|
228
|
+
const fd = fs.openSync(file, 'r')
|
|
229
|
+
const buf = Buffer.alloc(HEAD_BYTES)
|
|
230
|
+
const n = fs.readSync(fd, buf, 0, HEAD_BYTES, 0)
|
|
231
|
+
fs.closeSync(fd)
|
|
232
|
+
head = buf.subarray(0, n).toString('utf8')
|
|
233
|
+
} catch {
|
|
234
|
+
continue
|
|
235
|
+
}
|
|
236
|
+
for (const m of head.matchAll(/"cwd":"((?:[^"\\]|\\.)*)"/g)) {
|
|
237
|
+
try {
|
|
238
|
+
dirs.add(JSON.parse(`"${m[1]}"`))
|
|
239
|
+
} catch {
|
|
240
|
+
// a cwd cut off at the head's edge — the next line will carry it
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
return [...dirs]
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
module.exports = {
|
|
248
|
+
defaultRoot,
|
|
249
|
+
knownDirs,
|
|
250
|
+
launchDir,
|
|
251
|
+
listTranscripts,
|
|
252
|
+
readPrompt,
|
|
253
|
+
readSession,
|
|
254
|
+
trimPrompts,
|
|
255
|
+
PROMPT_CHARS,
|
|
256
|
+
KEEP_HEAD,
|
|
257
|
+
KEEP_TAIL,
|
|
258
|
+
}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The window a ta-da list covers — local time, because "today" is the
|
|
5
|
+
* reader's day and not UTC's. `--since <when>` runs from that day to now;
|
|
6
|
+
* `--on <when>` is that one day. Both read the same `<when>`:
|
|
7
|
+
*
|
|
8
|
+
* named today · yesterday · friday · last friday · last week
|
|
9
|
+
* relative 3 days ago · 3d · 2 weeks ago · 2w
|
|
10
|
+
* a date 2026-11-06 · 6 Nov · Nov 6 · 6 November 2026
|
|
11
|
+
*
|
|
12
|
+
* Pure: `now` is injected, so every shape is pinned without a clock.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday']
|
|
16
|
+
const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december']
|
|
17
|
+
|
|
18
|
+
const GRAMMAR = 'today, yesterday, a weekday (last friday), N days/weeks ago (3d, 2w), or a date (2026-11-06, 6 Nov)'
|
|
19
|
+
|
|
20
|
+
function daysBefore(d, n) {
|
|
21
|
+
return new Date(d.getFullYear(), d.getMonth(), d.getDate() - n)
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
// A name or its first three letters; `sept` is accepted for September.
|
|
25
|
+
function lookup(names, word) {
|
|
26
|
+
const w = word.toLowerCase()
|
|
27
|
+
const i = names.findIndex((n) => n === w || n.slice(0, 3) === w)
|
|
28
|
+
if (i !== -1) return i
|
|
29
|
+
return w === 'sept' && names === MONTHS ? 8 : -1
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function exactDate(year, month, day, value) {
|
|
33
|
+
const d = new Date(year, month, day)
|
|
34
|
+
// `new Date` rolls 31 Feb over into March rather than refusing it.
|
|
35
|
+
if (d.getMonth() !== month || d.getDate() !== day) throw new Error(`no such date: ${value}`)
|
|
36
|
+
return d
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* @param {string|undefined} value
|
|
41
|
+
* @param {Date} now
|
|
42
|
+
* @returns {Date} the local midnight the day begins at
|
|
43
|
+
* @throws on a value it cannot read — a window guessed from a typo would
|
|
44
|
+
* report the wrong day with total confidence
|
|
45
|
+
*/
|
|
46
|
+
function parseWhen(value, now = new Date()) {
|
|
47
|
+
const raw = (value || 'today').trim()
|
|
48
|
+
const v = raw.toLowerCase().replace(/\s+/g, ' ')
|
|
49
|
+
const today = daysBefore(now, 0)
|
|
50
|
+
let d = null
|
|
51
|
+
|
|
52
|
+
if (v === 'today') d = today
|
|
53
|
+
else if (v === 'yesterday') d = daysBefore(now, 1)
|
|
54
|
+
else if (v === 'last week' || v === 'a week ago') d = daysBefore(now, 7)
|
|
55
|
+
|
|
56
|
+
// A weekday is the most recent PAST one, so it is never more than a week
|
|
57
|
+
// back: `friday` on a Monday is three days back, and `monday` on a Monday is
|
|
58
|
+
// seven — on the day itself, "since monday" meaning today would be `today`
|
|
59
|
+
// spelled oddly. `last friday` says the same thing in more words.
|
|
60
|
+
if (!d) {
|
|
61
|
+
const m = /^(?:last )?([a-z]+)$/.exec(v)
|
|
62
|
+
const day = m ? lookup(WEEKDAYS, m[1]) : -1
|
|
63
|
+
if (day !== -1) d = daysBefore(now, (now.getDay() - day + 7) % 7 || 7)
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
if (!d) {
|
|
67
|
+
const m = /^(\d+|an?) ?(d|days?|w|weeks?)(?: ago)?$/.exec(v) || /^-(\d+)(d|w)$/.exec(v)
|
|
68
|
+
if (m) {
|
|
69
|
+
const n = /^\d+$/.test(m[1]) ? Number(m[1]) : 1
|
|
70
|
+
d = daysBefore(now, m[2].startsWith('w') ? n * 7 : n)
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
if (!d) {
|
|
75
|
+
const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(v)
|
|
76
|
+
if (iso) d = exactDate(Number(iso[1]), Number(iso[2]) - 1, Number(iso[3]), raw)
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
if (!d) {
|
|
80
|
+
// `6 Nov`, `Nov 6`, either with a year. Without one it is the most recent
|
|
81
|
+
// such date — `20 Dec` read in January means last December.
|
|
82
|
+
const dm = /^(\d{1,2})(?:st|nd|rd|th)? ([a-z]+),? ?(\d{4})?$/.exec(v)
|
|
83
|
+
const md = /^([a-z]+) (\d{1,2})(?:st|nd|rd|th)?,? ?(\d{4})?$/.exec(v)
|
|
84
|
+
const parts = dm ? { day: dm[1], month: dm[2], year: dm[3] } : md ? { day: md[2], month: md[1], year: md[3] } : null
|
|
85
|
+
const month = parts ? lookup(MONTHS, parts.month) : -1
|
|
86
|
+
if (month !== -1) {
|
|
87
|
+
if (parts.year) d = exactDate(Number(parts.year), month, Number(parts.day), raw)
|
|
88
|
+
else {
|
|
89
|
+
d = exactDate(now.getFullYear(), month, Number(parts.day), raw)
|
|
90
|
+
if (d > today) d = exactDate(now.getFullYear() - 1, month, Number(parts.day), raw)
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
if (!d && /^\d{1,2}[/.]\d{1,2}(?:[/.]\d{2,4})?$/.test(v)) {
|
|
96
|
+
// 11/12 is the 11th of December in London and the 12th of November in New
|
|
97
|
+
// York. Picking one is the confident wrong answer this refuses to give.
|
|
98
|
+
throw new Error(`${raw} reads two ways (day/month or month/day) — write 2026-11-12 or 12 Nov`)
|
|
99
|
+
}
|
|
100
|
+
if (!d) throw new Error(`expected ${GRAMMAR} — got: ${raw}`)
|
|
101
|
+
if (d > today) throw new Error(`${raw} is in the future`)
|
|
102
|
+
return d
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* @param {{ since?: string, on?: string }} when
|
|
107
|
+
* @returns {{ since: Date, until: Date }}
|
|
108
|
+
*/
|
|
109
|
+
function windowFor({ since, on } = {}, now = new Date()) {
|
|
110
|
+
if (since && on) throw new Error('--since and --on together name two windows — pick one')
|
|
111
|
+
if (on) {
|
|
112
|
+
const start = parseWhen(on, now)
|
|
113
|
+
const end = daysBefore(start, -1)
|
|
114
|
+
return { since: start, until: end < now ? end : now }
|
|
115
|
+
}
|
|
116
|
+
return { since: parseWhen(since, now), until: now }
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const localDay = (d) =>
|
|
120
|
+
`${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* The window as the reader's own dates — one day, or `first → last`. The
|
|
124
|
+
* digest's timestamps are UTC instants; a label is not, or `--on 10 Nov` read
|
|
125
|
+
* east of Greenwich would be named the 9th.
|
|
126
|
+
*/
|
|
127
|
+
function windowLabel({ since, until }) {
|
|
128
|
+
const last = new Date(until.getTime() - 1) // an `--on` window ends at the next midnight, exclusive
|
|
129
|
+
const a = localDay(since)
|
|
130
|
+
const b = localDay(last < since ? since : last)
|
|
131
|
+
return a === b ? a : `${a} → ${b}`
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
|
|
135
|
+
const MONTH_NAMES = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The window as a person writes dates: `Thursday 12 November 2026` for one
|
|
139
|
+
* day, `Fri 6 – Thu 12 Nov 2026` for a span — the month and year said once
|
|
140
|
+
* when the two ends share them, and both times when they do not.
|
|
141
|
+
*/
|
|
142
|
+
function humanLabel({ since, until }) {
|
|
143
|
+
const last = new Date(until.getTime() - 1)
|
|
144
|
+
const end = last < since ? since : last
|
|
145
|
+
if (localDay(since) === localDay(end)) {
|
|
146
|
+
return `${DAY_NAMES[since.getDay()]} ${since.getDate()} ${MONTH_NAMES[since.getMonth()]} ${since.getFullYear()}`
|
|
147
|
+
}
|
|
148
|
+
const short = (d) => `${DAY_NAMES[d.getDay()].slice(0, 3)} ${d.getDate()}`
|
|
149
|
+
const month = (d) => MONTH_NAMES[d.getMonth()].slice(0, 3)
|
|
150
|
+
const sameYear = since.getFullYear() === end.getFullYear()
|
|
151
|
+
const sameMonth = sameYear && since.getMonth() === end.getMonth()
|
|
152
|
+
const from = sameMonth ? short(since) : `${short(since)} ${month(since)}${sameYear ? '' : ` ${since.getFullYear()}`}`
|
|
153
|
+
return `${from} – ${short(end)} ${month(end)} ${end.getFullYear()}`
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
module.exports = { parseWhen, windowFor, windowLabel, humanLabel, localDay, GRAMMAR }
|
|
@@ -37,6 +37,10 @@
|
|
|
37
37
|
* - `remoteEditedLine(identifier)` the someone-else-edited warning
|
|
38
38
|
* - `twinAdvice(twin, title, specName)` the refusal message for a twin
|
|
39
39
|
* - `afterIssue(issue)` optional; → a report line or null
|
|
40
|
+
* - `retireSubIssue(id)` optional; close a leftover phase
|
|
41
|
+
* sub-issue as not planned and
|
|
42
|
+
* unlink it. Absent means this tracker
|
|
43
|
+
* cannot, and the push names the ids.
|
|
40
44
|
* - `setParent(issue, parentIdentifier)` optional; make the spec issue a
|
|
41
45
|
* child of its epic's → `{ changed }`.
|
|
42
46
|
* Absent means this tracker cannot
|
|
@@ -226,6 +230,26 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
|
|
|
226
230
|
lines.push(` sub-issue updated: ${sub.id}`)
|
|
227
231
|
}
|
|
228
232
|
|
|
233
|
+
// 5b. Retire an epic's leftover phase sub-issues (spec feat-epic-migration,
|
|
234
|
+
// Decision 2). Never fatal: a tracker without the seam names the ids once and
|
|
235
|
+
// they are forgotten — the line is the record; a retire that FAILS keeps its
|
|
236
|
+
// id in the snapshot, so the next push tries again.
|
|
237
|
+
const keepSubIssues = []
|
|
238
|
+
const retire = (plan.subIssues && plan.subIssues.retire) || []
|
|
239
|
+
if (retire.length && typeof ops.retireSubIssue !== 'function') {
|
|
240
|
+
lines.push(` this tracker cannot retire sub-issues here — close by hand: ${retire.join(', ')}`)
|
|
241
|
+
} else {
|
|
242
|
+
for (const id of retire) {
|
|
243
|
+
try {
|
|
244
|
+
await ops.retireSubIssue(id)
|
|
245
|
+
lines.push(` sub-issue retired: ${id} (no phase claims it on an epic)`)
|
|
246
|
+
} catch (error) {
|
|
247
|
+
keepSubIssues.push(id)
|
|
248
|
+
lines.push(` ?? retire ${id}: ${String((error && error.message) || error).split('\n')[0]}`)
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
|
|
229
253
|
// 6. Read back what the tracker stored and run the SAME check verify runs.
|
|
230
254
|
const stored = { issue: undefined, subIssues: {} }
|
|
231
255
|
if (result.issue) {
|
|
@@ -241,7 +265,7 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
|
|
|
241
265
|
const lost = verify.some((l) => l.includes('!!') || l.includes('??'))
|
|
242
266
|
|
|
243
267
|
// 7. Record the snapshot from the now-stamped files, so the next push is empty.
|
|
244
|
-
const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent })
|
|
268
|
+
const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent, keepSubIssues })
|
|
245
269
|
// A repo path, `/`-separated on every platform — the form every other
|
|
246
270
|
// spec path in this output takes.
|
|
247
271
|
lines.push(` snapshot: ${path.relative(dir, file).split(path.sep).join('/')}`)
|
|
@@ -252,7 +252,7 @@ function remapped(recorded, current) {
|
|
|
252
252
|
* `plan.issue` (when present) is the spec issue's description + state; the push
|
|
253
253
|
* skill applies its provider's project/grouping choice on top of it.
|
|
254
254
|
*/
|
|
255
|
-
function planChanges(projection, snapshot, { linked = false } = {}) {
|
|
255
|
+
function planChanges(projection, snapshot, { linked = false, epic = false } = {}) {
|
|
256
256
|
const p = projection || {}
|
|
257
257
|
const snap = snapshot || {}
|
|
258
258
|
const snapS = snap.subIssues || {}
|
|
@@ -297,6 +297,13 @@ function planChanges(projection, snapshot, { linked = false } = {}) {
|
|
|
297
297
|
}
|
|
298
298
|
}
|
|
299
299
|
|
|
300
|
+
// AN EPIC'S UNCLAIMED IDS ARE LEFTOVERS, NOT LOST STAMPS. An epic has no
|
|
301
|
+
// phases by construction (spec feat-epics, Decision 1), so every sub-issue the
|
|
302
|
+
// snapshot remembers belongs to the plan spec it was converted from — a
|
|
303
|
+
// positive signal. On any other kind an unclaimed id stays the ambiguity it
|
|
304
|
+
// is above, and nothing is retired (spec feat-epic-migration, Decision 2).
|
|
305
|
+
if (epic && unclaimed.length) subIssues.retire = unclaimed.slice()
|
|
306
|
+
|
|
300
307
|
const plan = { subIssues }
|
|
301
308
|
if (unstamped.length) plan.unstamped = unstamped
|
|
302
309
|
const issue = issueChanges(p, snap, { linked })
|
|
@@ -394,7 +401,8 @@ function issueChanges(projection, snapshot, { linked = false } = {}) {
|
|
|
394
401
|
|
|
395
402
|
// True when a plan would push nothing.
|
|
396
403
|
function isEmptyPlan(plan) {
|
|
397
|
-
|
|
404
|
+
const retire = plan.subIssues.retire || []
|
|
405
|
+
return !plan.issue && !plan.subIssues.create.length && !plan.subIssues.update.length && !retire.length
|
|
398
406
|
}
|
|
399
407
|
|
|
400
408
|
module.exports = {
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
'use strict'
|
|
2
2
|
|
|
3
|
+
const path = require('node:path')
|
|
4
|
+
|
|
3
5
|
/**
|
|
4
6
|
* `push` — repo → Linear, one-way. The repo is the source of truth; Linear is a
|
|
5
7
|
* generated mirror. We never read remote content: `push` builds the local
|
|
@@ -102,7 +104,8 @@ function isLinked(snapshotDir, config) {
|
|
|
102
104
|
function push({ dir, snapshotDir, identifier, config }) {
|
|
103
105
|
const projection = projectionOf(snapshotDir, config)
|
|
104
106
|
const snapshot = readBase(dir, identifier, config)
|
|
105
|
-
const
|
|
107
|
+
const epic = path.basename(String(snapshotDir || '')).startsWith('epic-')
|
|
108
|
+
const plan = planChanges(projection, snapshot, { linked: isLinked(snapshotDir, config), epic })
|
|
106
109
|
// A spec still linked under the pre-9.0 model reads as unlinked here, so the
|
|
107
110
|
// plan above is all-creates and would abandon a live mirror. Carry the finding
|
|
108
111
|
// ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
|
|
@@ -134,10 +137,18 @@ function push({ dir, snapshotDir, identifier, config }) {
|
|
|
134
137
|
// that was NOT sent would claim the tracker holds it, and silence the very remap
|
|
135
138
|
// this record exists to catch. Without `sent` (a hand-applied MCP push) nothing
|
|
136
139
|
// new is recorded and what was there is kept.
|
|
137
|
-
|
|
140
|
+
// `keepSubIssues` names ids the projection no longer claims but the tracker may
|
|
141
|
+
// still hold — a retire that failed — so the next push plans them again rather
|
|
142
|
+
// than forgetting them.
|
|
143
|
+
function recordPush({ dir, snapshotDir, identifier, config, sent = null, keepSubIssues = [] }) {
|
|
138
144
|
const projection = projectionOf(snapshotDir, config)
|
|
139
145
|
const snapshot = snapshotOf(projection, config)
|
|
140
|
-
const
|
|
146
|
+
const before = readBase(dir, identifier, config)
|
|
147
|
+
for (const id of keepSubIssues) {
|
|
148
|
+
const hash = before && before.subIssues && before.subIssues[String(id)]
|
|
149
|
+
if (hash !== undefined) snapshot.subIssues[String(id)] = hash
|
|
150
|
+
}
|
|
151
|
+
const names = stateNamesRecord(projection, before, sent)
|
|
141
152
|
if (names) snapshot.stateNames = names
|
|
142
153
|
return writeBase(dir, identifier, config, snapshot)
|
|
143
154
|
}
|
|
File without changes
|