@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 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, ...; a base
296
- // that is already a hotfix tag continues its line). Any other value is refused
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.0",
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 { renderRoutes, portsInUse, portsInUseOn, waitListening } = require('./env/proxy.js')
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-jira',
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 portsInUse(routes.map((r) => r.frontPort), config.proxy.host)
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 portsInUse(canonicalPorts, config.proxy.host)
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') return bumpPatch(baseTag)
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 — bump the base version or delete the stale tag`)
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 — resolve it before landing`)
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}`)