@skitterbyte/skitterspec-linear 19.9.1 → 19.11.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/cli.js CHANGED
@@ -48,6 +48,7 @@ const SPEC_ENV_VERBS = Object.freeze([
48
48
  'base',
49
49
  'nospec',
50
50
  'main',
51
+ 'project',
51
52
  ])
52
53
  const { forkMatch, planBaseReport } = require('./env/base.js')
53
54
  const {
@@ -99,10 +100,12 @@ const {
99
100
  clearReceipt,
100
101
  summarizeReceipt,
101
102
  migrationsHit,
103
+ depsChanged,
102
104
  planTake,
103
105
  liveStateFor,
104
106
  liveStateLine,
105
107
  planRelease,
108
+ runAfterSwitch,
106
109
  planAbort,
107
110
  } = require('./env/live.js')
108
111
  const { ensureWorktreeDirTrusted } = require('./env/trust.js')
@@ -214,8 +217,16 @@ const { ROUTE: TADA_ROUTE, tadaQuery, recapKey: tadaRecapKey, recapPath: tadaRec
214
217
  const { defaultRoot, knownDirs } = require('./tada/transcripts.js')
215
218
  const { setProjectKeys } = require('./env/projectedit.js')
216
219
  const { buildDigest, gitRepoOf } = require('./tada/digest.js')
220
+ const {
221
+ readAllows: readProjectAllows,
222
+ checkPath: checkProjectPath,
223
+ checkCommand: checkProjectCommand,
224
+ recordLift: recordProjectLift,
225
+ clearLift: clearProjectLift,
226
+ } = require('./env/projectguard.js')
217
227
  const { readRepoFacts } = require('./tada/repo.js')
218
228
  const { formatTada } = require('./tada/format.js')
229
+ const { LOOKBACK_DAYS, activityTimes, lastActiveDay, readBlockers, buildTodo, formatTodo } = require('./tada/todo.js')
219
230
  const { renderTadaPage } = require('./tada/page.js')
220
231
  const { startProcess, stopProcess, waitHealthy, readPid, isAlive } = require('./env/supervise.js')
221
232
  const {
@@ -288,6 +299,10 @@ Usage:
288
299
  main <check|allow|status>
289
300
  the main guard — is a write about to land
290
301
  on the base branch? (/allow-main lifts it)
302
+ project <check|allow|status>
303
+ the project guard — is a write or a lifecycle
304
+ command aimed at another skitterspec project?
305
+ (/allow-project <name> lifts it)
291
306
  down <spec> tear down (guards; --keep-volumes, --force)
292
307
  prune reap orphaned test-DB volumes (--older-than <days>)
293
308
  dev up <spec> start host dev servers on the spec's ports
@@ -356,6 +371,12 @@ Usage:
356
371
  --json, --page [--summary <recap.md>] for an HTML
357
372
  page. Reads ~/.claude/projects; exits 0 unless the
358
373
  window cannot be read.
374
+ skitterspec todo Where you left off: each project as it stood on
375
+ the last day with activity (up to 14 days back),
376
+ its open specs and next actions, review verdicts
377
+ waiting and gates armed, and today so far. Same
378
+ scope as tada (--here, --all-projects), --json,
379
+ --page [--summary <recap.md>].
359
380
  skitterspec gating <cmd> Release-gating check (opt-in; needs
360
381
  specs/.core/gating.config.json). Subcommands:
361
382
  check [spec] report specs with no recorded gating
@@ -812,12 +833,38 @@ async function tadaCommand(argv) {
812
833
  // nothing else, because the digest it carries was already read once.
813
834
  if (await serveTadaPage({ window, flags, recap })) return
814
835
  }
815
- const digest = await buildDigest({
836
+ const digest = await tadaDigest(window, flags)
837
+ // The reader's own dates, for the text header and the page; the digest's
838
+ // own `since`/`until` stay UTC instants for a script.
839
+ digest.window.label = humanLabel(window)
840
+ if (argv.includes('--page')) {
841
+ // No server to serve it: the page is a file on this machine, as it was.
842
+ const out = path.join(os.tmpdir(), `skitterspec-tada-${windowLabel(window).replace(' → ', '_')}.html`)
843
+ fs.writeFileSync(out, renderTadaPage(digest, { recap, title: `Ta-da · ${digest.window.label}`, category: digest.category || null }))
844
+ process.stdout.write(`page: ${pathToFileURL(out).href}\n`)
845
+ return
846
+ }
847
+ if (json) {
848
+ process.stdout.write(JSON.stringify(digest, null, 2) + '\n')
849
+ return
850
+ }
851
+ process.stdout.write(formatTada(digest))
852
+ }
853
+
854
+ /**
855
+ * One window's digest, scoped the way `tada` and `todo` both scope it: the
856
+ * running project's category unless `--all-projects`, the repo alone under
857
+ * `--here`, and the run's own cwd as home. `open: false` skips the in-flight
858
+ * rows, for a scan that only asks when something happened.
859
+ */
860
+ async function tadaDigest(window, flags, { chat = flags.chat, open = true } = {}) {
861
+ return buildDigest({
816
862
  root: defaultRoot(),
817
863
  window,
818
864
  here: flags.here ? process.cwd() : null,
865
+ home: process.cwd(),
819
866
  category: flags.all ? null : runningCategory(process.cwd()),
820
- chat: flags.chat,
867
+ chat,
821
868
  facts: (repo) => {
822
869
  let config = {}
823
870
  try {
@@ -828,31 +875,92 @@ async function tadaCommand(argv) {
828
875
  }
829
876
  return readRepoFacts({ repo, git: gitReader(repo), config, window })
830
877
  },
831
- openFor: (repo) => {
832
- try {
833
- return inFlightRows(repo)
834
- .rows.filter(isInFlight)
835
- .map((r) => ({ spec: r.spec, detail: detailOf(r), next: r.next ? actionText(r.next) : null }))
836
- } catch {
837
- return []
838
- }
839
- },
878
+ openFor: open ? openSpecsIn : null,
840
879
  })
841
- // The reader's own dates, for the text header and the page; the digest's
842
- // own `since`/`until` stay UTC instants for a script.
843
- digest.window.label = humanLabel(window)
880
+ }
881
+
882
+ function openSpecsIn(repo) {
883
+ try {
884
+ return inFlightRows(repo)
885
+ .rows.filter(isInFlight)
886
+ .map((r) => ({ spec: r.spec, detail: detailOf(r), next: r.next ? actionText(r.next) : null }))
887
+ } catch {
888
+ return []
889
+ }
890
+ }
891
+
892
+ /**
893
+ * What stands in one repo's way, read off its review store: passes waiting
894
+ * and gates armed, for the specs in flight there. Read-only, and every
895
+ * cannot-tell — no config, no store, an unreadable sidecar — is nothing at all
896
+ * rather than a blocker (`.claude/rules/negative-checks.md`).
897
+ */
898
+ function repoBlockers(repo, specs) {
899
+ let config
900
+ try {
901
+ config = loadEnvConfig(repo).config
902
+ } catch {
903
+ return []
904
+ }
905
+ return readBlockers(reviewsDirFor(repo, config), specs, config.review && config.review.required)
906
+ }
907
+
908
+ /**
909
+ * `skitterspec todo` — the morning half of the ta-da list: where each project
910
+ * was left on the last day with any activity, what is ahead, and what is in
911
+ * the way. Exits 0 whatever it finds, a fortnight of nothing included.
912
+ */
913
+ async function todoCommand(argv) {
914
+ const now = new Date()
915
+ const flags = { on: null, since: null, all: argv.includes('--all-projects'), chat: false, here: argv.includes('--here') }
916
+ const today = windowFor({}, now)
917
+ // One scan of the lookback finds the day; only that day is read in full.
918
+ const lookback = { since: new Date(today.since.getFullYear(), today.since.getMonth(), today.since.getDate() - LOOKBACK_DAYS), until: today.since }
919
+ const scan = await tadaDigest(lookback, flags, { chat: true, open: false })
920
+ const day = lastActiveDay(activityTimes(scan), today.since)
921
+ const leftWindow = day ? windowFor({ on: localDay(day) }, now) : null
922
+ const leftOff = leftWindow ? await tadaDigest(leftWindow, flags) : null
923
+ const todaySoFar = await tadaDigest(today, flags)
924
+
925
+ const homeRepo = gitRepoOf(process.cwd()).repo
926
+ let home = null
927
+ if (homeRepo && fs.existsSync(path.join(homeRepo, 'specs', '.core'))) {
928
+ let name = path.basename(homeRepo)
929
+ try {
930
+ name = projectName(loadEnvConfig(homeRepo).config) || name
931
+ } catch {
932
+ // the folder name stands in, as it does everywhere else
933
+ }
934
+ home = { repo: homeRepo, name, groups: openSpecsIn(homeRepo).map((row) => ({ spec: row.spec, inFlight: row })) }
935
+ }
936
+
937
+ const todo = buildTodo({ leftOff, leftOffDay: day, today: todaySoFar, home, blockersFor: repoBlockers })
938
+ todo.todayLabel = humanLabel(today)
939
+ if (todo.leftOff) todo.leftOff.label = humanLabel(leftWindow)
940
+
844
941
  if (argv.includes('--page')) {
845
- // No server to serve it: the page is a file on this machine, as it was.
846
- const out = path.join(os.tmpdir(), `skitterspec-tada-${windowLabel(window).replace(' → ', '_')}.html`)
847
- fs.writeFileSync(out, renderTadaPage(digest, { recap, title: `Ta-da · ${digest.window.label}`, category: digest.category || null }))
942
+ let recap = null
943
+ const from = tadaFlag(argv, '--summary')
944
+ if (from) {
945
+ try {
946
+ recap = fs.readFileSync(path.resolve(from), 'utf8')
947
+ } catch (e) {
948
+ process.stderr.write(`skitterspec todo: --summary ${from}: ${e.code || e.message}\n`)
949
+ process.exitCode = 1
950
+ return
951
+ }
952
+ }
953
+ if (await serveTadaPage({ window: today, flags: { ...flags, todo: true }, recap })) return
954
+ const out = path.join(os.tmpdir(), `skitterspec-todo-${localDay(today.since)}.html`)
955
+ fs.writeFileSync(out, renderTadaPage(todo, { recap, title: `To-do · ${todo.todayLabel}`, category: todo.category || null }))
848
956
  process.stdout.write(`page: ${pathToFileURL(out).href}\n`)
849
957
  return
850
958
  }
851
- if (json) {
852
- process.stdout.write(JSON.stringify(digest, null, 2) + '\n')
959
+ if (argv.includes('--json')) {
960
+ process.stdout.write(JSON.stringify(todo, null, 2) + '\n')
853
961
  return
854
962
  }
855
- process.stdout.write(formatTada(digest))
963
+ process.stdout.write(formatTodo(todo, now))
856
964
  }
857
965
 
858
966
  /**
@@ -878,7 +986,7 @@ async function serveTadaPage({ window, flags, recap }) {
878
986
  if (!present || config.review.serve === 'never') return false
879
987
  attachProject(config, anchor)
880
988
  const dir = anchor.dir
881
- const ask = { on: flags.on, since: flags.since, window, all: flags.all, chat: flags.chat }
989
+ const ask = { on: flags.on, since: flags.since, window, all: flags.all, chat: flags.chat, todo: Boolean(flags.todo) }
882
990
  if (recap !== null) {
883
991
  const file = tadaRecapPath(path.join(dir, stateDirLabel(config)), tadaRecapKey(ask))
884
992
  fs.mkdirSync(path.dirname(file), { recursive: true })
@@ -1426,6 +1534,88 @@ function specEnvUpCheckout(dir, config, spec) {
1426
1534
  * `allow` and `status` are for a person. `allow` is reached only through
1427
1535
  * `/allow-main`, which is user-only — a guard the model can lift is decoration.
1428
1536
  */
1537
+ /**
1538
+ * `spec-env project <check|allow|status>` — the project guard's engine
1539
+ * (`env/projectguard.js`). `dir` is home: the project the session belongs to,
1540
+ * anchored on its primary checkout like every subcommand.
1541
+ *
1542
+ * `check` is the hook's question — `--path <file>` for a write, `--command
1543
+ * <line> --cwd <dir>` for a shell command — and prints a refusal on stdout with
1544
+ * exit 1, or nothing with exit 0. `allow <name|path> [off]` is `/allow-project`.
1545
+ */
1546
+ function specEnvProject(dir, config, positional, flags = {}) {
1547
+ const action = positional[0] || 'status'
1548
+ const sessionId = flags.session || process.env.CLAUDE_CODE_SESSION_ID || null
1549
+ const enabled = !(config.guards && config.guards.projectBoundary === false)
1550
+
1551
+ if (action === 'check') {
1552
+ if (!enabled) return
1553
+ const allows = readProjectAllows(dir, config)
1554
+ const cwd = flags.cwd ? path.resolve(flags.cwd) : dir
1555
+ let verdict = { refuse: false }
1556
+ if (typeof flags.command === 'string') {
1557
+ verdict = checkProjectCommand({ home: dir, cwd, command: flags.command, gitAt: gitReader, allows, sessionId })
1558
+ } else if (flags.path) {
1559
+ verdict = checkProjectPath({ home: dir, target: path.resolve(cwd, flags.path), gitAt: gitReader, allows, sessionId })
1560
+ }
1561
+ if (!verdict.refuse) return
1562
+ process.stdout.write(`spec-env project: ${verdict.reason}\n`)
1563
+ process.exitCode = 1
1564
+ return
1565
+ }
1566
+
1567
+ if (action === 'allow') {
1568
+ const what = positional[1]
1569
+ if (!what) {
1570
+ process.stdout.write('Usage: skitterspec spec-env project allow <name|path> [off]\n')
1571
+ process.exitCode = 1
1572
+ return
1573
+ }
1574
+ if (flags.off || positional[2] === 'off') {
1575
+ const n = clearProjectLift(dir, config, what)
1576
+ process.stdout.write(
1577
+ n ? `spec-env project: ${what} is guarded again.\n` : `spec-env project: nothing to clear — ${what} was already guarded.\n`,
1578
+ )
1579
+ return
1580
+ }
1581
+ const lift = recordProjectLift(dir, config, { what, sessionId, gitAt: gitReader, at: new Date().toISOString() })
1582
+ if (lift.error) {
1583
+ process.stdout.write(`spec-env project: ${lift.error}\n`)
1584
+ process.exitCode = 1
1585
+ return
1586
+ }
1587
+ const scope =
1588
+ lift.scope === 'session'
1589
+ ? 'this session only — it lapses when the session ends'
1590
+ : `this repo until cleared — no session id available, so \`/allow-project ${lift.name} off\` is what ends it`
1591
+ process.stdout.write(`spec-env project: this session may work on ${lift.name} (${scope}).\n`)
1592
+ return
1593
+ }
1594
+
1595
+ if (action === 'status') {
1596
+ const lifts = readProjectAllows(dir, config)
1597
+ const st = { state: enabled ? 'guarded' : 'off', lifts }
1598
+ if (flags.json) {
1599
+ process.stdout.write(JSON.stringify(st, null, 2) + '\n')
1600
+ return
1601
+ }
1602
+ if (!enabled) {
1603
+ process.stdout.write('spec-env project: off for this project (guards.projectBoundary is false).\n')
1604
+ return
1605
+ }
1606
+ const mine = lifts.filter((l) => l.scope === 'repo' || (sessionId && l.session === sessionId))
1607
+ process.stdout.write(
1608
+ mine.length
1609
+ ? `spec-env project: guarded, with ${mine.map((l) => l.name).join(', ')} lifted for ${mine.some((l) => l.scope === 'repo') ? 'this repo' : 'this session'}.\n`
1610
+ : 'spec-env project: guarded — this session works on this project only.\n',
1611
+ )
1612
+ return
1613
+ }
1614
+
1615
+ process.stdout.write('Usage: skitterspec spec-env project <check|allow|status>\n')
1616
+ process.exitCode = 1
1617
+ }
1618
+
1429
1619
  function specEnvMain(dir, config, positional, flags = {}, present = true, invokedFrom = dir) {
1430
1620
  const action = positional[0] || 'status'
1431
1621
  const sessionId = flags.session || process.env.CLAUDE_CODE_SESSION_ID || null
@@ -7071,9 +7261,6 @@ function runGit(cwd, args) {
7071
7261
  }
7072
7262
  }
7073
7263
 
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
7264
  // Live overlay: test a spec on the already-running instance by checking its
7078
7265
  // branch out in the primary checkout, so the running dev server hot-reloads the
7079
7266
  // feature. The branch that's checked out IS the lock (assertPrimaryOnMain); the
@@ -7192,6 +7379,30 @@ function bareLive(dir, config) {
7192
7379
  return { action: 'take', specArg: choice.folder }
7193
7380
  }
7194
7381
 
7382
+ // What `live take` rebases onto. Under PR landing the base branch moves only
7383
+ // when the host merges, so local base is as stale as the last pull: fetch and
7384
+ // rebase onto `<remote>/<base>`, which is also what the landing rebase targets.
7385
+ // The take already rewrites the branch on every run, and the PR push is
7386
+ // `--force-with-lease`, so this puts nothing new at risk. Trunk landing keeps
7387
+ // local base — there the base branch is local work.
7388
+ //
7389
+ // WHAT WOULD FOOL THIS: a failed fetch (offline, no such remote, no such branch
7390
+ // there) says nothing about whether the remote base moved. That is cannot-tell,
7391
+ // so it falls back to local base and says so — never a refusal.
7392
+ function liveRebaseTarget(dir, config, base) {
7393
+ if (config.land.strategy !== 'pr') return { onto: base, note: null }
7394
+ const remote = baseRemote(config)
7395
+ const onto = `${remote}/${base}`
7396
+ const fetched = runGit(dir, ['fetch', remote, base]).ok
7397
+ if (fetched && gitReader(dir)(['rev-parse', '--verify', '--quiet', `refs/remotes/${onto}`])) {
7398
+ return { onto, note: null }
7399
+ }
7400
+ return {
7401
+ onto: base,
7402
+ note: `could not fetch ${onto} — rebased onto local ${base}, which may be behind the remote`,
7403
+ }
7404
+ }
7405
+
7195
7406
  // Take the running instance: rebase the spec's branch onto base, free it from its
7196
7407
  // worktree, and check it out in the primary checkout so the dev server reloads it.
7197
7408
  async function specEnvLiveTake(dir, config, specArg, flags = {}) {
@@ -7209,15 +7420,25 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7209
7420
  const wtStatus = worktreeExists ? gitReader(spec.worktreePath)(['status', '--porcelain']) : ''
7210
7421
  const worktreeClean = wtStatus !== null && wtStatus.length === 0
7211
7422
  const baseMainCommit = primaryGit(['rev-parse', 'HEAD'])
7212
-
7213
- // Diff base...branch to spot migration / dependency changes (best-effort).
7214
- const changed = primaryGit(['diff', '--name-only', `${base}...${spec.branch}`])
7423
+ const { onto, note: rebaseNote } = liveRebaseTarget(dir, config, base)
7424
+
7425
+ // Diff onto...branch to spot migration / dependency changes (best-effort) —
7426
+ // against the target the rebase will replay over, so both read the same commits.
7427
+ // `changedFiles` keeps the difference the two checks above can ignore: a
7428
+ // diff git would not answer is null (unknown), which runs `afterSwitch`'s
7429
+ // conditional entries rather than skipping them.
7430
+ const changed = primaryGit(['diff', '--name-only', `${onto}...${spec.branch}`])
7215
7431
  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')
7432
+ const changedFiles = changed === null ? null : files
7433
+ const depsHit = depsChanged(files, config.setupTriggers)
7434
+
7435
+ // Verify-only: probe the declared canonical (frontPort) ports of the HOT dev
7436
+ // entries. None declared → no health gate (serverUp = null); the switch
7437
+ // proceeds with a warning. A `reload: "restart"` entry is never probed: an
7438
+ // IDE-hosted app that is not running is the normal state, not a refusal.
7439
+ const hotDev = config.dev.filter((d) => d.reload !== 'restart')
7440
+ const restartApps = config.dev.filter((d) => d.reload === 'restart').map((d) => d.name)
7441
+ const canonicalPorts = hotDev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
7221
7442
  let serverUp = null
7222
7443
  if (canonicalPorts.length) {
7223
7444
  const up = await portsAnswering(canonicalPorts, config.proxy.host)
@@ -7233,10 +7454,14 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7233
7454
  worktreeExists,
7234
7455
  base,
7235
7456
  baseMainCommit,
7457
+ rebaseOnto: onto,
7458
+ rebaseNote,
7236
7459
  serverUp,
7237
7460
  canonicalPorts,
7461
+ restartApps,
7238
7462
  migrationsHit: migrationsHit(files, config.live.migrations),
7239
- depsChanged,
7463
+ depsChanged: depsHit,
7464
+ changedFiles,
7240
7465
  holder: primaryGit(['config', 'user.name']) || 'unknown',
7241
7466
  heldSince: new Date().toISOString(),
7242
7467
  })
@@ -7274,7 +7499,7 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7274
7499
  }
7275
7500
 
7276
7501
  // Execute the switch. Rebase first; on conflict, abort and bail (state untouched).
7277
- const reb = runGit(spec.worktreePath, ['rebase', base])
7502
+ const reb = runGit(spec.worktreePath, ['rebase', onto])
7278
7503
  if (!reb.ok) {
7279
7504
  // A rebase fails two ways and they need different answers. It can REFUSE TO
7280
7505
  // START (unstaged changes, a missing base) — nothing to abort, nothing to
@@ -7285,9 +7510,9 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7285
7510
  if (started) runGit(spec.worktreePath, ['rebase', '--abort'])
7286
7511
  process.stdout.write(
7287
7512
  started
7288
- ? `spec-env live take: rebase of ${spec.branch} onto ${base} hit conflicts — ` +
7513
+ ? `spec-env live take: rebase of ${spec.branch} onto ${onto} hit conflicts — ` +
7289
7514
  `resolve them in ${spec.worktreePath}, then retry.\n`
7290
- : `spec-env live take: rebase of ${spec.branch} onto ${base} could not start — ` +
7515
+ : `spec-env live take: rebase of ${spec.branch} onto ${onto} could not start — ` +
7291
7516
  `git said:\n ${reb.err.split('\n').join('\n ')}\n`,
7292
7517
  )
7293
7518
  return
@@ -7313,6 +7538,10 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7313
7538
  out.push('')
7314
7539
  out.push(` primary: now on ${receipt.branch} (was ${base} @ ${receipt.baseMainCommit.slice(0, 7)})`)
7315
7540
  out.push(` worktree: ${spec.worktreePath} (detached — branch handed to the primary checkout)`)
7541
+ if (onto !== base) out.push(` rebased: onto ${onto} (PR landing — the remote base)`)
7542
+ // After the receipt, so a failed command leaves a switch that `release` and
7543
+ // `status` both know about — the switch stands either way.
7544
+ out.push(...runAfterSwitch(plan.afterSwitch).lines)
7316
7545
  for (const w of plan.warnings) out.push(` ! ${w}`)
7317
7546
  out.push('')
7318
7547
  out.push(' Test at your canonical URL; release with: /spec-live main')
@@ -7344,6 +7573,10 @@ async function specEnvLiveRelease(dir, config, specArg) {
7344
7573
  const status = primaryGit(['status', '--porcelain'])
7345
7574
  const clean = status !== null && status.length === 0
7346
7575
  const worktreeExists = fs.existsSync(spec.worktreePath)
7576
+ // The files take brought in, read before the checkout moves HEAD: the switch
7577
+ // back reverts the same set. null when git would not say — unknown, not empty.
7578
+ const changed = primaryGit(['diff', '--name-only', `${base}...${spec.branch}`])
7579
+ const changedFiles = changed === null ? null : changed.split('\n').filter(Boolean)
7347
7580
 
7348
7581
  const plan = planRelease(spec, config, {
7349
7582
  primary,
@@ -7351,6 +7584,8 @@ async function specEnvLiveRelease(dir, config, specArg) {
7351
7584
  base,
7352
7585
  clean,
7353
7586
  worktreeExists,
7587
+ restartApps: config.dev.filter((d) => d.reload === 'restart').map((d) => d.name),
7588
+ changedFiles,
7354
7589
  })
7355
7590
 
7356
7591
  if (plan.noop) {
@@ -7372,7 +7607,9 @@ async function specEnvLiveRelease(dir, config, specArg) {
7372
7607
 
7373
7608
  process.stdout.write(
7374
7609
  `spec-env live release: ${spec.folder} released — primary back on ${base}, ` +
7375
- `${spec.branch} re-isolated to its worktree.\n`,
7610
+ `${spec.branch} re-isolated to its worktree.\n` +
7611
+ runAfterSwitch(plan.afterSwitch).lines.map((l) => `${l}\n`).join('') +
7612
+ plan.warnings.map((w) => ` ! ${w}\n`).join(''),
7376
7613
  )
7377
7614
  }
7378
7615
 
@@ -7627,6 +7864,8 @@ async function specEnv(rest) {
7627
7864
  else if (args[i] === '--from') flags.from = args[++i]
7628
7865
  else if (args[i] === '--session') flags.session = args[++i]
7629
7866
  else if (args[i] === '--path') flags.path = args[++i]
7867
+ else if (args[i] === '--cwd') flags.cwd = args[++i]
7868
+ else if (args[i] === '--command') flags.command = args[++i] ?? ''
7630
7869
  else if (args[i] === '--assert-primary-clean') flags.assertPrimaryClean = true
7631
7870
  else positional.push(args[i])
7632
7871
  }
@@ -7712,6 +7951,9 @@ async function specEnv(rest) {
7712
7951
  case 'main':
7713
7952
  specEnvMain(dir, config, positional, flags, present, invokedFrom)
7714
7953
  break
7954
+ case 'project':
7955
+ specEnvProject(dir, config, positional, flags)
7956
+ break
7715
7957
  case 'down':
7716
7958
  specEnvDown(dir, config, positional[0], flags)
7717
7959
  break
@@ -7860,6 +8102,11 @@ async function run(argv) {
7860
8102
  return
7861
8103
  }
7862
8104
 
8105
+ if (cmd === 'todo') {
8106
+ await todoCommand(rest)
8107
+ return
8108
+ }
8109
+
7863
8110
  if (cmd === 'epic') {
7864
8111
  const [sub, ...eArgs] = rest
7865
8112
  if (sub === 'status') epicStatusCommand(eArgs)
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)
@@ -48,8 +49,10 @@
48
49
  * // (push + pull request; base moves when the host merges)
49
50
  * guards: { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
50
51
  * teardown: { deleteRemoteBranch },
51
- * live: { migrations: [ "glob", ... ] } // migration globs → `live take`
52
+ * live: { migrations: [ "glob", ... ], // migration globs → `live take`
52
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`
53
56
  * hotfix: { bump, cherryPickMain, targets, releaseWith, releaseBranch, tag }
54
57
  * // `hotfix land`: patch-bump the deploy tag, also cherry-pick
55
58
  * // onto the base branch (main), and onto any extra base tags in
@@ -250,6 +253,10 @@ const DEFAULT_CONFIG = Object.freeze({
250
253
  refuseTeardownIfDirty: true,
251
254
  refuseTeardownIfUnpushed: true,
252
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,
253
260
  }),
254
261
  // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
255
262
  // `spec-env down` does about a branch the USER published by hand — nothing
@@ -327,7 +334,10 @@ const DEFAULT_CONFIG = Object.freeze({
327
334
  // Live overlay (`spec-env live`). `migrations` is a list of globs marking
328
335
  // migration files; a branch that changes any of them is treated as stateful and
329
336
  // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
330
- 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([]) }),
331
341
  // Hotfix landing (`spec-env hotfix land`). `bump` is the version-bump strategy
332
342
  // for the new deploy tag: "patch" (X.Y.Z -> X.Y.(Z+1)) or "hotfix-suffix"
333
343
  // (X.Y.Z -> X.Y.Z-hotfix.N). The loader keeps whatever string it is given and
@@ -422,7 +432,7 @@ function defaults() {
422
432
  guards: { ...DEFAULT_CONFIG.guards },
423
433
  teardown: { ...DEFAULT_CONFIG.teardown },
424
434
  review: { ...DEFAULT_CONFIG.review, reviewers: [] },
425
- live: { migrations: [] },
435
+ live: { migrations: [], afterSwitch: [] },
426
436
  hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
427
437
  }
428
438
  }
@@ -462,6 +472,9 @@ function normalizeDev(parsed) {
462
472
  if (typeof raw.frontPort === 'number' && Number.isFinite(raw.frontPort)) {
463
473
  entry.frontPort = raw.frontPort
464
474
  }
475
+ // An unrecognised value falls through to "hot", the conservative reading:
476
+ // a typo keeps `live take`'s listening check rather than silently dropping it.
477
+ entry.reload = raw.reload === 'restart' ? 'restart' : 'hot'
465
478
  out.push(entry)
466
479
  }
467
480
  return out
@@ -730,6 +743,7 @@ function mergeConfig(base, parsed) {
730
743
  assign(base.guards, parsed.guards, 'refuseTeardownIfDirty', 'boolean')
731
744
  assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
732
745
  assign(base.guards, parsed.guards, 'mainIsLandingZone', 'boolean')
746
+ assign(base.guards, parsed.guards, 'projectBoundary', 'boolean')
733
747
  }
734
748
 
735
749
  // An unrecognised policy falls through to the default rather than erroring or
@@ -817,6 +831,12 @@ function mergeConfig(base, parsed) {
817
831
  base.live.migrations = normalizeFileList(parsed.live.migrations)
818
832
  }
819
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
+
820
840
  if (isObject(parsed.hotfix)) {
821
841
  assign(base.hotfix, parsed.hotfix, 'bump', 'string')
822
842
  assign(base.hotfix, parsed.hotfix, 'cherryPickMain', 'boolean')
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 }