@skitterbyte/skitterspec-linear 19.9.1 → 19.10.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.
@@ -161,7 +161,10 @@ through to a documented conservative default; see the field notes below.
161
161
  // An entry may also be { "run": "<cmd>", "when": ["<glob>", ...] }. `when` is
162
162
  // IGNORED here — a fresh worktree always runs every setup step — and exists
163
163
  // so `afterLand` can re-run that step after a land that changes its inputs
164
- // (`{ "setup": true }`, below).
164
+ // (`{ "setup": true }`, below), and so `live take` warns to restart the dev
165
+ // server when a branch changes one of those files. Name your stack's
166
+ // manifests here, e.g. { "run": "dotnet restore", "when": ["**/*.csproj",
167
+ // "Directory.Packages.props"] } — the npm/pnpm/yarn files always count.
165
168
  "setup": [],
166
169
 
167
170
  // Commands to run in the PRIMARY checkout after a land — the counterpart of
@@ -239,6 +242,13 @@ through to a documented conservative default; see the field notes below.
239
242
  // {portVar}/{port} expand here too. Omit for no health gate.
240
243
  // frontPort optional canonical origin this process fronts (e.g. 3000 for the
241
244
  // UI, 8080 for the API) — used by the proxy to route to it.
245
+ // reload "hot" (default) or "restart". `live take` probes a hot entry's
246
+ // frontPort and refuses when nothing answers. A "restart" entry —
247
+ // an API run from Visual Studio or Rider — is never probed: take
248
+ // and release name it to restart instead. An unrecognised value
249
+ // reads as "hot". e.g. { "name": "api", "command": "dotnet run",
250
+ // "portVar": "ASPNETCORE_HTTP_PORTS", "frontPort": 5000,
251
+ // "reload": "restart" }
242
252
  "dev": [],
243
253
 
244
254
  // Front-door proxy for `spec-env connect <spec>` — a small bundled Node
@@ -398,6 +408,14 @@ through to a documented conservative default; see the field notes below.
398
408
  // `migrations` is a list of globs (`**`, `*`, `?`) marking migration files; a
399
409
  // branch that changes any of them is treated as STATEFUL and `live take`
400
410
  // refuses it (code-only v1 — use `/spec-connect` for those). Default: none.
411
+ // Nothing is detected for you: an EF Core project wants
412
+ // ["**/Migrations/**"], so a spec adding a migration is refused rather than
413
+ // applied to the shared dev database.
414
+ // A branch changing a manifest a `setup` entry's `when` names (or an npm
415
+ // lockfile) is let through with a "restart your dev server" warning.
416
+ // Under `land.strategy: "pr"` take fetches and rebases onto
417
+ // `<land.remote>/<base>`, since local base moves only when you pull; a
418
+ // failed fetch falls back to local base and says so.
401
419
  "live": {
402
420
  "migrations": []
403
421
  },
@@ -236,7 +236,8 @@ when `env.config.json` is absent — every skill then behaves as it does today.
236
236
  runs a spec's *own* dev stack and proxies the canonical ports to it (one stack per
237
237
  spec). **Live overlay** instead reuses the one dev server you already have running:
238
238
  `/spec-live <spec>` — or a bare `/spec-live`, which takes the spec you are
239
- standing on — rebases the branch onto base, frees it from its worktree, and
239
+ standing on — rebases the branch onto base (the fetched remote base under PR
240
+ landing), frees it from its worktree, and
240
241
  checks it out **in the primary checkout**, so your running server hot-reloads the
241
242
  feature at the normal URL — no second stack, no proxy. Bare only acts when there
242
243
  is exactly one answer *and* the workbench is free; anything else prints the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.9.1",
3
+ "version": "19.10.0",
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
@@ -99,6 +99,7 @@ const {
99
99
  clearReceipt,
100
100
  summarizeReceipt,
101
101
  migrationsHit,
102
+ depsChanged,
102
103
  planTake,
103
104
  liveStateFor,
104
105
  liveStateLine,
@@ -7071,9 +7072,6 @@ function runGit(cwd, args) {
7071
7072
  }
7072
7073
  }
7073
7074
 
7074
- // Lockfiles/manifests whose change means a dev server needs a restart, not HMR.
7075
- const DEPS_RE = /(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$/
7076
-
7077
7075
  // Live overlay: test a spec on the already-running instance by checking its
7078
7076
  // branch out in the primary checkout, so the running dev server hot-reloads the
7079
7077
  // feature. The branch that's checked out IS the lock (assertPrimaryOnMain); the
@@ -7192,6 +7190,30 @@ function bareLive(dir, config) {
7192
7190
  return { action: 'take', specArg: choice.folder }
7193
7191
  }
7194
7192
 
7193
+ // What `live take` rebases onto. Under PR landing the base branch moves only
7194
+ // when the host merges, so local base is as stale as the last pull: fetch and
7195
+ // rebase onto `<remote>/<base>`, which is also what the landing rebase targets.
7196
+ // The take already rewrites the branch on every run, and the PR push is
7197
+ // `--force-with-lease`, so this puts nothing new at risk. Trunk landing keeps
7198
+ // local base — there the base branch is local work.
7199
+ //
7200
+ // WHAT WOULD FOOL THIS: a failed fetch (offline, no such remote, no such branch
7201
+ // there) says nothing about whether the remote base moved. That is cannot-tell,
7202
+ // so it falls back to local base and says so — never a refusal.
7203
+ function liveRebaseTarget(dir, config, base) {
7204
+ if (config.land.strategy !== 'pr') return { onto: base, note: null }
7205
+ const remote = baseRemote(config)
7206
+ const onto = `${remote}/${base}`
7207
+ const fetched = runGit(dir, ['fetch', remote, base]).ok
7208
+ if (fetched && gitReader(dir)(['rev-parse', '--verify', '--quiet', `refs/remotes/${onto}`])) {
7209
+ return { onto, note: null }
7210
+ }
7211
+ return {
7212
+ onto: base,
7213
+ note: `could not fetch ${onto} — rebased onto local ${base}, which may be behind the remote`,
7214
+ }
7215
+ }
7216
+
7195
7217
  // Take the running instance: rebase the spec's branch onto base, free it from its
7196
7218
  // worktree, and check it out in the primary checkout so the dev server reloads it.
7197
7219
  async function specEnvLiveTake(dir, config, specArg, flags = {}) {
@@ -7209,15 +7231,21 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7209
7231
  const wtStatus = worktreeExists ? gitReader(spec.worktreePath)(['status', '--porcelain']) : ''
7210
7232
  const worktreeClean = wtStatus !== null && wtStatus.length === 0
7211
7233
  const baseMainCommit = primaryGit(['rev-parse', 'HEAD'])
7234
+ const { onto, note: rebaseNote } = liveRebaseTarget(dir, config, base)
7212
7235
 
7213
- // Diff base...branch to spot migration / dependency changes (best-effort).
7214
- const changed = primaryGit(['diff', '--name-only', `${base}...${spec.branch}`])
7236
+ // Diff onto...branch to spot migration / dependency changes (best-effort) —
7237
+ // against the target the rebase will replay over, so both read the same commits.
7238
+ const changed = primaryGit(['diff', '--name-only', `${onto}...${spec.branch}`])
7215
7239
  const files = changed ? changed.split('\n').filter(Boolean) : []
7216
- const depsChanged = files.some((f) => DEPS_RE.test(f))
7217
-
7218
- // Verify-only: probe the declared canonical (frontPort) ports. None declared →
7219
- // no health gate (serverUp = null); the switch proceeds with a warning.
7220
- const canonicalPorts = config.dev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
7240
+ const depsHit = depsChanged(files, config.setupTriggers)
7241
+
7242
+ // Verify-only: probe the declared canonical (frontPort) ports of the HOT dev
7243
+ // entries. None declared → no health gate (serverUp = null); the switch
7244
+ // proceeds with a warning. A `reload: "restart"` entry is never probed: an
7245
+ // IDE-hosted app that is not running is the normal state, not a refusal.
7246
+ const hotDev = config.dev.filter((d) => d.reload !== 'restart')
7247
+ const restartApps = config.dev.filter((d) => d.reload === 'restart').map((d) => d.name)
7248
+ const canonicalPorts = hotDev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
7221
7249
  let serverUp = null
7222
7250
  if (canonicalPorts.length) {
7223
7251
  const up = await portsAnswering(canonicalPorts, config.proxy.host)
@@ -7233,10 +7261,13 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7233
7261
  worktreeExists,
7234
7262
  base,
7235
7263
  baseMainCommit,
7264
+ rebaseOnto: onto,
7265
+ rebaseNote,
7236
7266
  serverUp,
7237
7267
  canonicalPorts,
7268
+ restartApps,
7238
7269
  migrationsHit: migrationsHit(files, config.live.migrations),
7239
- depsChanged,
7270
+ depsChanged: depsHit,
7240
7271
  holder: primaryGit(['config', 'user.name']) || 'unknown',
7241
7272
  heldSince: new Date().toISOString(),
7242
7273
  })
@@ -7274,7 +7305,7 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7274
7305
  }
7275
7306
 
7276
7307
  // Execute the switch. Rebase first; on conflict, abort and bail (state untouched).
7277
- const reb = runGit(spec.worktreePath, ['rebase', base])
7308
+ const reb = runGit(spec.worktreePath, ['rebase', onto])
7278
7309
  if (!reb.ok) {
7279
7310
  // A rebase fails two ways and they need different answers. It can REFUSE TO
7280
7311
  // START (unstaged changes, a missing base) — nothing to abort, nothing to
@@ -7285,9 +7316,9 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7285
7316
  if (started) runGit(spec.worktreePath, ['rebase', '--abort'])
7286
7317
  process.stdout.write(
7287
7318
  started
7288
- ? `spec-env live take: rebase of ${spec.branch} onto ${base} hit conflicts — ` +
7319
+ ? `spec-env live take: rebase of ${spec.branch} onto ${onto} hit conflicts — ` +
7289
7320
  `resolve them in ${spec.worktreePath}, then retry.\n`
7290
- : `spec-env live take: rebase of ${spec.branch} onto ${base} could not start — ` +
7321
+ : `spec-env live take: rebase of ${spec.branch} onto ${onto} could not start — ` +
7291
7322
  `git said:\n ${reb.err.split('\n').join('\n ')}\n`,
7292
7323
  )
7293
7324
  return
@@ -7313,6 +7344,7 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7313
7344
  out.push('')
7314
7345
  out.push(` primary: now on ${receipt.branch} (was ${base} @ ${receipt.baseMainCommit.slice(0, 7)})`)
7315
7346
  out.push(` worktree: ${spec.worktreePath} (detached — branch handed to the primary checkout)`)
7347
+ if (onto !== base) out.push(` rebased: onto ${onto} (PR landing — the remote base)`)
7316
7348
  for (const w of plan.warnings) out.push(` ! ${w}`)
7317
7349
  out.push('')
7318
7350
  out.push(' Test at your canonical URL; release with: /spec-live main')
@@ -7351,6 +7383,7 @@ async function specEnvLiveRelease(dir, config, specArg) {
7351
7383
  base,
7352
7384
  clean,
7353
7385
  worktreeExists,
7386
+ restartApps: config.dev.filter((d) => d.reload === 'restart').map((d) => d.name),
7354
7387
  })
7355
7388
 
7356
7389
  if (plan.noop) {
@@ -7372,7 +7405,8 @@ async function specEnvLiveRelease(dir, config, specArg) {
7372
7405
 
7373
7406
  process.stdout.write(
7374
7407
  `spec-env live release: ${spec.folder} released — primary back on ${base}, ` +
7375
- `${spec.branch} re-isolated to its worktree.\n`,
7408
+ `${spec.branch} re-isolated to its worktree.\n` +
7409
+ plan.warnings.map((w) => ` ! ${w}\n`).join(''),
7376
7410
  )
7377
7411
  }
7378
7412
 
package/src/env/config.js CHANGED
@@ -32,8 +32,9 @@
32
32
  * // `when` globs gate an entry on the land's changed files, and
33
33
  * // `{ setup: true }` expands to `setupTriggers`; literal, no
34
34
  * // token expansion; normalised to `{ run, when }`; empty = none
35
- * dev: [ { name, command, portVar, health?, frontPort? } ], // host dev
36
- * // servers started on the spec's port block (empty = none)
35
+ * dev: [ { name, command, portVar, health?, frontPort?, reload } ], // host dev
36
+ * // servers started on the spec's port block (empty = none);
37
+ * // reload "hot" (default) | "restart" (IDE-hosted, `live` reminds)
37
38
  * proxy: { enabled, host }, // bundled front-door proxy (spec-env connect)
38
39
  * registry: ".spec-env/registry.json",
39
40
  * branch: { pattern, identifierField }, // git branch naming (provider-neutral)
@@ -462,6 +463,9 @@ function normalizeDev(parsed) {
462
463
  if (typeof raw.frontPort === 'number' && Number.isFinite(raw.frontPort)) {
463
464
  entry.frontPort = raw.frontPort
464
465
  }
466
+ // An unrecognised value falls through to "hot", the conservative reading:
467
+ // a typo keeps `live take`'s listening check rather than silently dropping it.
468
+ entry.reload = raw.reload === 'restart' ? 'restart' : 'hot'
465
469
  out.push(entry)
466
470
  }
467
471
  return out
package/src/env/live.js CHANGED
@@ -190,6 +190,31 @@ function migrationsHit(files, patterns) {
190
190
  return files.some((f) => res.some((r) => r.test(f)))
191
191
  }
192
192
 
193
+ // Lockfiles/manifests whose change means a dev server needs a restart, not HMR.
194
+ // Always checked, so a project whose `when` globs name only (say) a schema file
195
+ // keeps the warning it had before those globs existed.
196
+ const DEPS_RE = /(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$/
197
+
198
+ // True when the branch changes a dependency manifest: the npm set above, or any
199
+ // file a `setup` entry's `when` globs name. Those globs are the project saying
200
+ // "this file changing means setup must re-run" — a .csproj, a go.mod — and a
201
+ // change that needs setup re-run needs the running app restarted for the same
202
+ // reason. Reading them keeps the engine ignorant of what stack it is in.
203
+ function depsChanged(files, setupTriggers) {
204
+ if (!Array.isArray(files) || !files.length) return false
205
+ const globs = (Array.isArray(setupTriggers) ? setupTriggers : []).flatMap((t) =>
206
+ t && Array.isArray(t.when) ? t.when : [],
207
+ )
208
+ const res = globs.map(globToRegExp)
209
+ return files.some((f) => DEPS_RE.test(f) || res.some((r) => r.test(f)))
210
+ }
211
+
212
+ // One reminder per `reload: "restart"` dev entry — an IDE-hosted app sees the
213
+ // branch switch on disk but runs the old build until someone restarts it.
214
+ function restartReminders(names, when) {
215
+ return names.map((name) => `restart ${name} ${when} — it does not hot-reload`)
216
+ }
217
+
193
218
  // --- take planner ---------------------------------------------------------
194
219
 
195
220
  /**
@@ -208,10 +233,16 @@ function migrationsHit(files, patterns) {
208
233
  * clean boolean — primary checkout working tree is clean
209
234
  * worktreeClean boolean — the SPEC WORKTREE's tree is clean (the rebase runs there)
210
235
  * worktreeExists boolean — the spec's worktree is on disk
211
- * base resolved base branch name (rebase target)
236
+ * base resolved base branch name (the workbench release returns to)
237
+ * rebaseOnto the rebase target — `<remote>/<base>` under PR landing,
238
+ * else omitted, meaning `base`
239
+ * rebaseNote string|null — why the target fell back to local base
212
240
  * baseMainCommit primary HEAD before the switch (receipt / crash recovery)
213
241
  * serverUp true | false | null — null = no canonical ports declared → no gate
214
- * canonicalPorts number[] — declared canonical (frontPort) ports, for messages
242
+ * canonicalPorts number[] — declared canonical (frontPort) ports of the HOT
243
+ * dev entries, for messages
244
+ * restartApps string[] — names of `reload: "restart"` dev entries; never
245
+ * probed, each named in a restart reminder instead
215
246
  * migrationsHit boolean — the branch diff touches configured migration globs
216
247
  * depsChanged boolean — the branch diff touches a lockfile/manifest (→ warn)
217
248
  * holder,heldSince receipt provenance (injected by the CLI; no Date.now here)
@@ -229,6 +260,7 @@ function planTake(spec, config, ctx) {
229
260
  warnings: [],
230
261
  receipt: null,
231
262
  base,
263
+ onto: c.rebaseOnto || base,
232
264
  branch,
233
265
  worktreePath: spec.worktreePath,
234
266
  }
@@ -332,17 +364,23 @@ function planTake(spec, config, ctx) {
332
364
  }
333
365
 
334
366
  const warnings = []
367
+ const restartApps = Array.isArray(c.restartApps) ? c.restartApps : []
335
368
  if (c.depsChanged) {
336
369
  warnings.push('dependencies changed on this branch — restart your dev server after the switch')
337
370
  }
338
- if (c.serverUp === null) {
371
+ // An app that restarts rather than hot-reloads is the operator's to restart,
372
+ // so its absence from the ports is the normal state — the IDE is closed, or
373
+ // will be restarted anyway — and "nothing to hot-reload" would only mislead.
374
+ if (c.serverUp === null && !restartApps.length) {
339
375
  warnings.push('no canonical dev ports configured — nothing to hot-reload; switching anyway')
340
376
  }
377
+ warnings.push(...restartReminders(restartApps, 'after the switch'))
378
+ if (c.rebaseNote) warnings.push(c.rebaseNote)
341
379
 
342
380
  return {
343
381
  ...result,
344
382
  commands: [
345
- `git -C ${shellPath(spec.worktreePath)} rebase ${base}`,
383
+ `git -C ${shellPath(spec.worktreePath)} rebase ${c.rebaseOnto || base}`,
346
384
  `git -C ${shellPath(spec.worktreePath)} switch --detach`,
347
385
  `git -C ${shellPath(c.primaryPath)} checkout ${branch}`,
348
386
  ],
@@ -367,8 +405,8 @@ function planTake(spec, config, ctx) {
367
405
  * In the branch-switch model `take` never moves the base ref, so release is just
368
406
  * `checkout base` (frees the branch) then re-attach it to the worktree — no reset.
369
407
  *
370
- * ctx: { primary:{onBase,branch}, primaryPath, base, clean, worktreeExists }
371
- * @returns {object} { blocked, noop, reason, commands, clears, base, branch, worktreePath }
408
+ * ctx: { primary:{onBase,branch}, primaryPath, base, clean, worktreeExists, restartApps }
409
+ * @returns {object} { blocked, noop, reason, commands, warnings, clears, base, branch, worktreePath }
372
410
  */
373
411
  function planRelease(spec, config, ctx) {
374
412
  const c = ctx || {}
@@ -379,6 +417,7 @@ function planRelease(spec, config, ctx) {
379
417
  noop: false,
380
418
  reason: null,
381
419
  commands: [],
420
+ warnings: [],
382
421
  clears: false,
383
422
  base,
384
423
  branch,
@@ -408,7 +447,8 @@ function planRelease(spec, config, ctx) {
408
447
 
409
448
  const commands = [`git -C ${shellPath(c.primaryPath)} checkout ${base}`]
410
449
  if (c.worktreeExists) commands.push(`git -C ${shellPath(spec.worktreePath)} switch ${branch}`)
411
- return { ...result, commands, clears: true }
450
+ const warnings = restartReminders(Array.isArray(c.restartApps) ? c.restartApps : [], `on ${base}`)
451
+ return { ...result, commands, warnings, clears: true }
412
452
  }
413
453
 
414
454
  // --- abort planner --------------------------------------------------------
@@ -472,6 +512,7 @@ module.exports = {
472
512
  summarizeReceipt,
473
513
  globToRegExp,
474
514
  migrationsHit,
515
+ depsChanged,
475
516
  planTake,
476
517
  planRelease,
477
518
  planAbort,