@skitterbyte/skitterspec-jira 2.16.0 → 2.18.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
@@ -5,7 +5,7 @@ const path = require('path')
5
5
  const os = require('os')
6
6
  const { pathToFileURL } = require('url')
7
7
  const { execFileSync } = require('child_process')
8
- const { init, resync, reset, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
8
+ const { init, resync, reset, uninstall, disable, enable, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
9
9
  const {
10
10
  detectReleaseTooling,
11
11
  removeReleaseTooling,
@@ -103,6 +103,9 @@ const {
103
103
  readReceipt,
104
104
  writeReceipt,
105
105
  clearReceipt,
106
+ readLastLive,
107
+ writeLastLive,
108
+ clearLastLive,
106
109
  summarizeReceipt,
107
110
  migrationsHit,
108
111
  depsChanged,
@@ -127,15 +130,9 @@ const {
127
130
  renderReviewBlock,
128
131
  reviewOutPath,
129
132
  reviewFileUrl,
130
- reviewUrlPath,
131
- reviewPublishPath,
132
133
  readReviewUrl,
133
- readRemoteAllow,
134
- writeRemoteAllow,
135
- withSpecRemote,
136
134
  publishedPageNotice,
137
135
  reviewServerNotice,
138
- renderReviewFragment,
139
136
  resolveReader,
140
137
  writeReviewPage,
141
138
  reviewNotesPath,
@@ -290,6 +287,16 @@ Usage:
290
287
  edits (--force to overwrite). Leaves specs/ + live
291
288
  .core config alone. --check reports what it would
292
289
  change and writes nothing.
290
+ skitterspec uninstall [dir] Take a local install (init --local) back off this
291
+ machine: managed files, hooks, the CLAUDE.local.md
292
+ block, the git excludes. Prints the plan; --yes
293
+ acts. Edited files are kept; specs/ is untouched.
294
+ Refuses a team install, or while a spec is in flight.
295
+ skitterspec disable [dir] Switch a local install off for this machine's
296
+ Claude — skills, commands, rules, hooks, the
297
+ CLAUDE.local.md block — leaving the files on disk.
298
+ skitterspec enable [dir] Switch it back on; installs it (init --local) when
299
+ there is nothing here to switch on.
293
300
  skitterspec spec-env <cmd> Per-spec isolation engine (opt-in; needs
294
301
  specs/.core/env.config.json). Subcommands:
295
302
  up <spec> print the plan to provision a worktree +
@@ -1065,7 +1072,7 @@ async function serveTadaPage({ window, flags, recap }) {
1065
1072
  const withQ = (u) => (u ? `${u}${q}` : u)
1066
1073
  const page = { ...served, loopbackUrl: withQ(served.loopbackUrl), url: withQ(served.url), alternates: (served.alternates || []).map(withQ) }
1067
1074
  const reader = resolveReader(config, process.env, process.platform)
1068
- const tiers = reviewTierStack({ served: page, fileUrl: null, publishedUrl: null, config, reader })
1075
+ const tiers = reviewTierStack({ served: page, fileUrl: null, config, reader })
1069
1076
  process.stdout.write(`page: ${humanLabel(window)}\n${reviewStackText(tiers)}`)
1070
1077
  return true
1071
1078
  }
@@ -1171,7 +1178,7 @@ function epicPageTiers(inputs, up, epic) {
1171
1178
  if (!up) return { off: true, start: 'skitterspec spec-env review serve --host 0.0.0.0' }
1172
1179
  const served = reviewServedUrls(up, offerableLanAddresses(), epic)
1173
1180
  const reader = resolveReader(inputs.config, process.env, process.platform)
1174
- return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config, reader }) }
1181
+ return { tiers: reviewTierStack({ served, fileUrl: null, config: inputs.config, reader }) }
1175
1182
  }
1176
1183
 
1177
1184
  function epicPageLines(page) {
@@ -2763,6 +2770,10 @@ function specEnvDown(dir, config, specArg, flags) {
2763
2770
  writeRegistry(dir, config, next)
2764
2771
  }
2765
2772
 
2773
+ // A torn-down spec is no longer anything a bare resolve should name.
2774
+ const last = readLastLive(dir, config)
2775
+ if (last && last.spec === spec.folder) clearLastLive(dir, config)
2776
+
2766
2777
  const out = []
2767
2778
  out.push(
2768
2779
  `spec-env down: ${spec.folder}` +
@@ -2887,47 +2898,73 @@ function volumeCreatedAt(names) {
2887
2898
  * `soleProvisionedSpec` below is a thin wrapper that turns the two empty-handed
2888
2899
  * cases into the exact errors every other subcommand already relies on.
2889
2900
  */
2890
- function provisionedSpecChoice(dir, config, cwd = process.cwd()) {
2901
+ function provisionedSpecChoice(dir, config, cwd = process.cwd(), { lastLive = true } = {}) {
2891
2902
  const worktreePaths = liveWorktreePaths(gitReader(dir))
2892
2903
  const provisioned = allSpecs(dir, config, worktreePaths, speclessMap(dir, config))
2893
- .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
2904
+ .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath), project: s.projectPath }))
2894
2905
  // The primary checkout is itself in `git worktree list`; a spec is
2895
2906
  // provisioned only when it has its OWN worktree, separate from it.
2896
2907
  .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
2897
2908
  .sort((a, b) => a.folder.localeCompare(b.folder))
2909
+ // The project folder, which is what `resolve` prints as `worktree:` and what
2910
+ // `/spec-next --worktree` is checked against — the worktree root only differs
2911
+ // when the project sits below the git root.
2912
+ const worktrees = provisioned.map((s) => ({ spec: s.folder, worktree: s.project }))
2898
2913
 
2899
2914
  // 1. Standing inside a spec's worktree names it outright. Deepest match wins,
2900
2915
  // so a nested worktree is not shadowed by an ancestor one.
2901
- let here
2902
- try {
2903
- here = fs.realpathSync.native(path.resolve(cwd))
2904
- } catch {
2905
- here = path.resolve(cwd)
2916
+ const real = (p) => {
2917
+ try {
2918
+ return fs.realpathSync.native(path.resolve(p))
2919
+ } catch {
2920
+ return path.resolve(p)
2921
+ }
2906
2922
  }
2923
+ const here = real(cwd)
2907
2924
  const inside = provisioned
2908
2925
  .filter((s) => here === s.wt || here.startsWith(s.wt + path.sep))
2909
2926
  .sort((a, b) => b.wt.length - a.wt.length)[0]
2910
- if (inside) return { folder: inside.folder }
2927
+ if (inside) return { folder: inside.folder, via: 'here', worktrees }
2911
2928
 
2912
- // 2. Otherwise only an unambiguous set answers.
2913
- if (provisioned.length === 1) return { folder: provisioned[0].folder }
2914
- return { candidates: provisioned.map((s) => s.folder) }
2929
+ // 2. From the primary checkout, the spec `live release` last handed back
2930
+ // (bug-live-release-forgets-spec) — only while it is still provisioned, so
2931
+ // a record outliving its worktree falls through as cannot-tell. Nowhere
2932
+ // else: the record is this checkout's, and says nothing about other cwds.
2933
+ const primary = real(dir)
2934
+ if (lastLive && (here === primary || here.startsWith(primary + path.sep))) {
2935
+ const record = readLastLive(dir, config)
2936
+ const hit = record && provisioned.find((s) => s.folder === record.spec)
2937
+ if (hit) return { folder: hit.folder, via: 'last-live', worktrees }
2938
+ }
2939
+
2940
+ // 3. Otherwise only an unambiguous set answers.
2941
+ if (provisioned.length === 1) return { folder: provisioned[0].folder, via: 'sole', worktrees }
2942
+ return { candidates: provisioned.map((s) => s.folder), worktrees }
2915
2943
  }
2916
2944
 
2917
2945
  function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
2918
- const { folder, candidates } = provisionedSpecChoice(dir, config, cwd)
2919
- if (folder) return folder
2920
- if (!candidates.length) {
2921
- throw new Error(
2922
- 'no spec given, and no spec has a worktree — name one explicitly, or run ' +
2923
- '/spec-start to provision it.',
2924
- )
2925
- }
2926
- throw new Error(
2927
- `no spec given, and ${candidates.length} specs have worktrees — name the one ` +
2928
- `you mean, or run this from inside one:\n` +
2929
- candidates.map((f, i) => ` ${i + 1}. ${f}`).join('\n'),
2930
- )
2946
+ return provisionedSpecChoiceOrThrow(dir, config, cwd).folder
2947
+ }
2948
+
2949
+ // `provisionedSpecChoice`, with the two empty-handed cases turned into the
2950
+ // errors every subcommand relies on. Each carries `reason` ('ambiguous' |
2951
+ // 'none') and the worktrees, so `resolve --json` can report it as data.
2952
+ function provisionedSpecChoiceOrThrow(dir, config, cwd = process.cwd()) {
2953
+ const choice = provisionedSpecChoice(dir, config, cwd)
2954
+ if (choice.folder) return choice
2955
+ const err = !choice.candidates.length
2956
+ ? new Error(
2957
+ 'no spec given, and no spec has a worktree — name one explicitly, or run ' +
2958
+ '/spec-start to provision it.',
2959
+ )
2960
+ : new Error(
2961
+ `no spec given, and ${choice.candidates.length} specs have worktrees — name the one ` +
2962
+ `you mean, or run this from inside one:\n` +
2963
+ choice.worktrees.map((w, i) => ` ${i + 1}. ${w.spec} (${w.worktree})`).join('\n'),
2964
+ )
2965
+ err.reason = choice.candidates.length ? 'ambiguous' : 'none'
2966
+ err.candidates = choice.worktrees
2967
+ throw err
2931
2968
  }
2932
2969
 
2933
2970
  // Resolve a spec argument the ONE way every spec-env subcommand resolves it:
@@ -3445,7 +3482,9 @@ function specEnvIntegratePr(dir, config, spec, base, flags, retarget = null) {
3445
3482
  // branch's own range — remote image first, local base as the fallback
3446
3483
  // when the remote ref is not here.
3447
3484
  primaryPath: dir,
3448
- changedFiles: landRange(git, `${remote}/${base}`, spec.branch) || landRange(git, base, spec.branch),
3485
+ changedFiles: aheadOfRemoteBase === false
3486
+ ? catchUpRange(git, base, `${remote}/${base}`)
3487
+ : landRange(git, `${remote}/${base}`, spec.branch) || landRange(git, base, spec.branch),
3449
3488
  worktreeState: { dirty },
3450
3489
  base,
3451
3490
  remote,
@@ -3696,6 +3735,21 @@ function landRange(git, base, branch) {
3696
3735
  return out.split('\n').map((l) => l.trim()).filter(Boolean)
3697
3736
  }
3698
3737
 
3738
+ // The range of a PR-mode finish: what local base gains by catching up with the
3739
+ // remote image the host merged into. The branch's own range cannot answer once
3740
+ // it has landed — it is inside `<remote>/<base>`, so `<remote>/<base>...branch`
3741
+ // is empty, and an empty known range skipped every conditional entry
3742
+ // (bug-pr-afterland-range).
3743
+ //
3744
+ // WHAT WOULD FOOL IT: a base already caught up by hand (`git pull`), which
3745
+ // leaves nothing between the two refs while the afterLand those files wanted
3746
+ // never ran. Empty therefore reads as unknown, which runs the conditional
3747
+ // entries (`.claude/rules/negative-checks.md` rule 4).
3748
+ function catchUpRange(git, base, remoteBase) {
3749
+ const range = landRange(git, base, remoteBase)
3750
+ return range && range.length ? range : null
3751
+ }
3752
+
3699
3753
  // The `afterLand` commands, as a section printed after a land plan — or after
3700
3754
  // integrate's already-landed line. Empty string when none apply, so a project
3701
3755
  // without the key sees exactly the output it always has, and one of plain
@@ -4496,14 +4550,60 @@ function assertPrimaryClean(dir, config, r) {
4496
4550
  }
4497
4551
 
4498
4552
  // Print the resolved identity/coordinates for a single spec.
4553
+ const RESOLVED_VIA = {
4554
+ here: 'the worktree you are standing in',
4555
+ 'last-live': 'last live on this checkout',
4556
+ sole: 'the only spec provisioned',
4557
+ }
4558
+
4499
4559
  function specEnvResolve(dir, config, specArg, flags = {}) {
4560
+ // Bare, say HOW it resolved as well as what: a caller standing in the primary
4561
+ // checkout cannot see which rung answered. `--json` also reports the two
4562
+ // empty-handed cases as data — `ambiguous` and `none` call for different
4563
+ // next steps, and a skill should not tell them apart by an Error's wording.
4564
+ let via = 'named'
4565
+ if (!specArg) {
4566
+ try {
4567
+ const choice = provisionedSpecChoiceOrThrow(dir, config)
4568
+ specArg = choice.folder
4569
+ via = choice.via
4570
+ } catch (err) {
4571
+ if (!flags.json || !err.reason) throw err
4572
+ process.stdout.write(
4573
+ JSON.stringify({ ok: false, reason: err.reason, error: err.message, candidates: err.candidates }, null, 2) +
4574
+ '\n',
4575
+ )
4576
+ return
4577
+ }
4578
+ }
4500
4579
  const r = resolveSpecWithWorktree(dir, config, specArg)
4501
4580
  if (flags.recordPrimary) return recordPrimary(dir, config, r)
4502
4581
  if (flags.assertPrimaryClean) return assertPrimaryClean(dir, config, r)
4582
+ if (flags.json) {
4583
+ process.stdout.write(
4584
+ JSON.stringify(
4585
+ {
4586
+ ok: true,
4587
+ spec: r.folder,
4588
+ via,
4589
+ bucket: r.specless ? null : r.bucket,
4590
+ type: r.type,
4591
+ slug: r.slug,
4592
+ branch: r.branch,
4593
+ worktree: r.projectPath,
4594
+ project: r.projectName,
4595
+ },
4596
+ null,
4597
+ 2,
4598
+ ) + '\n',
4599
+ )
4600
+ return
4601
+ }
4503
4602
  process.stdout.write(
4504
4603
  // A specless branch has no bucket because it has no document — say that
4505
4604
  // rather than printing `(null)`, which reads as a lookup that failed.
4506
4605
  `spec: ${r.folder} (${r.specless ? 'no spec' : r.bucket})\n` +
4606
+ (RESOLVED_VIA[via] ? `via: ${RESOLVED_VIA[via]}\n` : '') +
4507
4607
  `type/slug: ${r.type} / ${r.slug}\n` +
4508
4608
  `branch: ${r.branch}\n` +
4509
4609
  `worktree: ${r.projectPath}\n` +
@@ -5121,11 +5221,11 @@ function readRunningReviewServer(dir, config) {
5121
5221
  * the same functions, with nothing rendered and nothing started.
5122
5222
  */
5123
5223
  function reshowStack(dir, config, spec, out) {
5124
- const cfg = withSpecRemote(config, out)
5224
+ const cfg = config
5125
5225
  const up = readRunningReviewServer(dir, cfg)
5126
5226
  const served = up ? reviewServedUrls(up, offerableLanAddresses(), spec.folder) : null
5127
5227
  const reader = resolveReader(cfg, process.env, process.platform)
5128
- const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg, reader })
5228
+ const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), config: cfg, reader })
5129
5229
  let live = null
5130
5230
  try {
5131
5231
  const primaryState = assertPrimaryOnMain(cfg, gitReader(dir))
@@ -5444,101 +5544,74 @@ function specEnvReviewGate(dir, config, specArg, flags, invokedFrom = dir) {
5444
5544
  }
5445
5545
 
5446
5546
  /**
5447
- * `review allow <network|remote> [<spec>] [--off | --set <on|off|>] [--project]`
5448
- * — permit or withdraw a review tier.
5449
- *
5450
- * TWO SCOPES, because the two tiers are different kinds of decision.
5547
+ * `review allow network [--off | --set <on|off|>]` — permit or withdraw the
5548
+ * served tiers beyond loopback.
5451
5549
  *
5452
5550
  * `network` is a BIND, and one server binds for every spec at once — so it is a
5453
- * project setting and lives in the committed `env.config.json`.
5551
+ * project setting and lives in the committed `env.config.json`. `remote` is the
5552
+ * tailnet address of that same server, so this one switch covers it too.
5454
5553
  *
5455
- * `remote` PERMITS PUBLISHING, which sends one spec's diff to a third party. It
5456
- * was project-wide too, and that was bug-remote-review-toggle: typed from a
5457
- * worktree with a review waiting, it dirtied the base branch's committed config
5458
- * and permitted every other spec in the repo to publish as well. So it is now
5459
- * PER SPEC — a sidecar in the gitignored review store, layered over the
5460
- * committed key by `withSpecRemote`. `--project` keeps the committed write for
5461
- * a team that wants it everywhere.
5554
+ * `allow remote` used to permit publishing the review as a claude.ai page,
5555
+ * per spec. That tier is retired (feat-tailnet-remote-tier), and the verb
5556
+ * refuses by name rather than quietly doing the network thing: a person who
5557
+ * typed it wanted something specific, and should hear where it went.
5462
5558
  *
5463
- * THE COMMITTED WRITE IS NARROW: it reads, sets one key under `review`, and
5464
- * writes back with two-space indent. It never reorders, never adds a key nobody
5465
- * asked for, and never touches another section.
5559
+ * THE WRITE IS NARROW: it reads, sets one key under `review`, and writes back
5560
+ * with two-space indent. It never reorders, never adds a key nobody asked for,
5561
+ * and never touches another section.
5466
5562
  *
5467
5563
  * WHAT WOULD FOOL THIS: a config indented with anything other than two spaces
5468
- * IS reformatted by the committed write — cosmetic, but worth knowing before it
5469
- * shows up in someone's diff. A config with comments already fails to load, so
5470
- * there is no comment-preserving case to protect.
5564
+ * IS reformatted by the write — cosmetic, but worth knowing before it shows up
5565
+ * in someone's diff. A config with comments already fails to load, so there is
5566
+ * no comment-preserving case to protect.
5471
5567
  */
5472
- function specEnvReviewAllow(dir, config, tier, specArg, flags) {
5473
- const TIERS = { network: 'allowNetwork', remote: 'allowRemote' }
5474
- const key = TIERS[String(tier || '').trim()]
5475
- if (!key) {
5568
+ function specEnvReviewAllow(dir, config, tier, _specArg, flags) {
5569
+ const said = String(tier || '').trim()
5570
+ if (said === 'remote') {
5571
+ process.stdout.write(
5572
+ 'spec-env review allow: remote is no longer a setting — publishing the review was retired.\n' +
5573
+ ' `remote:` is now the tailnet address of the review server, on whenever network is.\n' +
5574
+ ' Nothing changed.\n',
5575
+ )
5576
+ process.exitCode = 1
5577
+ return
5578
+ }
5579
+ if (said !== 'network') {
5476
5580
  // Refused by name, never coerced to a default: silently permitting the
5477
5581
  // wrong tier is the one outcome worth more than a round trip.
5478
5582
  process.stdout.write(
5479
- `spec-env review allow: ${JSON.stringify(tier || '')} is not a tier — ` +
5480
- `one of ${Object.keys(TIERS).join(', ')}. Nothing changed.\n`,
5583
+ `spec-env review allow: ${JSON.stringify(tier || '')} is not a tier — network is the one ` +
5584
+ 'setting. Nothing changed.\n',
5481
5585
  )
5482
5586
  process.exitCode = 1
5483
5587
  return
5484
5588
  }
5589
+ const key = 'allowNetwork'
5485
5590
 
5486
- // WHICH SPEC, for the per-spec scope — resolved before anything is read, so a
5487
- // refusal changes nothing. An unknown name throws rather than falling back:
5488
- // permitting the wrong spec to publish looks exactly like permitting the
5489
- // right one.
5490
- const perSpec = key === 'allowRemote' && !flags.project
5491
- let spec = null
5492
- let out = null
5493
- if (perSpec) {
5494
- try {
5495
- spec = resolveSpecWithWorktree(dir, config, specArg)
5496
- } catch (err) {
5497
- process.stdout.write(
5498
- `spec-env review allow: ${err.message}\n` +
5499
- ' remote is permitted per spec — name it, or run this from its worktree.\n' +
5500
- ' --project permits every spec instead (writes the committed env.config.json).\n' +
5501
- ' Nothing changed.\n',
5502
- )
5503
- process.exitCode = 1
5504
- return
5505
- }
5506
- out = reviewOutPath(dir, spec.folder, null)
5507
- }
5508
-
5509
- // What the tier is now, through the same precedence the render uses — so a
5510
- // toggle means "the other thing the render showed".
5511
5591
  const file = path.resolve(dir, 'specs/.core/env.config.json')
5512
- const committed = () => {
5592
+ const current = () => {
5513
5593
  try {
5514
5594
  const now = JSON.parse(fs.readFileSync(file, 'utf8'))
5515
- return now.review && now.review[key] !== undefined ? now.review[key] : config.review[key]
5595
+ return Boolean(now.review && now.review[key] !== undefined ? now.review[key] : config.review[key])
5516
5596
  } catch {
5517
- return config.review[key]
5518
- }
5519
- }
5520
- const current = () => {
5521
- if (perSpec) {
5522
- const own = readRemoteAllow(out)
5523
- if (own !== null) return own
5597
+ return Boolean(config.review[key])
5524
5598
  }
5525
- return Boolean(committed())
5526
5599
  }
5527
5600
 
5528
- // THREE WAYS TO SAY WHAT THE TIER SHOULD BE. Bare `allow <tier>` turns it ON
5601
+ // THREE WAYS TO SAY WHAT THE TIER SHOULD BE. Bare `allow network` turns it ON
5529
5602
  // and `--off` turns it off, exactly as they always have. `--set` exists
5530
5603
  // because a SLASH COMMAND can only make one static substitution: the word the
5531
5604
  // person typed reaches the engine as a word. An EMPTY value toggles.
5532
5605
  let on = !flags.off
5533
5606
  if (flags.set !== undefined) {
5534
- const said = String(flags.set).trim().toLowerCase()
5535
- if (said === '') {
5607
+ const state = String(flags.set).trim().toLowerCase()
5608
+ if (state === '') {
5536
5609
  on = !current()
5537
- } else if (said === 'on' || said === 'off') {
5538
- on = said === 'on'
5610
+ } else if (state === 'on' || state === 'off') {
5611
+ on = state === 'on'
5539
5612
  } else {
5540
5613
  // Refused by name, like an unknown tier. The wrong default here opens a
5541
- // port or permits a publish.
5614
+ // port.
5542
5615
  process.stdout.write(
5543
5616
  `spec-env review allow: ${JSON.stringify(String(flags.set))} is not a state — ` +
5544
5617
  'one of on, off, or nothing at all to toggle. Nothing changed.\n',
@@ -5549,76 +5622,35 @@ function specEnvReviewAllow(dir, config, tier, specArg, flags) {
5549
5622
  }
5550
5623
 
5551
5624
  const before = current()
5552
- let wrote
5553
- if (perSpec) {
5554
- wrote = writeRemoteAllow(out, on)
5555
- } else {
5556
- let parsed
5557
- try {
5558
- parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
5559
- } catch (err) {
5560
- // Cannot tell what is in there, so write nothing. Reachable only if the
5561
- // file changes between `loadEnvConfig` and here — that load already
5562
- // refuses an unparseable config.
5563
- process.stdout.write(
5564
- `spec-env review allow: ${file} could not be read as JSON (${err.message}) — ` +
5565
- 'nothing changed.\n',
5566
- )
5567
- process.exitCode = 1
5568
- return
5569
- }
5570
- parsed.review = { ...(parsed.review || {}), [key]: on }
5571
- fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n')
5572
- wrote = file
5625
+ let parsed
5626
+ try {
5627
+ parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
5628
+ } catch (err) {
5629
+ // Cannot tell what is in there, so write nothing. Reachable only if the
5630
+ // file changes between `loadEnvConfig` and here — that load already
5631
+ // refuses an unparseable config.
5632
+ process.stdout.write(
5633
+ `spec-env review allow: ${file} could not be read as JSON (${err.message}) — ` +
5634
+ 'nothing changed.\n',
5635
+ )
5636
+ process.exitCode = 1
5637
+ return
5573
5638
  }
5639
+ parsed.review = { ...(parsed.review || {}), [key]: on }
5640
+ fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n')
5574
5641
 
5575
5642
  const lines = [
5576
- `spec-env review allow: ${tier} reviews${spec ? ` for ${spec.folder}` : ''} are now ${on ? 'ON' : 'OFF'}` +
5577
- (before === on ? ' (unchanged)' : ''),
5643
+ `spec-env review allow: network reviews are now ${on ? 'ON' : 'OFF'}` + (before === on ? ' (unchanged)' : ''),
5578
5644
  // THE ABSOLUTE PATH. `dir` is re-anchored to the primary checkout, so run
5579
5645
  // from a worktree this writes in a different tree — and a relative path
5580
5646
  // reads as the tree you are standing in.
5581
- ` wrote: ${wrote}`,
5647
+ ` wrote: ${file}`,
5648
+ ' that is the primary checkout, whichever tree you ran this from, and the file is',
5649
+ ' COMMITTED — so it changes for everyone who pulls, and leaves that tree dirty.',
5650
+ on
5651
+ ? ' the next render binds every interface, so the page opens on your phone and your tailnet.'
5652
+ : ' the next render binds 127.0.0.1 only, reachable from this machine.',
5582
5653
  ]
5583
- if (perSpec) {
5584
- lines.push(' this spec only, in the gitignored review store — the committed config is untouched.')
5585
- } else {
5586
- lines.push(
5587
- ' that is the primary checkout, whichever tree you ran this from, and the file is',
5588
- ' COMMITTED — so it changes for everyone who pulls, and leaves that tree dirty.',
5589
- )
5590
- }
5591
- if (key === 'allowNetwork') {
5592
- lines.push(
5593
- on
5594
- ? ' the next render binds every interface, so the page opens on your phone.'
5595
- : ' the next render binds 127.0.0.1 only, reachable from this machine.',
5596
- )
5597
- } else if (!on) {
5598
- lines.push(
5599
- ' publishing is no longer permitted; any page already published stays up.\n' +
5600
- ' turn it back on with: /spec-remote-review',
5601
- )
5602
- } else {
5603
- lines.push(
5604
- ' a published page cannot be deleted by skitterspec,\n' +
5605
- ' and a verdict there needs /spec-reviewed.\n' +
5606
- ' turn it back off with: /spec-remote-review',
5607
- )
5608
- // THE REVIEW IT WAS TYPED FOR. The banner names this command beside a page
5609
- // the reader cannot reach, so turning remote on is the ask to publish THAT
5610
- // page — and saying nothing about it left the reader with no link at all.
5611
- // A page on disk is the positive signal; with none there is nothing to
5612
- // publish, and nothing is named.
5613
- if (spec && fs.existsSync(out)) {
5614
- lines.push(
5615
- ` review: ${spec.folder} has a page — publish it and re-show the stack`,
5616
- ` publish: skitterspec spec-env review ${spec.folder} --publish-copy`,
5617
- )
5618
- } else {
5619
- lines.push(' this PERMITS publishing; it publishes nothing.')
5620
- }
5621
- }
5622
5654
  process.stdout.write(lines.join('\n') + '\n')
5623
5655
  }
5624
5656
 
@@ -5730,9 +5762,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
5730
5762
  // CHECKOUT, keyed by the spec's folder name; not one byte of it comes from
5731
5763
  // the worktree. `--out` moves the page and its sidecars together.
5732
5764
  const out = reviewOutPath(dir, spec.folder, flags.out)
5733
- // This spec's own remote permission over the project default — a
5734
- // per-worktree decision, never the committed config (bug-remote-review-toggle).
5735
- config = withSpecRemote(config, out)
5736
5765
 
5737
5766
  // The other half of a confirmation: a pass the operator says is not theirs.
5738
5767
  // Left in the store it is reported on every render until they stop reading the
@@ -6451,21 +6480,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6451
6480
  /* the page is the artefact; this is a note for the daemon */
6452
6481
  }
6453
6482
 
6454
- // The publish-ready copy, ONLY when asked. An ordinary render must not pay for
6455
- // a second copy of the whole diff on disk for a path most renders never take.
6456
- let publishCopy = null
6457
- if (flags.publishCopy) {
6458
- publishCopy = reviewPublishPath(out)
6459
- writeReviewPage(
6460
- publishCopy,
6461
- renderReviewFragment(data, { reviewHtml: renderReviewBlock(data.review) }),
6462
- )
6463
- }
6464
-
6465
- // Read, never written, and never interpreted: the engine cannot publish, and
6466
- // names this file only so the skill that can never has to build a path.
6467
- const urlFile = reviewUrlPath(out)
6468
- const url = readReviewUrl(out)
6469
6483
 
6470
6484
  // Resolved before the --json early return, so both outputs agree.
6471
6485
  const reader = resolveReader(config, process.env, process.platform)
@@ -6537,7 +6551,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6537
6551
 
6538
6552
  // ONE STACK for both outputs, so `--json` and the text cannot disagree about
6539
6553
  // which tiers exist — or which one is hidden.
6540
- const stackTiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: url, config, reader })
6554
+ const stackTiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), config, reader })
6541
6555
 
6542
6556
  if (flags.json) {
6543
6557
  process.stdout.write(
@@ -6559,7 +6573,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6559
6573
  // project folder.
6560
6574
  ...(docs ? { docs: { paths: docs.owned.map((p) => projectRelative(p, prefixOf(config))) } } : {}),
6561
6575
  out,
6562
- publishCopy,
6563
6576
  reader: reader.reader,
6564
6577
  readerWhy: reader.why,
6565
6578
  served,
@@ -6580,8 +6593,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6580
6593
  ...(served ? {} : noServeBecause ? { notServed: noServeBecause } : {}),
6581
6594
  ...(serverSaid ? { server: serverSaid } : {}),
6582
6595
  fileUrl: reviewFileUrl(out),
6583
- urlFile,
6584
- url,
6585
6596
  notesFile: reviewNotesPath(out),
6586
6597
  // Absent stays absent, exactly as it is in the page payload: the
6587
6598
  // committing set is what a caller that did not ask always got, so
@@ -6688,16 +6699,15 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6688
6699
  // use, and the engine cannot know — that guess failed three separate ways
6689
6700
  // in one day. Now every tier is listed, labelled, and either a URL or the
6690
6701
  // one command that turns it on.
6691
- // The runners-up print as `also:` lines inside the network tier's own
6692
- // rendering — `reviewTierLine` carries them, which is what puts them
6693
- // under `network:` rather than dangling after the stack (they used to
6694
- // print below `remote:`, against the comment that placed them).
6702
+ // Any runners-up print as `also:` lines inside their tier's own
6703
+ // rendering — `reviewTierLine` carries them.
6695
6704
  reviewStackText(stackTiers) +
6696
- // WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
6697
- // `network` are two doors into one room — the page POSTs to
6698
- // `location.pathname`, so both reach this server and this pending store.
6699
- // `remote` writes to the artifact's own store, which nothing here can see.
6700
- ` the wait covers ${waitCovers(stackTiers).join(' + ')}; a remote verdict needs /spec-reviewed.\n` +
6705
+ // WHICH TIERS THE WAIT COVERS, once, next to the stack. Every served door
6706
+ // is one room — the page POSTs to `location.pathname`, so each reaches
6707
+ // this server and this pending store.
6708
+ // Nothing at all for a `file://` page: there is no door to watch, and
6709
+ // the `not served:` line below says why.
6710
+ (waitCovers(stackTiers).length ? ` the wait covers ${waitCovers(stackTiers).join(' + ')}.\n` : '') +
6701
6711
  // WHETHER IT IS ALSO RUNNING SOMEWHERE, which is the other way to judge a
6702
6712
  // change. `unavailable` prints nothing — see `liveStateLine`.
6703
6713
  (liveStateLine(live) ? `${liveStateLine(live)}\n` : '') +
@@ -6711,9 +6721,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6711
6721
  // One line, and only when something was actually done on the reader's
6712
6722
  // behalf. An action nobody asked for is reported, not hidden.
6713
6723
  (serverSaid ? ` ${serverSaid}\n` : '') +
6714
- // Named on its own line so the skill never has to build the path itself.
6715
- (publishCopy ? ` publish: ${publishCopy}\n` : '') +
6716
- (url ? ` published: ${url}\n` : '') +
6717
6724
  (t.files === 0 ? ' nothing to review — no changes found.\n' : ''),
6718
6725
  )
6719
6726
  }
@@ -7663,7 +7670,9 @@ function bareLive(dir, config) {
7663
7670
  return { action: 'status', specArg: undefined }
7664
7671
  }
7665
7672
 
7666
- const choice = provisionedSpecChoice(dir, config)
7673
+ // The last-live record is a hint for READING which spec you mean, never for a
7674
+ // bare command that switches a branch on it — that stays one possible meaning.
7675
+ const choice = provisionedSpecChoice(dir, config, process.cwd(), { lastLive: false })
7667
7676
  if (!choice.folder) {
7668
7677
  // Several worktrees is the only cannot-tell the status report does not
7669
7678
  // explain — it reports on the repo, not on what you might have meant. With
@@ -7835,6 +7844,9 @@ async function specEnvLiveTake(dir, config, specArg, flags = {}) {
7835
7844
  return
7836
7845
  }
7837
7846
  const receipt = writeReceipt(dir, config, plan.receipt)
7847
+ // Another spec is now the one on this checkout; the last release no longer is.
7848
+ const last = readLastLive(dir, config)
7849
+ if (last && last.spec !== spec.folder) clearLastLive(dir, config)
7838
7850
 
7839
7851
  const out = [`spec-env live take: ${spec.folder} is live on the primary checkout`]
7840
7852
  out.push('')
@@ -7906,10 +7918,17 @@ async function specEnvLiveRelease(dir, config, specArg) {
7906
7918
  }
7907
7919
  if (worktreeExists) runGit(spec.worktreePath, ['switch', spec.branch])
7908
7920
  clearReceipt(dir, config)
7921
+ // Remembered so a bare resolve from here still names this spec — the session
7922
+ // is now standing in the primary checkout, which says nothing on its own.
7923
+ writeLastLive(dir, config, { spec: spec.folder, worktree: spec.projectPath })
7909
7924
 
7910
7925
  process.stdout.write(
7911
7926
  `spec-env live release: ${spec.folder} released — primary back on ${base}, ` +
7912
7927
  `${spec.branch} re-isolated to its worktree.\n` +
7928
+ // The project folder, not the worktree root: it is what `/spec-next
7929
+ // --worktree` checks against `resolve`'s own `worktree:` line.
7930
+ ` worktree: ${spec.projectPath}\n` +
7931
+ ` next: /spec-next --worktree ${shellPath(spec.projectPath)}\n` +
7913
7932
  runAfterSwitch(plan.afterSwitch).lines.map((l) => `${l}\n`).join('') +
7914
7933
  plan.warnings.map((w) => ` ! ${w}\n`).join(''),
7915
7934
  )
@@ -8127,19 +8146,17 @@ async function specEnv(rest) {
8127
8146
  else if (args[i] === '--stop') flags.stop = true
8128
8147
  else if (args[i] === '--rotate-token') flags.rotateToken = true
8129
8148
  else if (args[i] === '--off') flags.off = true
8130
- else if (args[i] === '--project') flags.project = true
8131
8149
  else if (args[i] === '--status') flags.status = true
8132
8150
  else if (args[i] === '--port') flags.port = args[++i]
8133
8151
  else if (args[i] === '--host') flags.host = args[++i]
8134
- else if (args[i] === '--publish-copy') flags.publishCopy = true
8135
8152
  else if (args[i] === '--buttons') flags.buttons = args[++i]
8136
8153
  else if (args[i] === '--out') flags.out = args[++i]
8137
8154
  else if (args[i] === '--review') flags.review = args[++i]
8138
8155
  else if (args[i] === '--run-reviewers') flags.runReviewers = true
8139
8156
  else if (args[i] === '--notes') flags.notes = args[++i]
8140
8157
  else if (args[i] === '--verdict') flags.verdict = args[++i]
8141
- // `--set` keeps an EMPTY STRING rather than coercing it away: empty is the
8142
- // bare `/spec-remote-review`, and it means toggle. `??` so a missing value
8158
+ // `--set` keeps an EMPTY STRING rather than coercing it away: empty means
8159
+ // toggle. `??` so a missing value
8143
8160
  // at the end of argv is still the empty form rather than `undefined`, which
8144
8161
  // would read as the flag never having been passed.
8145
8162
  else if (args[i] === '--set') flags.set = args[++i] ?? ''
@@ -8382,7 +8399,7 @@ async function specEnvDispatch(sub, dir, config, positional, flags, present, inv
8382
8399
  `Usage: skitterspec spec-env <${SPEC_ENV_VERBS.join('|')}> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--run-reviewers] [--notes <json>] [--verdict <word>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--buttons <set>] [--json] [--record-primary] [--assert-primary-clean]\n` +
8383
8400
  ' review serve [--port <n>] [--host <addr>] [--stop] [--status] serve every diff locally\n' +
8384
8401
  ' review serve --rotate-token mint a new URL token; every handed-out link dies\n' +
8385
- ' review allow <network|remote> [<spec>] [--off] [--project] permit a review tier\n' +
8402
+ ' review allow network [--off] permit the network and tailnet tiers\n' +
8386
8403
  ' (network: env.config.json; remote: this spec only)\n' +
8387
8404
  ' review arm [spec] [--phase <n>] a phase ended — its diff now owes a verdict\n' +
8388
8405
  ' review gate [spec] [--check] [--json] is one owed? --check exits non-zero if so\n' +
@@ -8540,6 +8557,36 @@ async function run(argv) {
8540
8557
  resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
8541
8558
  await cleanupReleaseTooling(dir, opts)
8542
8559
  break
8560
+ case 'uninstall': {
8561
+ // What is in flight is read here, where the spec machinery lives, and
8562
+ // handed to the engine: every provisioned worktree (specless ones too)
8563
+ // and a live overlay holding the primary checkout. A read that throws is
8564
+ // cannot-tell, and the engine refuses on it rather than deleting.
8565
+ const inFlight = []
8566
+ let cannotTell = null
8567
+ try {
8568
+ // Anchored as spec-env anchors, so a project in a subfolder of its
8569
+ // repo, or a run from inside a worktree, reads the same registry.
8570
+ const anchor = primaryAnchor(dir, gitReader(dir))
8571
+ const { config } = loadEnvConfig(anchor.dir)
8572
+ attachProject(config, anchor)
8573
+ for (const w of provisionedSpecChoice(anchor.dir, config, anchor.dir, { lastLive: false }).worktrees) {
8574
+ inFlight.push({ spec: w.spec, where: `(worktree ${w.worktree})` })
8575
+ }
8576
+ const receipt = readReceipt(anchor.dir, config)
8577
+ if (receipt && receipt.spec) inFlight.push({ spec: String(receipt.spec), where: '(live in the primary checkout)' })
8578
+ } catch (error) {
8579
+ cannotTell = error.message
8580
+ }
8581
+ process.exitCode = uninstall(dir, { yes: opts.yes, inFlight, cannotTell })
8582
+ break
8583
+ }
8584
+ case 'disable':
8585
+ process.exitCode = disable(dir)
8586
+ break
8587
+ case 'enable':
8588
+ process.exitCode = await enable(dir)
8589
+ break
8543
8590
  default:
8544
8591
  throw new Error(unknownCommand(cmd))
8545
8592
  }