@skitterbyte/skitterspec-linear 18.1.0 → 18.1.2
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 +37 -0
- package/assets/core/env.config.md +5 -2
- package/assets/hooks/main-guard.cjs +1 -1
- package/assets/hooks/review-gate.cjs +1 -1
- package/package.json +1 -1
- package/src/cli.js +10 -4
- package/src/env/hotfix.js +29 -3
- package/src/env/proxy.js +33 -0
- package/src/init.js +3 -3
- package/src/vendor/linear/cli-sync.js +33 -283
- package/src/vendor/provider-kit/src/apply.js +10 -0
- package/src/vendor/provider-kit/src/assignment.js +277 -0
- package/src/vendor/provider-kit/src/http.js +30 -11
- package/src/vendor/provider-kit/src/released.js +56 -13
- package/src/vendor/provider-kit/src/releases.js +380 -0
- package/src/vendor/sync-core/index.js +2 -1
- package/src/vendor/sync-core/src/compare.js +32 -0
- package/src/vendor/sync-core/src/normalize.js +10 -1
package/MIGRATION.md
CHANGED
|
@@ -100,6 +100,43 @@ Nothing in `env.config.json` changes.
|
|
|
100
100
|
**If you added a secrets-hook exception for the printed seed commands**, you
|
|
101
101
|
can remove it now. Nothing shipped prints them any more.
|
|
102
102
|
|
|
103
|
+
## `@skitterbyte/skitterspec-azure-boards` v0 → v1 (first release)
|
|
104
|
+
|
|
105
|
+
Nothing to migrate: this is the distribution's first release. It is a superset
|
|
106
|
+
of `@skitterbyte/skitterspec` — install exactly one of the base or one
|
|
107
|
+
superset. Coming from the base, run `npx @skitterbyte/skitterspec-azure-boards
|
|
108
|
+
update` and run `/spec-azure-setup`
|
|
109
|
+
(or `skitterspec-azure-boards spec-sync init-config --org-url … --project …`).
|
|
110
|
+
|
|
111
|
+
**Coming from `@skitterbyte/skitterspec-linear` or `-jira`** — a repo moving
|
|
112
|
+
trackers: swap the distribution, configure Azure as above, set
|
|
113
|
+
`refs.foreignPatterns` to the old team key (e.g. `"ERQ-\\d+"`), then push each
|
|
114
|
+
backlog and in-progress spec (`/spec-push`, or `spec-sync apply --all
|
|
115
|
+
in-progress` and `--all backlog`) to link it to a new work item. Finished specs
|
|
116
|
+
keep their old stamps (`linear_identifier`, …) as history; nothing rewrites
|
|
117
|
+
them. Old `Refs: ERQ-12` trailers stay in the log, and `spec-sync released`
|
|
118
|
+
counts them as `historical` rather than as missing a ref. New commits carry
|
|
119
|
+
`Refs: AB#n`. Delete the old `linear.config.json` / `jira.config.json` once the
|
|
120
|
+
open specs are linked.
|
|
121
|
+
|
|
122
|
+
## `@skitterbyte/skitterspec-github` v0 → v1 (first release)
|
|
123
|
+
|
|
124
|
+
Nothing to migrate: this is the distribution's first release. It is a superset
|
|
125
|
+
of `@skitterbyte/skitterspec` — install exactly one of the base or one
|
|
126
|
+
superset. Coming from the base, run `npx @skitterbyte/skitterspec-github
|
|
127
|
+
update`, make a Projects v2 board for the repo, and run `/spec-github-setup`
|
|
128
|
+
(or `skitterspec-github spec-sync init-config --owner … --repo … --project N`).
|
|
129
|
+
|
|
130
|
+
**Coming from `@skitterbyte/skitterspec-linear` or `-jira`** — a repo moving
|
|
131
|
+
trackers: swap the distribution, configure GitHub as above, then push each
|
|
132
|
+
backlog and in-progress spec (`/spec-push`, or `spec-sync apply --all
|
|
133
|
+
in-progress` and `--all backlog`) to link it to a new issue. Finished specs keep
|
|
134
|
+
their old stamps (`linear_identifier`, …) as history; nothing rewrites them.
|
|
135
|
+
Old `Refs: SKS-12` trailers stay in the log, and `spec-sync released` counts
|
|
136
|
+
them as `historical` rather than as missing a ref. New commits carry
|
|
137
|
+
`Refs: #N`. Delete the old `linear.config.json` / `jira.config.json` once the
|
|
138
|
+
open specs are linked.
|
|
139
|
+
|
|
103
140
|
## `@skitterbyte/skitterspec-jira` v0 → v1 (first release)
|
|
104
141
|
|
|
105
142
|
Nothing to migrate: this is the distribution's first release. It is a superset
|
|
@@ -292,8 +292,11 @@ through to a documented conservative default; see the field notes below.
|
|
|
292
292
|
// one. Empty (the default) = the built-in tagger.
|
|
293
293
|
//
|
|
294
294
|
// `bump` is the built-in tagger's strategy: "patch" (v33.16.4 -> v33.16.5) or
|
|
295
|
-
// "hotfix-suffix" (v33.16.4 -> v33.16.4-hotfix.1, then -hotfix.2,
|
|
296
|
-
// that is already a hotfix tag continues its line
|
|
295
|
+
// "hotfix-suffix" (v33.16.4 -> v33.16.4-hotfix.1, then -hotfix.2, ...). Under
|
|
296
|
+
// either, a base that is already a hotfix tag continues its line
|
|
297
|
+
// (v36.2.3-hotfix.4 -> v36.2.3-hotfix.5), so "patch" never takes a number the
|
|
298
|
+
// mainline owns. When the patch tag already exists, the refusal names the
|
|
299
|
+
// free hotfix tag that "hotfix-suffix" would cut. Any other value is refused
|
|
297
300
|
// when `hotfix land` runs. Tags order X.Y.Z-rc.N < X.Y.Z < X.Y.Z-hotfix.N <
|
|
298
301
|
// X.Y.(Z+1), the same as skittership.
|
|
299
302
|
//
|
|
@@ -85,7 +85,7 @@ function findEngine(projectDir) {
|
|
|
85
85
|
if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
|
|
86
86
|
let at = projectDir
|
|
87
87
|
for (let i = 0; i < 6 && at; i++) {
|
|
88
|
-
for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
|
|
88
|
+
for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
|
|
89
89
|
const candidate = path.join(at, 'node_modules', '.bin', name)
|
|
90
90
|
if (fs.existsSync(candidate)) return candidate
|
|
91
91
|
}
|
|
@@ -82,7 +82,7 @@ function findEngine(projectDir) {
|
|
|
82
82
|
if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
|
|
83
83
|
let at = projectDir
|
|
84
84
|
for (let i = 0; i < 6 && at; i++) {
|
|
85
|
-
for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']) {
|
|
85
|
+
for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
|
|
86
86
|
const candidate = path.join(at, 'node_modules', '.bin', name)
|
|
87
87
|
if (fs.existsSync(candidate)) return candidate
|
|
88
88
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "18.1.
|
|
3
|
+
"version": "18.1.2",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
package/src/cli.js
CHANGED
|
@@ -165,7 +165,13 @@ const { planHotfixLand, planHotfixFinish } = require('./env/hotfix.js')
|
|
|
165
165
|
const { runHotfixLand, describeStep: describeHotfixStep } = require('./env/hotfixland.js')
|
|
166
166
|
const { planDev } = require('./env/dev.js')
|
|
167
167
|
const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
|
|
168
|
-
const {
|
|
168
|
+
const {
|
|
169
|
+
renderRoutes,
|
|
170
|
+
portsHeld,
|
|
171
|
+
portsAnswering,
|
|
172
|
+
portsInUseOn,
|
|
173
|
+
waitListening,
|
|
174
|
+
} = require('./env/proxy.js')
|
|
169
175
|
const {
|
|
170
176
|
mintToken,
|
|
171
177
|
servableSpecs,
|
|
@@ -185,7 +191,7 @@ const pkg = require('../package.json')
|
|
|
185
191
|
// supersets the hand-off names both where both ship the command, and the one
|
|
186
192
|
// that does where only one does.
|
|
187
193
|
const PROVIDER_COMMANDS = {
|
|
188
|
-
'spec-sync': '@skitterbyte/skitterspec-linear or @skitterbyte/skitterspec-
|
|
194
|
+
'spec-sync': '@skitterbyte/skitterspec-linear, @skitterbyte/skitterspec-jira, @skitterbyte/skitterspec-github or @skitterbyte/skitterspec-azure-boards',
|
|
189
195
|
'spec-sanitise': '@skitterbyte/skitterspec-linear',
|
|
190
196
|
}
|
|
191
197
|
|
|
@@ -4988,7 +4994,7 @@ async function specEnvConnect(dir, config, specArg) {
|
|
|
4988
4994
|
// Stop any proxy we already run (a previous connect), freeing the canonical
|
|
4989
4995
|
// ports, then refuse if the primary checkout still holds one of them.
|
|
4990
4996
|
await stopProcess(proxyProc, { rootDir: dir })
|
|
4991
|
-
const busy = await
|
|
4997
|
+
const busy = await portsHeld(routes.map((r) => r.frontPort), config.proxy.host)
|
|
4992
4998
|
if (busy.length) {
|
|
4993
4999
|
process.stdout.write(
|
|
4994
5000
|
`spec-connect: canonical port(s) ${busy.join(', ')} are in use (your main dev server?).\n` +
|
|
@@ -5199,7 +5205,7 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
|
|
|
5199
5205
|
const canonicalPorts = config.dev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
|
|
5200
5206
|
let serverUp = null
|
|
5201
5207
|
if (canonicalPorts.length) {
|
|
5202
|
-
const up = await
|
|
5208
|
+
const up = await portsAnswering(canonicalPorts, config.proxy.host)
|
|
5203
5209
|
serverUp = up.length === canonicalPorts.length
|
|
5204
5210
|
}
|
|
5205
5211
|
|
package/src/env/hotfix.js
CHANGED
|
@@ -114,12 +114,38 @@ const BUMPS = ['patch', 'hotfix-suffix']
|
|
|
114
114
|
// The tag `hotfix.bump` asks for. An unknown strategy throws rather than
|
|
115
115
|
// falling back to `patch`: a typo there would otherwise cut the wrong release
|
|
116
116
|
// line and say nothing.
|
|
117
|
+
//
|
|
118
|
+
// Under `patch`, a base that is ITSELF a `-hotfix.N` tag continues that line.
|
|
119
|
+
// Bumping its patch takes X.Y.(Z+1), a number the mainline owns: refused when
|
|
120
|
+
// the mainline already cut it, and minted silently when it had not. Only a
|
|
121
|
+
// parsed hotfix suffix routes here; an rc or any other suffix keeps the patch
|
|
122
|
+
// bump, so a base we cannot read as a hotfix line is never treated as one.
|
|
117
123
|
function nextTag(baseTag, existingTags, bump = 'patch') {
|
|
118
|
-
if (bump === 'patch')
|
|
124
|
+
if (bump === 'patch') {
|
|
125
|
+
const base = parseTag(baseTag)
|
|
126
|
+
if (base && base.hotfix !== null) return nextHotfixTag(baseTag, existingTags)
|
|
127
|
+
return bumpPatch(baseTag)
|
|
128
|
+
}
|
|
119
129
|
if (bump === 'hotfix-suffix') return nextHotfixTag(baseTag, existingTags)
|
|
120
130
|
throw new Error(`unknown hotfix.bump "${bump}" — use one of: ${BUMPS.join(', ')}`)
|
|
121
131
|
}
|
|
122
132
|
|
|
133
|
+
// What a collision refusal offers: the free tag on the same base's hotfix
|
|
134
|
+
// line, which is never taken by a mainline release. Never a deletion and never
|
|
135
|
+
// another base — the first destroys a released tag, the second forks from a
|
|
136
|
+
// version prod is not running. Empty where the suffix line cannot be derived
|
|
137
|
+
// (an rc base) or is already the strategy, so the refusal just names the tag.
|
|
138
|
+
function freeTagHint(baseTag, existingTags, bump) {
|
|
139
|
+
if (bump !== 'patch') return ''
|
|
140
|
+
let free
|
|
141
|
+
try {
|
|
142
|
+
free = nextHotfixTag(baseTag, existingTags)
|
|
143
|
+
} catch {
|
|
144
|
+
return ''
|
|
145
|
+
}
|
|
146
|
+
return ` — set hotfix.bump "hotfix-suffix" in env.config.json to cut ${free} instead`
|
|
147
|
+
}
|
|
148
|
+
|
|
123
149
|
// A filesystem/branch-safe slug derived from a tag (`v30.2.1` → `v30-2-1`).
|
|
124
150
|
function tagSlug(tag) {
|
|
125
151
|
return String(tag)
|
|
@@ -206,7 +232,7 @@ function planHotfixLand(spec, config, ctx) {
|
|
|
206
232
|
} else {
|
|
207
233
|
prodTag = nextTag(baseRef, c.existingTags, bump)
|
|
208
234
|
if (taken.has(prodTag)) {
|
|
209
|
-
return block(`tag ${prodTag} already exists
|
|
235
|
+
return block(`tag ${prodTag} already exists${freeTagHint(baseRef, c.existingTags, bump)}`)
|
|
210
236
|
}
|
|
211
237
|
taken.add(prodTag)
|
|
212
238
|
commands.push(`git -C ${spec.worktreePath} tag ${prodTag}`)
|
|
@@ -248,7 +274,7 @@ function planHotfixLand(spec, config, ctx) {
|
|
|
248
274
|
// hotfix numbers rather than colliding on the same one.
|
|
249
275
|
const tag = nextTag(t, [...taken], bump)
|
|
250
276
|
if (taken.has(tag)) {
|
|
251
|
-
return block(`tag ${tag} (for target ${t}) already exists
|
|
277
|
+
return block(`tag ${tag} (for target ${t}) already exists${freeTagHint(t, [...taken], bump)}`)
|
|
252
278
|
}
|
|
253
279
|
taken.add(tag)
|
|
254
280
|
const slug = `${spec.slug}-onto-${tagSlug(t)}`
|
package/src/env/proxy.js
CHANGED
|
@@ -167,12 +167,45 @@ async function portsInUseOn(port, hosts, probe = portsInUse) {
|
|
|
167
167
|
return [...new Set(busy)]
|
|
168
168
|
}
|
|
169
169
|
|
|
170
|
+
/**
|
|
171
|
+
* Which of `ports` accept a connection on `host` — "is a dev server running?".
|
|
172
|
+
*
|
|
173
|
+
* CONNECTS, never binds. A bind probe on 127.0.0.1 SUCCEEDS on macOS beside a
|
|
174
|
+
* server listening on every address (Vite `host: true`, Fastify `0.0.0.0`),
|
|
175
|
+
* because BSD lets the two coexist, so it read a running phone-on-wifi dev
|
|
176
|
+
* server as absent. Linux refuses the second bind, which is why CI never saw
|
|
177
|
+
* it. A server that answers is running on any OS. What could still fool it: a
|
|
178
|
+
* server bound only to a non-loopback address, which `host` does not reach.
|
|
179
|
+
*/
|
|
180
|
+
async function portsAnswering(ports, host = '127.0.0.1') {
|
|
181
|
+
const results = await Promise.all(ports.map((p) => checkListening(p, host)))
|
|
182
|
+
return ports.filter((_, i) => results[i])
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* Which of `ports` are taken for a new listener on `host` — "may the proxy
|
|
187
|
+
* have these?". Busy when the bind fails OR something already answers.
|
|
188
|
+
*
|
|
189
|
+
* The bind alone is not enough on macOS: beside a wildcard listener it
|
|
190
|
+
* succeeds, and the proxy would then own `localhost` while LAN clients still
|
|
191
|
+
* reach the old server — two apps behind one port number. The connect catches
|
|
192
|
+
* that. SEQUENTIAL, bind first: the bind probe's own listener is closed before
|
|
193
|
+
* the connect runs, so the connect can never find the probe itself.
|
|
194
|
+
*/
|
|
195
|
+
async function portsHeld(ports, host = '127.0.0.1') {
|
|
196
|
+
const bound = await portsInUse(ports, host)
|
|
197
|
+
const answering = await portsAnswering(ports, host)
|
|
198
|
+
return ports.filter((p) => bound.includes(p) || answering.includes(p))
|
|
199
|
+
}
|
|
200
|
+
|
|
170
201
|
module.exports = {
|
|
171
202
|
renderRoutes,
|
|
172
203
|
createRouteServer,
|
|
173
204
|
startProxy,
|
|
174
205
|
portsInUse,
|
|
175
206
|
portsInUseOn,
|
|
207
|
+
portsAnswering,
|
|
208
|
+
portsHeld,
|
|
176
209
|
waitListening,
|
|
177
210
|
}
|
|
178
211
|
|
package/src/init.js
CHANGED
|
@@ -125,7 +125,7 @@ function detectPackageManager(dir) {
|
|
|
125
125
|
|
|
126
126
|
// The bin names a distribution may expose. A provider superset ships its own
|
|
127
127
|
// name alongside `skitterspec`, and either proves the engine is reachable.
|
|
128
|
-
const ENGINE_BINS = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira']
|
|
128
|
+
const ENGINE_BINS = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
|
|
129
129
|
|
|
130
130
|
function binNames() {
|
|
131
131
|
return process.platform === 'win32'
|
|
@@ -914,8 +914,8 @@ function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
|
|
|
914
914
|
// never delete spec content or active config (defense-in-depth — the manifest
|
|
915
915
|
// never lists these, but a tampered/foreign entry must still be refused).
|
|
916
916
|
const PROTECTED_SPEC_BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
|
|
917
|
-
const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json', 'jira.config.json']
|
|
918
|
-
const PROTECTED_DIRS = ['linear-base', 'linear-backups', 'jira-base', 'jira-backups']
|
|
917
|
+
const PROTECTED_CONFIG = ['env.config.json', 'linear.config.json', 'jira.config.json', 'github.config.json', 'azure-boards.config.json']
|
|
918
|
+
const PROTECTED_DIRS = ['linear-base', 'linear-backups', 'jira-base', 'jira-backups', 'github-base', 'github-backups', 'azure-base', 'azure-backups']
|
|
919
919
|
|
|
920
920
|
function assertSafeToDelete(relPath, managedSet) {
|
|
921
921
|
const norm = relPath.split(path.sep).join('/')
|
|
@@ -83,7 +83,40 @@ const {
|
|
|
83
83
|
removeUser,
|
|
84
84
|
} = require('./credentials.js')
|
|
85
85
|
const { resolveIdentity, displayNameOf } = require('./identity.js')
|
|
86
|
+
const { makeAssignmentCommands } = require('../provider-kit/src/assignment.js')
|
|
86
87
|
const { resolveTransport } = require('../provider-kit/src/transport.js')
|
|
88
|
+
|
|
89
|
+
// `assign`, `whoami` and `users` are the kit's (`provider-kit/src/assignment.js`),
|
|
90
|
+
// hoisted when the GitHub provider became their second consumer. What is
|
|
91
|
+
// Linear's is the binding: the team-keyed store, the API key and the wording.
|
|
92
|
+
const assignment = makeAssignmentCommands({
|
|
93
|
+
tracker: 'Linear',
|
|
94
|
+
configFile: 'specs/.core/linear.config.json',
|
|
95
|
+
bin: 'skitterspec',
|
|
96
|
+
idHint: '<linear-user-id>',
|
|
97
|
+
scopeOf: (config) => {
|
|
98
|
+
const teamId = (config.linear && config.linear.teamId) || ''
|
|
99
|
+
const teamKey = (config.linear && config.linear.teamKey) || ''
|
|
100
|
+
return {
|
|
101
|
+
id: teamId,
|
|
102
|
+
label: teamKey ? `${teamId} (${teamKey})` : teamId,
|
|
103
|
+
missing:
|
|
104
|
+
'spec-sync whoami: no linear.teamId in specs/.core/linear.config.json.\n' +
|
|
105
|
+
' Identity is stored per team — run `spec-sync init-config` first.',
|
|
106
|
+
}
|
|
107
|
+
},
|
|
108
|
+
storePath: (env) => storePath(env),
|
|
109
|
+
writeUser: (file, scope, user, deps) => writeUser(file, scope, user, deps),
|
|
110
|
+
removeUser: (file, scope, deps) => removeUser(file, scope, deps),
|
|
111
|
+
resolveIdentity: (config, env, deps) => resolveIdentity(config, env, deps),
|
|
112
|
+
resolveCredential: (config, env) => resolveApiKey(config, env),
|
|
113
|
+
makeAdapter: (config, key, flags) => makeApiAdapter({ apiKey: key.key, fetch: flags.fetch }),
|
|
114
|
+
displayNameOf: (u) => displayNameOf(u),
|
|
115
|
+
usersOverMcp: 'search the workspace over MCP with the user-list tool',
|
|
116
|
+
})
|
|
117
|
+
const specSyncAssign = (dir, config, specArg, flags, out) => assignment.assign(dir, config, specArg, flags, out)
|
|
118
|
+
const specSyncWhoami = (dir, config, flags, out) => assignment.whoami(dir, config, flags, out)
|
|
119
|
+
const specSyncUsers = (dir, config, query, flags, out) => assignment.users(dir, config, query, flags, out)
|
|
87
120
|
const { readAllStdin, promptHidden } = require('../provider-kit/src/prompt.js')
|
|
88
121
|
const { applySpecPlan } = require('../provider-kit/src/apply.js')
|
|
89
122
|
|
|
@@ -375,100 +408,6 @@ function specSyncStamp(dir, config, specArg, flags, out) {
|
|
|
375
408
|
return 0
|
|
376
409
|
}
|
|
377
410
|
|
|
378
|
-
/**
|
|
379
|
-
* `spec-sync assign <spec> [--to <id> [--name <n>]] [--release] [--json]`
|
|
380
|
-
*
|
|
381
|
-
* Record — or release — who owns a spec, by stamping `linear_assignee_id` /
|
|
382
|
-
* `linear_assignee_name` into the overview frontmatter. The counterpart to
|
|
383
|
-
* `spec-sync stamp`, which does the same job for issue ids.
|
|
384
|
-
*
|
|
385
|
-
* **It writes the repo and nothing else.** Pushing is the caller's next step,
|
|
386
|
-
* deliberately: the repo is the source of truth, so ownership changes here and
|
|
387
|
-
* the mirror catches up like any other edit. Splitting it that way also means a
|
|
388
|
-
* failed push leaves the claim recorded rather than lost.
|
|
389
|
-
*
|
|
390
|
-
* **Stamping is explicit, and never inferred by a push.** Only this verb (and
|
|
391
|
-
* the skills that call it) writes the field. A push that resolved identity for
|
|
392
|
-
* itself would quietly re-assign a spec to whoever happened to run it — which is
|
|
393
|
-
* how a teammate pushing someone else's branch would steal their work.
|
|
394
|
-
*
|
|
395
|
-
* **And it refuses where the write could not travel.** Two preconditions, for
|
|
396
|
-
* one reason: an unlinked spec has no issue, and a repo that does not own
|
|
397
|
-
* `assignee` has no field. In either case the stamp would sit in the file doing
|
|
398
|
-
* nothing while this command's success line promised `next: push it, so Linear
|
|
399
|
-
* agrees`. The failure mode being guarded is not a silent skip — it is a true-
|
|
400
|
-
* sounding sentence, which is worse, because nothing later contradicts it.
|
|
401
|
-
*/
|
|
402
|
-
function specSyncAssign(dir, config, specArg, flags, out) {
|
|
403
|
-
const snapshotDir = resolveOrExit(specArg, dir, out)
|
|
404
|
-
if (!snapshotDir) return 1
|
|
405
|
-
|
|
406
|
-
const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
|
|
407
|
-
const identifier = linkedIdentifier(path.join(snapshotDir, overviewFile))
|
|
408
|
-
const rel = path.relative(dir, snapshotDir)
|
|
409
|
-
|
|
410
|
-
const problems = []
|
|
411
|
-
if (flags.release && flags.to) problems.push('--release and --to are opposites — pass one')
|
|
412
|
-
if (!flags.release && !flags.to) problems.push('nothing to do — pass --to <user-id> or --release')
|
|
413
|
-
// An unlinked spec has no issue to assign. Refusing beats stamping a field
|
|
414
|
-
// that would sit in the file doing nothing until someone noticed.
|
|
415
|
-
if (!identifier) problems.push(`${rel} is not linked to Linear — /spec-push it first`)
|
|
416
|
-
// AND THE SAME REASONING FOR THE FIELD ITSELF. `toFieldSet` drops a field the
|
|
417
|
-
// repo does not own, so a stamp written here would never reach the tracker —
|
|
418
|
-
// while this command's success line says `next: push it, so Linear agrees`.
|
|
419
|
-
// That is not a silent skip, it is an assertion that is untrue, and the cost
|
|
420
|
-
// is someone believing a spec is assigned for as long as it takes them to
|
|
421
|
-
// look. `/spec-claim` already refuses on this; the engine beneath it did not.
|
|
422
|
-
//
|
|
423
|
-
// Applies to `--release` too. Nothing it could clear was ever pushed, so
|
|
424
|
-
// releasing is inert here as well, and one command in this function acting on
|
|
425
|
-
// a field the repo declares it does not own is the inconsistency that would
|
|
426
|
-
// teach the next reader the check is optional.
|
|
427
|
-
if (!ownsField(config, 'assignee')) {
|
|
428
|
-
problems.push(
|
|
429
|
-
'this repo does not own the assignee field — set sync.fieldOwnership.assignee ' +
|
|
430
|
-
`to "push" in ${CONFIG_FILE}`,
|
|
431
|
-
)
|
|
432
|
-
}
|
|
433
|
-
|
|
434
|
-
if (problems.length) {
|
|
435
|
-
out.write(
|
|
436
|
-
['spec-sync assign: refusing to write — nothing was changed', ...problems.map((p) => ` ${p}`)].join('\n') + '\n',
|
|
437
|
-
)
|
|
438
|
-
return 1
|
|
439
|
-
}
|
|
440
|
-
|
|
441
|
-
if (flags.release) {
|
|
442
|
-
const removed = deleteFrontmatter(snapshotDir, config, ['linear_assignee_id', 'linear_assignee_name'])
|
|
443
|
-
if (flags.json) {
|
|
444
|
-
out.write(JSON.stringify({ spec: rel, issue: identifier, released: removed.length > 0 }, null, 2) + '\n')
|
|
445
|
-
return 0
|
|
446
|
-
}
|
|
447
|
-
out.write(
|
|
448
|
-
(removed.length
|
|
449
|
-
? `spec-sync assign: ${rel} released (${identifier})\n`
|
|
450
|
-
: `spec-sync assign: ${rel} records no assignee — nothing to release\n`) +
|
|
451
|
-
' next: push it, so Linear is unassigned too\n',
|
|
452
|
-
)
|
|
453
|
-
return 0
|
|
454
|
-
}
|
|
455
|
-
|
|
456
|
-
writeFrontmatter(snapshotDir, config, {
|
|
457
|
-
linear_assignee_id: flags.to,
|
|
458
|
-
// Display only — the projection never sends it. It exists so a reader (and
|
|
459
|
-
// `/spec-claim`) can name the person without a Linear round trip.
|
|
460
|
-
linear_assignee_name: flags.name || null,
|
|
461
|
-
})
|
|
462
|
-
if (flags.json) {
|
|
463
|
-
out.write(
|
|
464
|
-
JSON.stringify({ spec: rel, issue: identifier, id: flags.to, name: flags.name || null }, null, 2) + '\n',
|
|
465
|
-
)
|
|
466
|
-
return 0
|
|
467
|
-
}
|
|
468
|
-
const who = flags.name ? `${flags.name} (${flags.to})` : flags.to
|
|
469
|
-
out.write(`spec-sync assign: ${rel} assigned to ${who} (${identifier})\n next: push it, so Linear agrees\n`)
|
|
470
|
-
return 0
|
|
471
|
-
}
|
|
472
411
|
|
|
473
412
|
// `spec-sync record <spec>` — write the last-pushed snapshot from the CURRENT
|
|
474
413
|
// files. The skill calls this AFTER applying the plan and stamping new ids.
|
|
@@ -2568,195 +2507,6 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
|
|
|
2568
2507
|
return applySpecPlan({ dir, config, snapshotDir, plan, adapter, ops, forceNew })
|
|
2569
2508
|
}
|
|
2570
2509
|
|
|
2571
|
-
/**
|
|
2572
|
-
* `spec-sync whoami [--json] [--set <id> [--name <n>]] [--unset]`
|
|
2573
|
-
*
|
|
2574
|
-
* Report — and cache — who the operator is in Linear, which is the fact
|
|
2575
|
-
* assignment rests on. See `identity.js` for why it is derived rather than
|
|
2576
|
-
* configured.
|
|
2577
|
-
*
|
|
2578
|
-
* **Exit code 0 even when the answer is "unknown".** This deliberately differs
|
|
2579
|
-
* from `credentials status`, which exits 1 with no key: that command is a
|
|
2580
|
-
* READINESS check, and a missing key means the thing you asked about cannot
|
|
2581
|
-
* work. This one answers a question, and "nobody is identified here" is a valid
|
|
2582
|
-
* answer — a shared key, an offline machine, a repo mid-setup. Exiting non-zero
|
|
2583
|
-
* would make every caller treat an ordinary state as a fault, which is how an
|
|
2584
|
-
* advisory check turns into one that accuses.
|
|
2585
|
-
*
|
|
2586
|
-
* A successful DERIVE is cached; a read from the cache is not re-written. The
|
|
2587
|
-
* caching lives here rather than in `resolveIdentity` so that asking the
|
|
2588
|
-
* question never has a side effect — see that module's header.
|
|
2589
|
-
*/
|
|
2590
|
-
async function specSyncWhoami(dir, config, flags, out) {
|
|
2591
|
-
const env = flags.env || process.env
|
|
2592
|
-
const file = storePath(env)
|
|
2593
|
-
const teamId = (config.linear && config.linear.teamId) || ''
|
|
2594
|
-
const teamKey = (config.linear && config.linear.teamKey) || ''
|
|
2595
|
-
const label = teamKey ? `${teamId} (${teamKey})` : teamId
|
|
2596
|
-
|
|
2597
|
-
// The store is keyed by team, so without one there is nowhere to read from or
|
|
2598
|
-
// write to. That IS a broken config rather than an ordinary unknown, so unlike
|
|
2599
|
-
// the rest of this command it exits non-zero.
|
|
2600
|
-
if (!teamId) {
|
|
2601
|
-
out.write(
|
|
2602
|
-
'spec-sync whoami: no linear.teamId in specs/.core/linear.config.json.\n' +
|
|
2603
|
-
' Identity is stored per team — run `spec-sync init-config` first.\n',
|
|
2604
|
-
)
|
|
2605
|
-
return 1
|
|
2606
|
-
}
|
|
2607
|
-
|
|
2608
|
-
if (flags.unset) {
|
|
2609
|
-
const r = removeUser(file, teamId, {})
|
|
2610
|
-
if (!r.ok) {
|
|
2611
|
-
out.write(`spec-sync whoami: ${r.reason}\n`)
|
|
2612
|
-
return 1
|
|
2613
|
-
}
|
|
2614
|
-
out.write(
|
|
2615
|
-
r.removed
|
|
2616
|
-
? `spec-sync whoami: forgot the identity for ${label} (the API key is untouched)\n`
|
|
2617
|
-
: `spec-sync whoami: no identity stored for ${label} — nothing to forget\n`,
|
|
2618
|
-
)
|
|
2619
|
-
return 0
|
|
2620
|
-
}
|
|
2621
|
-
|
|
2622
|
-
if (flags.set) {
|
|
2623
|
-
const r = writeUser(file, teamId, { id: flags.set, name: flags.name }, {})
|
|
2624
|
-
if (!r.ok) {
|
|
2625
|
-
out.write(`spec-sync whoami: ${r.reason}\n`)
|
|
2626
|
-
return 1
|
|
2627
|
-
}
|
|
2628
|
-
if (flags.json) {
|
|
2629
|
-
out.write(
|
|
2630
|
-
JSON.stringify({ id: flags.set, name: flags.name || null, source: 'set', store: r.path }, null, 2) + '\n',
|
|
2631
|
-
)
|
|
2632
|
-
return 0
|
|
2633
|
-
}
|
|
2634
|
-
const shown = flags.name ? `${flags.name} (${flags.set})` : flags.set
|
|
2635
|
-
out.write(`spec-sync whoami: identity for ${label} set to ${shown} in ${r.path} (600)\n`)
|
|
2636
|
-
return 0
|
|
2637
|
-
}
|
|
2638
|
-
|
|
2639
|
-
const identity = await resolveIdentity(config, env, { adapter: flags.adapter, fetch: flags.fetch })
|
|
2640
|
-
|
|
2641
|
-
if (identity.ok && identity.source === 'viewer') {
|
|
2642
|
-
// Cache what the network just told us, so the next `/spec-start` costs no
|
|
2643
|
-
// call. A failed write is not fatal: we HAVE the answer, and re-deriving it
|
|
2644
|
-
// next time is a slower success, not a wrong one.
|
|
2645
|
-
const cached = writeUser(file, teamId, { id: identity.id, name: identity.name }, {})
|
|
2646
|
-
if (!cached.ok) identity.cacheWarning = cached.reason
|
|
2647
|
-
}
|
|
2648
|
-
|
|
2649
|
-
if (flags.json) {
|
|
2650
|
-
out.write(
|
|
2651
|
-
JSON.stringify(
|
|
2652
|
-
{
|
|
2653
|
-
team: label,
|
|
2654
|
-
store: file,
|
|
2655
|
-
ok: identity.ok,
|
|
2656
|
-
id: identity.id || null,
|
|
2657
|
-
name: identity.name || null,
|
|
2658
|
-
source: identity.source,
|
|
2659
|
-
reason: identity.ok ? null : identity.reason || null,
|
|
2660
|
-
},
|
|
2661
|
-
null,
|
|
2662
|
-
2,
|
|
2663
|
-
) + '\n',
|
|
2664
|
-
)
|
|
2665
|
-
return 0
|
|
2666
|
-
}
|
|
2667
|
-
|
|
2668
|
-
if (!identity.ok) {
|
|
2669
|
-
out.write(
|
|
2670
|
-
[
|
|
2671
|
-
'spec-sync whoami: unknown — no identity for this workspace',
|
|
2672
|
-
` ${identity.reason}`,
|
|
2673
|
-
' Set one by hand:',
|
|
2674
|
-
' skitterspec spec-sync whoami --set <linear-user-id> --name "<your name>"',
|
|
2675
|
-
' Find the id with: skitterspec spec-sync users <name-or-email>',
|
|
2676
|
-
].join('\n') + '\n',
|
|
2677
|
-
)
|
|
2678
|
-
return 0
|
|
2679
|
-
}
|
|
2680
|
-
|
|
2681
|
-
const where = identity.source === 'store' ? `cached in ${file}` : 'derived from the API key'
|
|
2682
|
-
const lines = [
|
|
2683
|
-
`spec-sync whoami: ${identity.name || '(unnamed)'} <${identity.id}>`,
|
|
2684
|
-
` team: ${label}`,
|
|
2685
|
-
` source: ${where}`,
|
|
2686
|
-
]
|
|
2687
|
-
if (identity.cacheWarning) lines.push(` note: not cached — ${identity.cacheWarning}`)
|
|
2688
|
-
out.write(lines.join('\n') + '\n')
|
|
2689
|
-
return 0
|
|
2690
|
-
}
|
|
2691
|
-
|
|
2692
|
-
/**
|
|
2693
|
-
* `spec-sync users [<query>] [--json] [--limit N] [--cursor C]`
|
|
2694
|
-
*
|
|
2695
|
-
* Find a person by name or email. Both halves matter: search is what makes this
|
|
2696
|
-
* usable in a workspace of hundreds, and the bare listing is what answers "show
|
|
2697
|
-
* me everyone" in one of five. Linear's user query does both, so this is one
|
|
2698
|
-
* command rather than a `users` and a `search-users`.
|
|
2699
|
-
*
|
|
2700
|
-
* The engine answers on the API path and steps aside on the MCP path — the same
|
|
2701
|
-
* contract `states` and `projects` follow.
|
|
2702
|
-
*/
|
|
2703
|
-
async function specSyncUsers(dir, config, query, flags, out) {
|
|
2704
|
-
const key = resolveApiKey(config, flags.env || process.env)
|
|
2705
|
-
const transport = resolveTransport(flags, config, key.ok)
|
|
2706
|
-
|
|
2707
|
-
if (transport === 'mcp') {
|
|
2708
|
-
if (flags.json) {
|
|
2709
|
-
out.write(
|
|
2710
|
-
JSON.stringify({ transport: 'mcp', reason: key.ok ? 'requested' : key.error, users: null }, null, 2) + '\n',
|
|
2711
|
-
)
|
|
2712
|
-
return 0
|
|
2713
|
-
}
|
|
2714
|
-
out.write(
|
|
2715
|
-
[
|
|
2716
|
-
'spec-sync users: transport = mcp',
|
|
2717
|
-
` ${key.ok ? '--via mcp was requested' : key.error}`,
|
|
2718
|
-
' search the workspace over MCP with the user-list tool',
|
|
2719
|
-
].join('\n') + '\n',
|
|
2720
|
-
)
|
|
2721
|
-
return 0
|
|
2722
|
-
}
|
|
2723
|
-
if (!key.ok) {
|
|
2724
|
-
out.write(`spec-sync users: refusing — ${key.error}\n`)
|
|
2725
|
-
return 1
|
|
2726
|
-
}
|
|
2727
|
-
|
|
2728
|
-
const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
|
|
2729
|
-
let page
|
|
2730
|
-
try {
|
|
2731
|
-
page = await adapter.searchUsers(query || '', { limit: flags.limit || 50, cursor: flags.cursor || null })
|
|
2732
|
-
} catch (error) {
|
|
2733
|
-
out.write(`spec-sync users: ${error.message}\n`)
|
|
2734
|
-
return 1
|
|
2735
|
-
}
|
|
2736
|
-
|
|
2737
|
-
const users = (page && page.users) || []
|
|
2738
|
-
if (flags.json) {
|
|
2739
|
-
out.write(
|
|
2740
|
-
JSON.stringify({ transport: 'api', users, nextCursor: (page && page.nextCursor) || null }, null, 2) + '\n',
|
|
2741
|
-
)
|
|
2742
|
-
return 0
|
|
2743
|
-
}
|
|
2744
|
-
if (!users.length) {
|
|
2745
|
-
out.write(`spec-sync users: no match for ${JSON.stringify(query || '')}\n`)
|
|
2746
|
-
return 0
|
|
2747
|
-
}
|
|
2748
|
-
const lines = [`spec-sync users: ${users.length} match(es)`]
|
|
2749
|
-
for (const u of users) {
|
|
2750
|
-
// A deactivated user still resolves by id and can still be assigned, so the
|
|
2751
|
-
// marker is the difference between a valid pick and a silently dead one.
|
|
2752
|
-
const inactive = u && u.active === false ? ' [deactivated]' : ''
|
|
2753
|
-
const email = u && u.email ? ` ${u.email}` : ''
|
|
2754
|
-
lines.push(` ${displayNameOf(u) || '(unnamed)'} <${u && u.id}>${email}${inactive}`)
|
|
2755
|
-
}
|
|
2756
|
-
if (page && page.nextCursor) lines.push(` … more — re-run with --cursor ${page.nextCursor}`)
|
|
2757
|
-
out.write(lines.join('\n') + '\n')
|
|
2758
|
-
return 0
|
|
2759
|
-
}
|
|
2760
2510
|
|
|
2761
2511
|
/**
|
|
2762
2512
|
* `spec-sync apply <spec> --plan <file> [--via api|mcp] [--project <id>]`
|
|
@@ -49,6 +49,7 @@ const {
|
|
|
49
49
|
stampSubIssueId,
|
|
50
50
|
fieldsOf,
|
|
51
51
|
remoteDescriptionEdited,
|
|
52
|
+
remoteSubIssueEdited,
|
|
52
53
|
listPhaseFiles,
|
|
53
54
|
} = require('../../sync-core')
|
|
54
55
|
const { makeSpecHelpers } = require('./specs.js')
|
|
@@ -162,7 +163,16 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
|
|
|
162
163
|
for (const s of projectionOf(snapshotDir, config).subIssues || []) {
|
|
163
164
|
if (s.id != null) refById.set(String(s.id), s.ref)
|
|
164
165
|
}
|
|
166
|
+
// A phase body edited on the tracker gets the same warning as the spec
|
|
167
|
+
// issue. The read is spent only where the snapshot recorded something to
|
|
168
|
+
// compare against, so an old snapshot costs no extra calls.
|
|
169
|
+
const base = readBase(dir, identifier, config)
|
|
165
170
|
for (const sub of (plan.subIssues && plan.subIssues.update) || []) {
|
|
171
|
+
const streams = base && base.subIssueStreams
|
|
172
|
+
if (sub.goal != null && streams && streams[String(sub.id)]) {
|
|
173
|
+
const before = await adapter.readIssue(sub.id)
|
|
174
|
+
if (remoteSubIssueEdited(base, sub.id, before, config) === true) lines.push(ops.remoteEditedLine(sub.id))
|
|
175
|
+
}
|
|
166
176
|
await ops.updateSubIssue(sub)
|
|
167
177
|
result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
|
|
168
178
|
lines.push(` sub-issue updated: ${sub.id}`)
|