@skitterbyte/skitterspec-linear 19.10.0 → 19.12.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/src/env/config.js CHANGED
@@ -49,8 +49,10 @@
49
49
  * // (push + pull request; base moves when the host merges)
50
50
  * guards: { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
51
51
  * teardown: { deleteRemoteBranch },
52
- * live: { migrations: [ "glob", ... ] } // migration globs → `live take`
52
+ * live: { migrations: [ "glob", ... ], // migration globs → `live take`
53
53
  * // refuses a branch that changes them (code-only v1)
54
+ * afterSwitch: [ "cmd" | { run, when } | { setup: true }, ... ] }
55
+ * // run in the primary checkout after `live take`/`release`
54
56
  * hotfix: { bump, cherryPickMain, targets, releaseWith, releaseBranch, tag }
55
57
  * // `hotfix land`: patch-bump the deploy tag, also cherry-pick
56
58
  * // onto the base branch (main), and onto any extra base tags in
@@ -251,6 +253,10 @@ const DEFAULT_CONFIG = Object.freeze({
251
253
  refuseTeardownIfDirty: true,
252
254
  refuseTeardownIfUnpushed: true,
253
255
  mainIsLandingZone: true,
256
+ // A session acts on the project it was started in: writes and lifecycle
257
+ // commands aimed at another skitterspec project are refused
258
+ // (`env/projectguard.js`). On by default, like the main guard.
259
+ projectBoundary: true,
254
260
  }),
255
261
  // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
256
262
  // `spec-env down` does about a branch the USER published by hand — nothing
@@ -328,7 +334,10 @@ const DEFAULT_CONFIG = Object.freeze({
328
334
  // Live overlay (`spec-env live`). `migrations` is a list of globs marking
329
335
  // migration files; a branch that changes any of them is treated as stateful and
330
336
  // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
331
- live: Object.freeze({ migrations: Object.freeze([]) }),
337
+ // `afterSwitch` is `afterLand`'s grammar, run in the primary checkout after a
338
+ // take or a release — a separate list because `afterLand` may hold a data
339
+ // migration, which must never run for a branch that has not landed.
340
+ live: Object.freeze({ migrations: Object.freeze([]), afterSwitch: Object.freeze([]) }),
332
341
  // Hotfix landing (`spec-env hotfix land`). `bump` is the version-bump strategy
333
342
  // for the new deploy tag: "patch" (X.Y.Z -> X.Y.(Z+1)) or "hotfix-suffix"
334
343
  // (X.Y.Z -> X.Y.Z-hotfix.N). The loader keeps whatever string it is given and
@@ -423,7 +432,7 @@ function defaults() {
423
432
  guards: { ...DEFAULT_CONFIG.guards },
424
433
  teardown: { ...DEFAULT_CONFIG.teardown },
425
434
  review: { ...DEFAULT_CONFIG.review, reviewers: [] },
426
- live: { migrations: [] },
435
+ live: { migrations: [], afterSwitch: [] },
427
436
  hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
428
437
  }
429
438
  }
@@ -734,6 +743,7 @@ function mergeConfig(base, parsed) {
734
743
  assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')
735
744
  assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
736
745
  assign(base.guards, parsed.guards, 'mainIsLandingZone', 'boolean')
746
+ assign(base.guards, parsed.guards, 'projectBoundary', 'boolean')
737
747
  }
738
748
 
739
749
  // An unrecognised policy falls through to the default rather than erroring or
@@ -821,6 +831,12 @@ function mergeConfig(base, parsed) {
821
831
  base.live.migrations = normalizeFileList(parsed.live.migrations)
822
832
  }
823
833
 
834
+ // `afterLand`'s grammar and normaliser, `{ setup: true }` included — read
835
+ // after `setup`, which the shorthand expands from.
836
+ if (isObject(parsed.live) && Array.isArray(parsed.live.afterSwitch)) {
837
+ base.live.afterSwitch = normalizeAfterLand(parsed.live.afterSwitch, base.setupTriggers)
838
+ }
839
+
824
840
  if (isObject(parsed.hotfix)) {
825
841
  assign(base.hotfix, parsed.hotfix, 'bump', 'string')
826
842
  assign(base.hotfix, parsed.hotfix, 'cherryPickMain', 'boolean')
@@ -911,6 +927,12 @@ function setProviderConfigFile(rel) {
911
927
  providerConfigFile = rel || null
912
928
  }
913
929
 
930
+ // Is a ticketing provider registered AND configured in this project? The same
931
+ // signal `land.specDocs` defaults on, so the two cannot disagree.
932
+ function providerConfigured(dir) {
933
+ return Boolean(providerConfigFile) && existsSync(join(dir, providerConfigFile))
934
+ }
935
+
914
936
  // An explicit `specDocs` in the file — any value, even one the merge rejected —
915
937
  // is the project's decision; a rejected typo stays on the conservative "trunk"
916
938
  // rather than being promoted to the provider default.
@@ -960,6 +982,7 @@ module.exports = {
960
982
  loadEnvConfig,
961
983
  setProviderEnvDefaults,
962
984
  setProviderConfigFile,
985
+ providerConfigured,
963
986
  resolveServePort,
964
987
  derivedServePort,
965
988
  servePortRoot,
package/src/env/hooks.js CHANGED
@@ -72,6 +72,16 @@ const HOOKS = [
72
72
  matcher: 'Edit|Write|NotebookEdit|MultiEdit',
73
73
  timeout: HOOK_TIMEOUT,
74
74
  },
75
+ {
76
+ // Refuses a write, or a git/engine command, aimed at ANOTHER skitterspec
77
+ // project: a session acts on the project it was started in. Both kinds of
78
+ // tool, so one entry with both matchers rather than two entries sharing a
79
+ // script — a script is how an entry is recognised as ours.
80
+ key: 'project-guard',
81
+ stem: '.claude/hooks/project-guard',
82
+ matcher: 'Edit|Write|NotebookEdit|MultiEdit|Bash',
83
+ timeout: HOOK_TIMEOUT,
84
+ },
75
85
  ].map((h) => ({ ...h, script: `${h.stem}.cjs`, re: hookStemRe(h.stem) }))
76
86
 
77
87
  function isObject(value) {
@@ -1,6 +1,6 @@
1
1
  'use strict'
2
2
 
3
- const { globToRegExp } = require('./glob.js')
3
+ const { planTriggered, noTriggered } = require('./triggered.js')
4
4
  const { shellPath } = require('./project.js')
5
5
 
6
6
  /**
@@ -293,39 +293,10 @@ function planIntegrateDocs(spec, config, ctx) {
293
293
  // The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
294
294
  // primary checkout, standing on base) once the land commands have succeeded.
295
295
  // A blocked plan carries the empty form — nothing landed, so nothing follows.
296
- //
297
- // `range` is the files the land changes: a list (possibly empty) when known,
298
- // null when it is not. Each entry gets a decision — `always` (no `when`),
299
- // `matched` (with the first path that hit), `skipped`, or `unknown` — and
300
- // `commands` is every entry but the skipped ones, in config order.
301
- //
302
- // AN UNKNOWN RANGE RUNS THE CONDITIONAL ENTRIES. A land made elsewhere, or a
303
- // diff git would not answer, says nothing about what changed, and only one
304
- // reading is harmless: a redundant generate costs seconds, a skipped one leaves
305
- // the base red with nothing pointing at why (`.claude/rules/negative-checks.md`
306
- // rule 4). An EMPTY known range is not unknown — a land whose commits touch no
307
- // files is healthy, and it skips them.
296
+ // The decisions, and why an unknown range runs the conditional entries, live
297
+ // in `planTriggered` (`./triggered.js`), shared with `live.afterSwitch`.
308
298
  function afterLandFor(config, cwd, range = null) {
309
- const raw = (config && Array.isArray(config.afterLand)) ? config.afterLand : []
310
- const entries = raw.map((e) => decide(asEntry(e), range))
311
- const commands = entries.filter((e) => e.decision !== 'skipped').map((e) => e.run)
312
- return { cwd: entries.length ? cwd : null, commands, entries, range }
313
- }
314
-
315
- function decide(entry, range) {
316
- if (!entry.when) return { ...entry, decision: 'always', matched: null }
317
- if (range === null) return { ...entry, decision: 'unknown', matched: null }
318
- const res = entry.when.map(globToRegExp)
319
- const matched = range.find((f) => res.some((r) => r.test(f)))
320
- return matched === undefined
321
- ? { ...entry, decision: 'skipped', matched: null }
322
- : { ...entry, decision: 'matched', matched }
323
- }
324
-
325
- // Normalised config holds `{ run, when }`; a pure caller may still hand over
326
- // the plain string an entry is written as.
327
- function asEntry(entry) {
328
- return typeof entry === 'string' ? { run: entry, when: null } : { run: entry.run, when: entry.when || null }
299
+ return planTriggered(config && config.afterLand, cwd, range)
329
300
  }
330
301
 
331
302
  // `changedFiles` from a planner's ctx, with anything that is not a list read as
@@ -335,7 +306,7 @@ function rangeOf(ctx) {
335
306
  }
336
307
 
337
308
  function noAfterLand() {
338
- return { cwd: null, commands: [], entries: [], range: null }
309
+ return noTriggered()
339
310
  }
340
311
 
341
312
  module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs, afterLandFor, rangeOf }
package/src/env/live.js CHANGED
@@ -18,8 +18,10 @@
18
18
 
19
19
  const fs = require('node:fs')
20
20
  const path = require('node:path')
21
+ const { spawnSync } = require('node:child_process')
21
22
  const { globToRegExp } = require('./glob.js')
22
23
  const { shellPath } = require('./project.js')
24
+ const { planTriggered, noTriggered } = require('./triggered.js')
23
25
 
24
26
  const REQUIRED = ['spec', 'branch', 'holder', 'heldSince', 'baseMainCommit']
25
27
 
@@ -215,6 +217,15 @@ function restartReminders(names, when) {
215
217
  return names.map((name) => `restart ${name} ${when} — it does not hot-reload`)
216
218
  }
217
219
 
220
+ // `live.afterSwitch` decided for one switch, to run in the primary checkout.
221
+ // Anything but a list in `changedFiles` is an unknown range — a caller that
222
+ // did not supply it said nothing about what changed.
223
+ function afterSwitchFor(config, c) {
224
+ const raw = config && config.live ? config.live.afterSwitch : []
225
+ const range = Array.isArray(c.changedFiles) ? c.changedFiles : null
226
+ return planTriggered(raw, c.primaryPath, range)
227
+ }
228
+
218
229
  // --- take planner ---------------------------------------------------------
219
230
 
220
231
  /**
@@ -245,9 +256,14 @@ function restartReminders(names, when) {
245
256
  * probed, each named in a restart reminder instead
246
257
  * migrationsHit boolean — the branch diff touches configured migration globs
247
258
  * depsChanged boolean — the branch diff touches a lockfile/manifest (→ warn)
259
+ * changedFiles string[] — the files `onto...branch` changes, or anything
260
+ * else (null) when git would not say: decides `afterSwitch`
248
261
  * holder,heldSince receipt provenance (injected by the CLI; no Date.now here)
249
262
  *
250
- * @returns {object} { blocked, reason, commands, warnings, receipt, base, branch, worktreePath }
263
+ * @returns {object} { blocked, reason, commands, warnings, receipt, base, branch,
264
+ * worktreePath, afterSwitch } — `afterSwitch` is `config.live.afterSwitch`
265
+ * decided against `changedFiles`, to run in the primary checkout after the
266
+ * checkout; empty on a refusal, since nothing switched.
251
267
  */
252
268
  function planTake(spec, config, ctx) {
253
269
  const c = ctx || {}
@@ -263,6 +279,7 @@ function planTake(spec, config, ctx) {
263
279
  onto: c.rebaseOnto || base,
264
280
  branch,
265
281
  worktreePath: spec.worktreePath,
282
+ afterSwitch: noTriggered(),
266
283
  }
267
284
  /**
268
285
  * A refusal, and — only where one exists — the way out of it.
@@ -385,6 +402,7 @@ function planTake(spec, config, ctx) {
385
402
  `git -C ${shellPath(c.primaryPath)} checkout ${branch}`,
386
403
  ],
387
404
  warnings,
405
+ afterSwitch: afterSwitchFor(config, c),
388
406
  receipt: {
389
407
  spec: spec.folder,
390
408
  branch,
@@ -405,8 +423,12 @@ function planTake(spec, config, ctx) {
405
423
  * In the branch-switch model `take` never moves the base ref, so release is just
406
424
  * `checkout base` (frees the branch) then re-attach it to the worktree — no reset.
407
425
  *
408
- * ctx: { primary:{onBase,branch}, primaryPath, base, clean, worktreeExists, restartApps }
409
- * @returns {object} { blocked, noop, reason, commands, warnings, clears, base, branch, worktreePath }
426
+ * ctx: { primary:{onBase,branch}, primaryPath, base, clean, worktreeExists, restartApps,
427
+ * changedFiles }
428
+ * `changedFiles` is `base...branch` — the same files take brought in, which the
429
+ * switch back reverts, so `afterSwitch` is decided against the same set.
430
+ * @returns {object} { blocked, noop, reason, commands, warnings, clears, base, branch,
431
+ * worktreePath, afterSwitch }
410
432
  */
411
433
  function planRelease(spec, config, ctx) {
412
434
  const c = ctx || {}
@@ -422,6 +444,7 @@ function planRelease(spec, config, ctx) {
422
444
  base,
423
445
  branch,
424
446
  worktreePath: spec.worktreePath,
447
+ afterSwitch: noTriggered(),
425
448
  }
426
449
 
427
450
  // Nothing live — the primary checkout is already on base.
@@ -448,7 +471,7 @@ function planRelease(spec, config, ctx) {
448
471
  const commands = [`git -C ${shellPath(c.primaryPath)} checkout ${base}`]
449
472
  if (c.worktreeExists) commands.push(`git -C ${shellPath(spec.worktreePath)} switch ${branch}`)
450
473
  const warnings = restartReminders(Array.isArray(c.restartApps) ? c.restartApps : [], `on ${base}`)
451
- return { ...result, commands, warnings, clears: true }
474
+ return { ...result, commands, warnings, clears: true, afterSwitch: afterSwitchFor(config, c) }
452
475
  }
453
476
 
454
477
  // --- abort planner --------------------------------------------------------
@@ -503,7 +526,86 @@ function planAbort(config, ctx) {
503
526
  return { ...result, commands, clears: true, branch }
504
527
  }
505
528
 
529
+ // --- after-switch runner --------------------------------------------------
530
+
531
+ // How much of a failed command's output to show — enough to see why, not a
532
+ // whole install log in a report that is relayed verbatim.
533
+ const FAIL_TAIL = 20
534
+
535
+ /**
536
+ * Run a plan's `afterSwitch` commands in order, in its `cwd` (the primary
537
+ * checkout), and return the lines that report them. The ENGINE runs these,
538
+ * unlike `afterLand`: `/spec-live` and the page's live action are pre-executed
539
+ * with no caller turn to run anything after them.
540
+ *
541
+ * Output is CAPTURED, not streamed — the report is relayed verbatim, so a full
542
+ * install log would bury it. Only a failure shows output, and only its tail.
543
+ *
544
+ * STOPS AT THE FIRST FAILURE AND NEVER UNDOES THE SWITCH. Rolling the branch
545
+ * back over a failed install would hide the cause and swap one broken tree for
546
+ * another; the operator is told what failed and what did not run.
547
+ *
548
+ * An empty list returns no lines at all, so a project without the key prints
549
+ * exactly what it printed before the key existed.
550
+ *
551
+ * @param {object} afterSwitch a planner's `afterSwitch` ({ cwd, commands, entries, range })
552
+ * @param {function} [spawn] spawnSync-shaped, injectable for tests
553
+ * @returns {{ lines: string[], failed: boolean }}
554
+ */
555
+ function runAfterSwitch(afterSwitch, spawn = spawnSync) {
556
+ const entries = afterSwitch && Array.isArray(afterSwitch.entries) ? afterSwitch.entries : []
557
+ if (!entries.length) return { lines: [], failed: false }
558
+ const cwd = afterSwitch.cwd
559
+ const toRun = entries.filter((e) => e.decision !== 'skipped')
560
+ const skipped = entries.filter((e) => e.decision === 'skipped')
561
+ const width = Math.max(...entries.map((e) => e.run.length))
562
+ // A shell COMMENT for the reason, as `afterLand` prints it, so a line copied
563
+ // out of the report is still one command.
564
+ const why = (e) =>
565
+ e.decision === 'matched' ? ` # ${e.matched} changed` : e.decision === 'unknown' ? ' # range unknown' : ''
566
+ const lines = []
567
+ let failed = false
568
+
569
+ if (!toRun.length) {
570
+ lines.push(` after switch (in ${cwd}): nothing to run.`)
571
+ } else {
572
+ lines.push(` after switch (in ${cwd}):`)
573
+ for (let i = 0; i < toRun.length; i++) {
574
+ const e = toRun[i]
575
+ const res = spawn(e.run, {
576
+ cwd,
577
+ shell: true,
578
+ stdio: ['ignore', 'pipe', 'pipe'],
579
+ encoding: 'utf8',
580
+ maxBuffer: 64 * 1024 * 1024,
581
+ })
582
+ if (!res.error && res.status === 0) {
583
+ lines.push(` ran: ${why(e) ? e.run.padEnd(width) + why(e) : e.run}`)
584
+ continue
585
+ }
586
+ failed = true
587
+ const status = res.error ? res.error.message : res.signal ? `signal ${res.signal}` : `exit ${res.status}`
588
+ lines.push(` ! after switch: ${e.run} failed (${status}) — the switch stands; fix it in ${cwd}`)
589
+ // Joined on a newline: stdout without a trailing one would otherwise run
590
+ // its last line into stderr's first.
591
+ const output = `${res.stdout || ''}\n${res.stderr || ''}`.split('\n').filter((l) => l.trim())
592
+ for (const l of output.slice(-FAIL_TAIL)) lines.push(` ${l}`)
593
+ for (const rest of toRun.slice(i + 1)) lines.push(` not run: ${rest.run}`)
594
+ break
595
+ }
596
+ }
597
+ if (toRun.some((e) => e.decision === 'unknown')) {
598
+ lines.push(" the switch's changed files are unknown here, so the conditional entries run.")
599
+ }
600
+ if (skipped.length) {
601
+ lines.push(' skipped (nothing in the switch matched):')
602
+ for (const e of skipped) lines.push(` ${e.run.padEnd(width)} # when ${e.when.join(', ')}`)
603
+ }
604
+ return { lines, failed }
605
+ }
606
+
506
607
  module.exports = {
608
+ runAfterSwitch,
507
609
  receiptPath,
508
610
  renderReceipt,
509
611
  readReceipt,