@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/init.js CHANGED
@@ -6,8 +6,8 @@ const crypto = require('crypto')
6
6
  const { execFileSync } = require('child_process')
7
7
 
8
8
  const { ensureWorktreeDirTrusted } = require('./env/trust.js')
9
- const { ensureHooks, removeHooks } = require('./env/hooks.js')
10
- const { repoInfo, expandTokens } = require('./env/resolve.js')
9
+ const { ensureHooks, removeHooks, HOOKS: GATE_HOOKS } = require('./env/hooks.js')
10
+ const { repoInfo, expandTokens, describeBaseBranch, baseRemote } = require('./env/resolve.js')
11
11
  const { primaryAnchor } = require('./env/project.js')
12
12
  const { setProjectKeys } = require('./env/projectedit.js')
13
13
 
@@ -318,6 +318,7 @@ const report = { created: [], updated: [], skipped: [], refused: [], removed: []
318
318
 
319
319
  function resetReport() {
320
320
  scope = 'team'
321
+ enabledOnFlush = null
321
322
  for (const k of Object.keys(report)) report[k].length = 0
322
323
  for (const k of Object.keys(writtenHashes)) delete writtenHashes[k]
323
324
  }
@@ -424,20 +425,25 @@ function readManifest(dir) {
424
425
  // Absent means team: every manifest written before `--local` existed
425
426
  // reads exactly as it did.
426
427
  scope: parsed.scope === 'local' ? 'local' : 'team',
428
+ // Absent means enabled: only `disable` writes the field.
429
+ enabled: parsed.enabled !== false,
427
430
  }
428
431
  }
429
432
  } catch {
430
433
  /* missing or malformed → empty baseline */
431
434
  }
432
- return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team' }
435
+ return { version: MANIFEST_VERSION, files: {}, baselined: false, scope: 'team', enabled: true }
433
436
  }
434
437
 
435
- function writeManifest(dir, files, { local = false } = {}) {
438
+ function writeManifest(dir, files, { local = false, enabled = true } = {}) {
436
439
  const target = path.join(dir, MANIFEST_FILE)
437
440
  ensureDir(path.dirname(target))
438
441
  const sorted = {}
439
442
  for (const k of Object.keys(files).sort()) sorted[k] = files[k]
440
443
  const body = local ? { version: MANIFEST_VERSION, scope: 'local', files: sorted } : { version: MANIFEST_VERSION, files: sorted }
444
+ // Written only when false, so an enabled install's manifest reads exactly as
445
+ // every manifest written before `disable` existed.
446
+ if (!enabled) body.enabled = false
441
447
  fs.writeFileSync(target, JSON.stringify(body, null, 2) + '\n')
442
448
  }
443
449
 
@@ -499,7 +505,8 @@ function flushManifest(dir) {
499
505
  // env.config.json that installIsolation happens to write through writeFile).
500
506
  const managed = managedTargets(dir)
501
507
  const managedRel = new Set(managed.map((t) => t.relPath))
502
- const merged = { ...readManifest(dir).files, ...writtenHashes }
508
+ const prior = readManifest(dir)
509
+ const merged = { ...prior.files, ...writtenHashes }
503
510
  const next = {}
504
511
  for (const [relPath, hash] of Object.entries(merged)) {
505
512
  if (managedRel.has(relPath)) next[relPath] = hash
@@ -510,9 +517,13 @@ function flushManifest(dir) {
510
517
  for (const relPath of Object.keys(next)) {
511
518
  if (!fs.existsSync(path.join(dir, relPath))) delete next[relPath] // prune gone
512
519
  }
513
- writeManifest(dir, next, { local: scope === 'local' })
520
+ writeManifest(dir, next, { local: scope === 'local', enabled: enabledOnFlush === null ? prior.enabled : enabledOnFlush })
514
521
  }
515
522
 
523
+ // Set by a run that decides the install's switch: `init` turns it on, and
524
+ // `null` keeps whatever the manifest says (`update` on a disabled install).
525
+ let enabledOnFlush = null
526
+
516
527
  function writeFile(dir, target, content, { force }) {
517
528
  // A dangling symlink (its target no longer exists) is invisible to existsSync,
518
529
  // which follows the link — but the link itself is still on disk, so a plain
@@ -1004,8 +1015,14 @@ function resync(dir, { force = false, claudeMd = true, diff = false, local = fal
1004
1015
  // `update` copied `.claude/hooks/` and registered nothing, for every upgrading
1005
1016
  // project, while reporting a file created. `init-review-gate-hook.test.js`
1006
1017
  // asserts over the entry points rather than over this call.
1007
- registerReviewGateHook(dir)
1008
- if (claudeMd) installClaudeMd(dir, { mode: 'update' })
1018
+ // A disabled install stays disabled through an update: the files refresh,
1019
+ // and the two things Claude reads from outside them are not written back.
1020
+ const disabled = scope === 'local' && !manifest.enabled
1021
+ if (disabled) report.skipped.push('hooks and CLAUDE.local.md block (disabled — skitterspec enable turns them on)')
1022
+ else {
1023
+ registerReviewGateHook(dir)
1024
+ if (claudeMd) installClaudeMd(dir, { mode: 'update' })
1025
+ }
1009
1026
  suggestReleaseWith(dir)
1010
1027
  flushManifest(dir)
1011
1028
  if (scope === 'local') writeLocalExcludes(dir)
@@ -1205,8 +1222,10 @@ function suggestReleaseWith(dir) {
1205
1222
  // Switching a local install back to team is out of scope and says so.
1206
1223
  function resolveScope(dir, local) {
1207
1224
  const recorded = readManifest(dir).scope
1208
- scope = local || recorded === 'local' ? 'local' : 'team'
1225
+ const excluded = !local && recorded !== 'local' && excludeNamesManifest(dir)
1226
+ scope = local || recorded === 'local' || excluded ? 'local' : 'team'
1209
1227
  if (!local && recorded === 'local') report.skipped.push('local install (recorded in the manifest) — kept local')
1228
+ if (excluded) report.skipped.push('local install (recorded in .git/info/exclude) — kept local')
1210
1229
  if (local && recorded !== 'local') {
1211
1230
  report.warnings.push(
1212
1231
  '--local keeps skitterspec on this machine: teammates get none of its skills, rules ' +
@@ -1243,11 +1262,16 @@ function localExcludes(dir) {
1243
1262
  }
1244
1263
 
1245
1264
  // What `spec-env bootstrap` seeds into a local install's worktrees: the managed
1246
- // paths plus the two per-machine files. A worktree is a fresh checkout, and
1247
- // git carries none of it there. Empty for a team install, which git carries.
1265
+ // paths, the two per-machine files and the manifest. A worktree is a fresh
1266
+ // checkout, and git carries none of it there. Empty for a team install, which
1267
+ // git carries.
1268
+ //
1269
+ // THE MANIFEST IS SEEDED because it is what records the scope: without it a
1270
+ // worktree's `update` read team and wrote the block into the tracked CLAUDE.md
1271
+ // and the hooks into a new .claude/settings.json (bug-local-scope-worktree).
1248
1272
  function localSeedFiles(dir) {
1249
1273
  if (readManifest(dir).scope !== 'local') return []
1250
- return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md']
1274
+ return [...localManagedPaths(dir), '.claude/settings.local.json', 'CLAUDE.local.md', MANIFEST_FILE.replace(/\\/g, '/')]
1251
1275
  }
1252
1276
 
1253
1277
  const EXCLUDE_START = '# >>> skitterspec (local install)'
@@ -1288,6 +1312,31 @@ function writeLocalExcludes(dir) {
1288
1312
  report.updated.push('.git/info/exclude (skitterspec block)')
1289
1313
  }
1290
1314
 
1315
+ // Whether the shared `.git/info/exclude` block names THIS project's manifest —
1316
+ // the positive signal that a worktree with no manifest of its own belongs to a
1317
+ // local install. The exclude lives in the common dir, so every worktree sees
1318
+ // the block the primary checkout's install wrote; matching the prefixed
1319
+ // manifest path, not the bare block, keeps a second project in the same repo
1320
+ // from being read as local by a neighbour's install.
1321
+ //
1322
+ // WHAT WOULD FOOL IT: a block hand-edited to drop the manifest line, or git
1323
+ // unreachable. Both answer false — the scope the manifest recorded, as before.
1324
+ function excludeNamesManifest(dir) {
1325
+ try {
1326
+ const git = (...args) => execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
1327
+ const commonDir = path.resolve(dir, git('rev-parse', '--git-common-dir'))
1328
+ const prefix = git('rev-parse', '--show-prefix')
1329
+ const text = fs.readFileSync(path.join(commonDir, 'info', 'exclude'), 'utf8')
1330
+ const start = text.indexOf(EXCLUDE_START)
1331
+ const end = text.indexOf(EXCLUDE_END, start)
1332
+ if (start === -1 || end === -1) return false
1333
+ const entry = `/${prefix}${MANIFEST_FILE.replace(/\\/g, '/')}`
1334
+ return text.slice(start, end).split(/\r?\n/).some((l) => l.trim() === entry)
1335
+ } catch {
1336
+ return false
1337
+ }
1338
+ }
1339
+
1291
1340
  // Convert a COMMITTED (team) install into a local one, in place. Every step
1292
1341
  // leaves the files on disk and stages or edits only; it never commits — the
1293
1342
  // operator commits the removal, and teammates who pull it lose the install.
@@ -1304,9 +1353,9 @@ function writeLocalExcludes(dir) {
1304
1353
  function convertCommitted(dir) {
1305
1354
  const git = (...args) =>
1306
1355
  execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
1356
+ const candidates = [...new Set(localExcludes(dir))].filter((p) => !p.endsWith('/'))
1307
1357
  let tracked
1308
1358
  try {
1309
- const candidates = [...new Set(localExcludes(dir))].filter((p) => !p.endsWith('/'))
1310
1359
  tracked = git('ls-files', '--', ...candidates).split('\n').filter(Boolean)
1311
1360
  } catch {
1312
1361
  return // not a git repo — writeLocalExcludes says so
@@ -1372,6 +1421,444 @@ function convertCommitted(dir) {
1372
1421
  'the conversion is staged, not committed — commit it (/commit) and teammates who pull it lose the install',
1373
1422
  )
1374
1423
  }
1424
+
1425
+ for (const row of branchesCarryingInstall(dir, candidates)) {
1426
+ if (row.cannotTell) {
1427
+ report.warnings.push(`${row.ref}: cannot tell whether it still commits the install — git could not read it`)
1428
+ continue
1429
+ }
1430
+ const what = [`${row.files} managed file(s)`, ...(row.hooks ? [`${row.hooks} hook(s)`] : [])].join(', ')
1431
+ report.suggestions.push(
1432
+ `${row.ref} still commits the install (${what})${row.remote ? ' — as of the last fetch' : ''}. ` +
1433
+ 'Anyone working from it still gets the skills: merge this conversion into it, or run ' +
1434
+ '`skitterspec init --local` on it and commit',
1435
+ )
1436
+ }
1437
+ }
1438
+
1439
+ // The long-lived branches — the base, `hotfix.releaseBranch`, the remote's
1440
+ // default — that still commit the install this conversion takes out of git.
1441
+ // A conversion is per branch, so a quarter branch converted and a `master` left
1442
+ // as it was still hands every teammate on `master` the whole workflow.
1443
+ // Feature branches are not asked: they catch up when they merge the base.
1444
+ //
1445
+ // Each name is read as its remote-tracking ref where one exists (what
1446
+ // teammates pull), else as the local branch. The branch being converted is
1447
+ // skipped — its own state is the staged conversion above.
1448
+ //
1449
+ // WHAT WOULD FOOL THIS: remote-tracking refs are as of the last fetch, and this
1450
+ // never fetches. A branch cleaned on the remote since then is still reported
1451
+ // (and says "as of the last fetch"); one that regained the install is missed.
1452
+ // A base that does not resolve (the gap between release branches) is not a
1453
+ // candidate at all, so it is skipped rather than reported clean.
1454
+ function branchesCarryingInstall(dir, candidates) {
1455
+ const read = (args) => {
1456
+ try {
1457
+ return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
1458
+ } catch {
1459
+ return null
1460
+ }
1461
+ }
1462
+ let config = null
1463
+ try {
1464
+ config = require('./env/config.js').loadEnvConfig(dir).config
1465
+ } catch {
1466
+ /* unreadable config — the base still resolves from git alone */
1467
+ }
1468
+ const remote = baseRemote(config)
1469
+ const names = []
1470
+ try {
1471
+ const { base } = describeBaseBranch(config, read)
1472
+ if (base) names.push(base)
1473
+ } catch {
1474
+ /* cannot tell — no candidate */
1475
+ }
1476
+ const release = config && config.hotfix && typeof config.hotfix.releaseBranch === 'string' && config.hotfix.releaseBranch.trim()
1477
+ if (release) names.push(release)
1478
+ const head = read(['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`])
1479
+ if (head) names.push(head.startsWith(`${remote}/`) ? head.slice(remote.length + 1) : head)
1480
+
1481
+ const current = read(['symbolic-ref', '--short', 'HEAD'])
1482
+ const rows = []
1483
+ for (const name of new Set(names)) {
1484
+ if (name === current) continue
1485
+ const exists = (ref) => read(['show-ref', '--verify', '--quiet', ref]) !== null
1486
+ const ref = exists(`refs/remotes/${remote}/${name}`) ? `${remote}/${name}` : exists(`refs/heads/${name}`) ? name : null
1487
+ if (!ref) continue
1488
+ const listed = read(['ls-tree', '-r', '--name-only', ref, '--', ...candidates])
1489
+ if (listed === null) {
1490
+ rows.push({ ref, cannotTell: true })
1491
+ continue
1492
+ }
1493
+ const files = listed.split('\n').filter(Boolean).length
1494
+ const hooks = hooksAt(read, ref)
1495
+ if (hooks === null) {
1496
+ rows.push({ ref, cannotTell: true })
1497
+ continue
1498
+ }
1499
+ if (files || hooks) rows.push({ ref, files, hooks, remote: ref !== name })
1500
+ }
1501
+ return rows
1502
+ }
1503
+
1504
+ // Our hook entries in a ref's committed `.claude/settings.json` — 0 when it has
1505
+ // none or no such file, null when the file is there and not JSON.
1506
+ function hooksAt(read, ref) {
1507
+ const text = read(['show', `${ref}:./.claude/settings.json`])
1508
+ if (text === null) return 0
1509
+ let parsed
1510
+ try {
1511
+ parsed = JSON.parse(text)
1512
+ } catch {
1513
+ return null
1514
+ }
1515
+ const pre = parsed && parsed.hooks && Array.isArray(parsed.hooks.PreToolUse) ? parsed.hooks.PreToolUse : []
1516
+ return pre
1517
+ .flatMap((group) => (group && Array.isArray(group.hooks) ? group.hooks : []))
1518
+ .filter((h) => h && typeof h.command === 'string' && GATE_HOOKS.some((k) => k.re.test(h.command))).length
1519
+ }
1520
+
1521
+ // DISABLE / ENABLE — switch whether this machine's Claude uses a local install,
1522
+ // without touching its files (feat-uninstall-local). Claude Code has no single
1523
+ // switch covering skills, commands, rules and hooks, so the install is switched
1524
+ // through three settings in `.claude/settings.local.json`:
1525
+ // - `skillOverrides: { <name>: "off" }` — every managed skill and command
1526
+ // (command files are skills to Claude Code). Exact names: no wildcard.
1527
+ // - `claudeMdExcludes: ["**/.claude/rules/<file>"]` — every managed rule, as
1528
+ // a glob so the one entry matches in every worktree.
1529
+ // - our hooks and the CLAUDE.local.md block are taken out, and written back
1530
+ // from the shipped assets by `enable`, so nothing has to be saved.
1531
+ // Only entries naming OUR paths are written or removed: an override or exclude
1532
+ // the developer wrote is never taken.
1533
+ function switchNames() {
1534
+ return [...SKILLS, ...COMMANDS.map((c) => c.replace(/\.md$/, ''))]
1535
+ }
1536
+
1537
+ function ruleExcludes() {
1538
+ return RULES.map((r) => `**/.claude/rules/${r}`)
1539
+ }
1540
+
1541
+ // The local settings, parsed — `{}` when absent, null when not valid JSON.
1542
+ function readLocalSettings(dir) {
1543
+ try {
1544
+ const parsed = JSON.parse(fs.readFileSync(path.join(dir, '.claude', 'settings.local.json'), 'utf8'))
1545
+ return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
1546
+ } catch (error) {
1547
+ return error.code === 'ENOENT' ? {} : null
1548
+ }
1549
+ }
1550
+
1551
+ function writeLocalSettings(dir, settings) {
1552
+ const file = path.join(dir, '.claude', 'settings.local.json')
1553
+ if (!Object.keys(settings).length) {
1554
+ if (fs.existsSync(file)) fs.unlinkSync(file)
1555
+ return
1556
+ }
1557
+ ensureDir(path.dirname(file))
1558
+ fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n')
1559
+ }
1560
+
1561
+ // Take our override and exclude entries out of the local settings. Returns
1562
+ // false when the file is not valid JSON (left untouched).
1563
+ function clearSwitches(dir) {
1564
+ const settings = readLocalSettings(dir)
1565
+ if (settings === null) return false
1566
+ const names = new Set(switchNames())
1567
+ const globs = new Set(ruleExcludes())
1568
+ if (settings.skillOverrides && typeof settings.skillOverrides === 'object') {
1569
+ for (const name of Object.keys(settings.skillOverrides)) {
1570
+ if (names.has(name) && settings.skillOverrides[name] === 'off') delete settings.skillOverrides[name]
1571
+ }
1572
+ if (!Object.keys(settings.skillOverrides).length) delete settings.skillOverrides
1573
+ }
1574
+ if (Array.isArray(settings.claudeMdExcludes)) {
1575
+ settings.claudeMdExcludes = settings.claudeMdExcludes.filter((g) => !globs.has(g))
1576
+ if (!settings.claudeMdExcludes.length) delete settings.claudeMdExcludes
1577
+ }
1578
+ writeLocalSettings(dir, settings)
1579
+ return true
1580
+ }
1581
+
1582
+ function stripLocalClaudeBlock(dir) {
1583
+ const file = path.join(dir, 'CLAUDE.local.md')
1584
+ if (!fs.existsSync(file)) return false
1585
+ const text = fs.readFileSync(file, 'utf8')
1586
+ const re = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
1587
+ if (!re.test(text)) return false
1588
+ const next = text.replace(re, '\n')
1589
+ if (next.trim()) fs.writeFileSync(file, next.replace(/^\n+/, ''))
1590
+ else fs.unlinkSync(file)
1591
+ return true
1592
+ }
1593
+
1594
+ function rewriteManifestEnabled(dir, enabled) {
1595
+ const manifest = readManifest(dir)
1596
+ writeManifest(dir, manifest.files, { local: manifest.scope === 'local', enabled })
1597
+ }
1598
+
1599
+ // Turn a local install off for this machine's Claude. Deletes nothing, so it
1600
+ // refuses nothing about work in flight; returns the exit code.
1601
+ function disable(dir, { log = (s) => process.stdout.write(s) } = {}) {
1602
+ if (!fs.existsSync(path.join(dir, MANIFEST_FILE))) {
1603
+ log('disable: no skitterspec install here (no manifest) — nothing to disable.\n')
1604
+ return 0
1605
+ }
1606
+ const manifest = readManifest(dir)
1607
+ if (manifest.scope !== 'local') {
1608
+ log(
1609
+ 'disable: refused — this is a team install. Its hooks are in the committed settings,\n' +
1610
+ ' so they cannot be switched off for one person. disable works on a local install (init --local).\n',
1611
+ )
1612
+ return 1
1613
+ }
1614
+ const settings = readLocalSettings(dir)
1615
+ if (settings === null) {
1616
+ log('disable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
1617
+ return 1
1618
+ }
1619
+ const overrides = settings.skillOverrides && typeof settings.skillOverrides === 'object' ? settings.skillOverrides : {}
1620
+ for (const name of switchNames()) overrides[name] = 'off'
1621
+ settings.skillOverrides = overrides
1622
+ const excludes = Array.isArray(settings.claudeMdExcludes) ? settings.claudeMdExcludes : []
1623
+ for (const glob of ruleExcludes()) if (!excludes.includes(glob)) excludes.push(glob)
1624
+ settings.claudeMdExcludes = excludes
1625
+ writeLocalSettings(dir, settings)
1626
+ const hooks = removeHooks(dir, { local: true })
1627
+ if (hooks.emptied) writeLocalSettings(dir, {})
1628
+ const block = stripLocalClaudeBlock(dir)
1629
+ rewriteManifestEnabled(dir, false)
1630
+ log(
1631
+ `disable: skitterspec is off for Claude on this machine (${dir})\n` +
1632
+ ` ${switchNames().length} skills and commands switched off · ${RULES.length} rules excluded\n` +
1633
+ ` ${hooks.removed} hook(s) removed${block ? ' · CLAUDE.local.md block removed' : ''}\n` +
1634
+ ' the files stay on disk — skitterspec enable turns it back on. Restart Claude Code to pick it up.\n',
1635
+ )
1636
+ return 0
1637
+ }
1638
+
1639
+ // Turn a local install back on — and install it when there is nothing here to
1640
+ // turn on, since asking to use it has one meaning then.
1641
+ async function enable(dir, { log = (s) => process.stdout.write(s) } = {}) {
1642
+ const manifest = readManifest(dir)
1643
+ const present = fs.existsSync(path.join(dir, MANIFEST_FILE))
1644
+ const filesHere = managedTargets(dir).some((t) => !t.relPath.startsWith('specs') && fs.existsSync(t.abs))
1645
+ if (!present || (manifest.scope === 'local' && !filesHere)) {
1646
+ log('enable: no local install here — installing it (init --local).\n')
1647
+ // `update` mode installs the files and switches them on, and leaves the
1648
+ // project's committed config (isolation, gating) exactly as it is.
1649
+ await init({ dir, force: false, claudeMd: true, mode: 'update', local: true })
1650
+ return 0
1651
+ }
1652
+ if (manifest.scope !== 'local') {
1653
+ log('enable: refused — this is a team install, which is always on. enable works on a local install (init --local).\n')
1654
+ return 1
1655
+ }
1656
+ if (!clearSwitches(dir)) {
1657
+ log('enable: refused — .claude/settings.local.json is not valid JSON, and the switch is written there. Nothing changed.\n')
1658
+ return 1
1659
+ }
1660
+ resetReport()
1661
+ scope = 'local'
1662
+ registerReviewGateHook(dir)
1663
+ installClaudeMd(dir, { mode: 'init' })
1664
+ rewriteManifestEnabled(dir, true)
1665
+ log(
1666
+ `enable: skitterspec is on for Claude on this machine (${dir})\n` +
1667
+ ' skills, commands and rules switched back on · hooks registered · CLAUDE.local.md block written\n' +
1668
+ ' Restart Claude Code to pick it up.\n',
1669
+ )
1670
+ return 0
1671
+ }
1672
+
1673
+ // UNINSTALL — take a local install (`init --local`) back off this machine,
1674
+ // exactly: the managed files, our hooks in settings.local.json, the block in
1675
+ // CLAUDE.local.md, the exclude block, `.spec-env/` and the manifest. Nothing
1676
+ // under `specs/` is touched — it is committed and shared. Plans by default and
1677
+ // acts only with `yes`; returns the exit code.
1678
+ //
1679
+ // A file is deleted only when it is PRISTINE. An unrecognised hash is either
1680
+ // the developer's edit or a lost record, and only one of those is safe to
1681
+ // delete, so it is kept (`.claude/rules/negative-checks.md` rule 4) — but kept
1682
+ // under `.claude/` it would still be loaded, so it is PARKED in
1683
+ // `<git-common-dir>/skitterspec-kept/`: outside the tree, so git status is
1684
+ // unchanged, and never over an earlier parked copy.
1685
+ //
1686
+ // `inFlight` is the caller's list of provisioned specs and a held live overlay;
1687
+ // any entry refuses, because each worktree carries a seeded copy of the install
1688
+ // and a torn-down primary leaves nothing to finish them with. `cannotTell` is
1689
+ // the caller failing to read that list, which also refuses: deleting is the
1690
+ // destructive branch, so the unknown case does not get it.
1691
+ function uninstall(dir, { yes = false, inFlight = [], cannotTell = null, log = (s) => process.stdout.write(s) } = {}) {
1692
+ const manifestAbs = path.join(dir, MANIFEST_FILE)
1693
+ if (!fs.existsSync(manifestAbs)) {
1694
+ log('uninstall: no skitterspec install here (no manifest) — nothing to do.\n')
1695
+ return 0
1696
+ }
1697
+ const manifest = readManifest(dir)
1698
+ if (manifest.scope !== 'local') {
1699
+ log(
1700
+ 'uninstall: refused — this is a team install, committed for everyone.\n' +
1701
+ ' Removing it is a commit for the team to make, not one machine\'s command.\n' +
1702
+ ' uninstall only takes a local install (init --local) back off.\n',
1703
+ )
1704
+ return 1
1705
+ }
1706
+ if (cannotTell) {
1707
+ log(`uninstall: refused — cannot tell whether a spec is in flight (${cannotTell}).\n Nothing changed.\n`)
1708
+ return 1
1709
+ }
1710
+ if (inFlight.length) {
1711
+ log(
1712
+ 'uninstall: refused — work is still in flight here, and its worktrees carry a copy of the install:\n' +
1713
+ inFlight.map((f) => ` ${f.spec} ${f.where}\n`).join('') +
1714
+ ' Finish each with /spec-complete, drop it with /spec-cancel (or spec-env down <name>),\n' +
1715
+ ' and hand a live spec back with /spec-live main. Nothing changed.\n',
1716
+ )
1717
+ return 1
1718
+ }
1719
+
1720
+ // The files: every managed target outside specs/, plus any manifest entry
1721
+ // the package no longer ships (a retired skill is still a skill on disk).
1722
+ const targets = new Map()
1723
+ for (const t of managedTargets(dir)) targets.set(t.relPath.split(path.sep).join('/'), t.bundled)
1724
+ for (const k of Object.keys(manifest.files)) if (!targets.has(k)) targets.set(k, undefined)
1725
+ const remove = []
1726
+ const keep = []
1727
+ const exclude = localExcludeFile(dir)
1728
+ const parkRoot = exclude && path.join(path.dirname(path.dirname(exclude.file)), 'skitterspec-kept')
1729
+ const parkFor = (relPath) => {
1730
+ let target = path.join(parkRoot, relPath)
1731
+ for (let n = 2; fs.existsSync(target); n++) target = path.join(parkRoot, `${relPath}.${n}`)
1732
+ return target
1733
+ }
1734
+ for (const [relPath, bundled] of [...targets].sort(([a], [b]) => a.localeCompare(b))) {
1735
+ if (relPath.startsWith('specs/')) continue
1736
+ const state = managedState(dir, relPath, manifest, bundled)
1737
+ if (state === 'pristine') remove.push(relPath)
1738
+ else if (state !== 'missing') keep.push({ relPath, parked: parkRoot ? parkFor(relPath) : null })
1739
+ }
1740
+
1741
+ const hooks = removeHooks(dir, { local: true, dryRun: true })
1742
+ const switches = readLocalSettings(dir)
1743
+ const hasSwitches =
1744
+ switches !== null &&
1745
+ (Object.keys(switches.skillOverrides || {}).some((n) => switchNames().includes(n)) ||
1746
+ (Array.isArray(switches.claudeMdExcludes) && switches.claudeMdExcludes.some((g) => ruleExcludes().includes(g))))
1747
+ const claudeLocal = path.join(dir, 'CLAUDE.local.md')
1748
+ const blockRe = new RegExp(`\\n*${SPEC_MARKER_START}[\\s\\S]*?${SPEC_MARKER_END}\\n?`)
1749
+ const claudeText = fs.existsSync(claudeLocal) ? fs.readFileSync(claudeLocal, 'utf8') : null
1750
+ const hasBlock = claudeText !== null && blockRe.test(claudeText)
1751
+ const hasExclude = exclude !== null && exclude.text.includes(EXCLUDE_START)
1752
+ const specEnv = path.join(dir, '.spec-env')
1753
+
1754
+ const lines = []
1755
+ const say = (label, items) => {
1756
+ if (!items.length) return
1757
+ lines.push(`\n${label}:\n`)
1758
+ for (const it of items) lines.push(` ${it}\n`)
1759
+ }
1760
+ say(yes ? 'removed' : 'would remove', [
1761
+ ...remove,
1762
+ ...(hooks.reason === 'removed' ? [`.claude/settings.local.json (${hooks.removed} skitterspec hook(s)${hooks.emptied ? ', then the emptied file' : ''})`] : []),
1763
+ ...(hasSwitches ? ['.claude/settings.local.json (skitterspec disable switches)'] : []),
1764
+ ...(hasBlock ? ['CLAUDE.local.md (spec workflow block)'] : []),
1765
+ ...(hasExclude ? [`${path.relative(dir, exclude.file).split(path.sep).join('/')} (skitterspec block)`] : []),
1766
+ ...(fs.existsSync(specEnv) ? ['.spec-env/'] : []),
1767
+ MANIFEST_FILE.split(path.sep).join('/'),
1768
+ ])
1769
+ say(
1770
+ yes ? 'parked — edited since install, moved out of Claude\'s reach' : 'would park — edited since install',
1771
+ keep.map((k) => (k.parked ? `${k.relPath} → ${k.parked}` : `${k.relPath} (kept in place — no git dir to park it in)`)),
1772
+ )
1773
+ const warnings = []
1774
+ if (hooks.reason === 'malformed') warnings.push('.claude/settings.local.json is not valid JSON — skitterspec hooks left in it; remove them by hand')
1775
+ if (exclude === null) warnings.push('not a git repository — no exclude block to remove')
1776
+ say('warnings', warnings)
1777
+
1778
+ if (!yes) {
1779
+ log(`uninstall: plan — nothing changed (${dir})\n${lines.join('')}\n re-run with --yes to remove the local install.\n`)
1780
+ return 0
1781
+ }
1782
+
1783
+ const managedSet = new Set(targets.keys())
1784
+ const parents = new Set()
1785
+ for (const relPath of remove) {
1786
+ assertSafeToDelete(relPath, managedSet)
1787
+ fs.unlinkSync(path.join(dir, relPath))
1788
+ parents.add(path.dirname(path.join(dir, relPath)))
1789
+ }
1790
+ for (const k of keep) {
1791
+ if (!k.parked) continue
1792
+ fs.mkdirSync(path.dirname(k.parked), { recursive: true })
1793
+ try {
1794
+ fs.renameSync(path.join(dir, k.relPath), k.parked)
1795
+ } catch (error) {
1796
+ if (error.code !== 'EXDEV') throw error
1797
+ fs.copyFileSync(path.join(dir, k.relPath), k.parked)
1798
+ fs.unlinkSync(path.join(dir, k.relPath))
1799
+ }
1800
+ parents.add(path.dirname(path.join(dir, k.relPath)))
1801
+ }
1802
+ // Folders our files left empty — a skill's own, then .claude/<kind>/ — and
1803
+ // never one that still holds something of the developer's.
1804
+ const stop = path.join(dir, '.claude')
1805
+ for (const start of parents) {
1806
+ for (let at = start; at.startsWith(stop + path.sep); at = path.dirname(at)) {
1807
+ try {
1808
+ if (fs.readdirSync(at).length) break
1809
+ fs.rmdirSync(at)
1810
+ } catch {
1811
+ break
1812
+ }
1813
+ }
1814
+ }
1815
+ // A disabled install's switches go too, or they would outlive what they name.
1816
+ clearSwitches(dir)
1817
+ if (hooks.reason === 'removed') {
1818
+ const done = removeHooks(dir, { local: true })
1819
+ if (done.emptied) fs.unlinkSync(path.join(dir, '.claude', 'settings.local.json'))
1820
+ }
1821
+ if (hasBlock) {
1822
+ const next = claudeText.replace(blockRe, '\n')
1823
+ if (next.trim()) fs.writeFileSync(claudeLocal, next.replace(/^\n+/, ''))
1824
+ else fs.unlinkSync(claudeLocal)
1825
+ }
1826
+ if (hasExclude) {
1827
+ const start = exclude.text.indexOf(EXCLUDE_START)
1828
+ const end = exclude.text.indexOf(EXCLUDE_END, start)
1829
+ if (end !== -1) {
1830
+ fs.writeFileSync(exclude.file, exclude.text.slice(0, start) + exclude.text.slice(end + EXCLUDE_END.length).replace(/^\n/, ''))
1831
+ }
1832
+ }
1833
+ fs.rmSync(specEnv, { recursive: true, force: true })
1834
+ fs.unlinkSync(manifestAbs)
1835
+
1836
+ log(
1837
+ `uninstall: done (${dir})\n${lines.join('')}\n` +
1838
+ ` the CLI itself is still installed — npm uninstall -g ${distributionPackage()} removes it.\n`,
1839
+ )
1840
+ return 0
1841
+ }
1842
+
1843
+ // The git common dir's info/exclude, read — null when this is not a git repo.
1844
+ function localExcludeFile(dir) {
1845
+ let commonDir
1846
+ try {
1847
+ commonDir = path.resolve(
1848
+ dir,
1849
+ execFileSync('git', ['-C', dir, 'rev-parse', '--git-common-dir'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(),
1850
+ )
1851
+ } catch {
1852
+ return null
1853
+ }
1854
+ const file = path.join(commonDir, 'info', 'exclude')
1855
+ let text = ''
1856
+ try {
1857
+ text = fs.readFileSync(file, 'utf8')
1858
+ } catch {
1859
+ /* no exclude file */
1860
+ }
1861
+ return { file, text }
1375
1862
  }
1376
1863
 
1377
1864
  async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gating, project, local = false }) {
@@ -1379,6 +1866,12 @@ async function init({ dir, force, claudeMd, mode, isolation, workspaceMode, gati
1379
1866
  resetReport()
1380
1867
  resolveScope(dir, local)
1381
1868
  if (scope === 'local') convertCommitted(dir)
1869
+ // Installing is enabling: a disabled install comes back on.
1870
+ if (scope === 'local' && !readManifest(dir).enabled) {
1871
+ clearSwitches(dir)
1872
+ report.updated.push('.claude/settings.local.json (skitterspec enabled)')
1873
+ }
1874
+ enabledOnFlush = true
1382
1875
 
1383
1876
  installSkills(dir, { force })
1384
1877
  installCommands(dir, { force })
@@ -1422,6 +1915,9 @@ module.exports = {
1422
1915
  isExistingSetup,
1423
1916
  resync,
1424
1917
  reset,
1918
+ uninstall,
1919
+ disable,
1920
+ enable,
1425
1921
  assertSafeToDelete,
1426
1922
  assertComposedAssets,
1427
1923
  detectPackageManager,
@@ -1,37 +0,0 @@
1
- ---
2
- description: Permit or forbid publishing this spec's review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
3
- argument-hint: "[on | off]"
4
- allowed-tools: Bash({{exec}} skitterspec spec-env review allow remote:*)
5
- disable-model-invocation: true
6
- ---
7
- !`{{exec}} skitterspec spec-env review allow remote --set "$ARGUMENTS"`
8
-
9
- Relay the engine output above verbatim. Add nothing to it.
10
-
11
- **Then one thing, and only when the engine asked for it.** Where the output
12
- carries a `review:` and a `publish:` line, typing this command **is** the ask
13
- to publish that page: the banner named this command beside a review the reader
14
- could not reach, so the link is what they are waiting for. Publish it exactly
15
- as `/spec-diff` §6 describes (run the `publish:` command, publish the copy it
16
- names with a store, write the URL file), then re-emit the review banner with
17
- all three tiers, `remote` now carrying the URL. A wait already running keeps
18
- running; do not restart it or the server. If the harness refuses the publish,
19
- say so in one line and keep the banner as it was, because local and network
20
- still work.
21
-
22
- With no `publish:` line, run nothing else. Nothing has a page to publish, or
23
- the tier was turned off.
24
-
25
- **Bare toggles.** That is the common case: you are looking at a render whose
26
- `remote:` line says which way it currently is, and what you want is the other
27
- one. `on` and `off` are there for when you are not looking at it.
28
-
29
- **It is per spec.** The engine resolves the spec from the worktree you are
30
- standing in and records the permission in the gitignored review store, so
31
- the base branch is untouched and no other spec may publish because of it.
32
- `skitterspec spec-env review allow remote --project` is the committed,
33
- every-spec form, for a team that wants it.
34
-
35
- **A published page is one skitterspec cannot delete**, and a verdict pressed
36
- on one needs `/spec-reviewed`, because nothing pushes from an artifact's store
37
- into a conversation.