@skitterbyte/skitterspec-linear 19.16.0 → 19.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/MIGRATION.md +78 -0
- package/README.md +0 -1
- package/assets/claude-md-section.md +6 -9
- package/assets/commands/allow-main.md +1 -2
- package/assets/core/env.config.json.example +0 -1
- package/assets/core/env.config.md +24 -27
- package/assets/review/page.html +10 -83
- package/assets/rules/spec-planning.md +14 -21
- package/assets/rules/spec-reports.md +112 -54
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +2 -2
- package/assets/skills/spec-bug/SKILL.md +10 -13
- package/assets/skills/spec-diff/SKILL.md +47 -115
- package/assets/skills/spec-hotfix/SKILL.md +10 -13
- package/assets/skills/spec-next/SKILL.md +59 -42
- package/assets/skills/spec-review/SKILL.md +2 -2
- package/assets/skills/spec-reviewed/SKILL.md +1 -8
- package/package.json +1 -1
- package/src/cli.js +251 -204
- package/src/env/config.js +16 -7
- package/src/env/hooks.js +6 -3
- package/src/env/live.js +48 -0
- package/src/env/review.js +71 -173
- package/src/env/serve.js +3 -7
- package/src/init.js +509 -13
- package/assets/commands/spec-remote-review.md +0 -37
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
|
|
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
|
-
|
|
1008
|
-
|
|
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
|
-
|
|
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
|
|
1247
|
-
// git carries none of it there. Empty for a team install, which
|
|
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.
|