@skitterbyte/skitterspec-linear 19.4.0 → 19.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/env/review.js CHANGED
@@ -19,6 +19,7 @@ const fs = require('node:fs')
19
19
  const path = require('node:path')
20
20
  const crypto = require('node:crypto')
21
21
  const { readPhases, readOverview } = require('./resolve.js')
22
+ const { fromRepoPath, projectIn } = require('./project.js')
22
23
  const { execFileSync } = require('node:child_process')
23
24
 
24
25
  // `-U` large enough that a file's patch IS the file. Reviewing a changed line
@@ -40,8 +41,13 @@ const REVIEW_DIR = path.join('.spec-env', 'reviews')
40
41
  // push snapshot that lives among them. The ENGINE decides this, because it knows
41
42
  // the spec's own paths — a viewer guessing from regexes would get it wrong the
42
43
  // first time someone's product code lived under a folder called `specs`.
43
- function isNoise(relPath) {
44
- return relPath.startsWith('specs/') || relPath.startsWith('.spec-env/')
44
+ //
45
+ // `relPath` is a REPO path, and only the project's own `specs/` and `.spec-env/`
46
+ // are bookkeeping: a project in a subfolder of its repo (`prefix`) owns neither
47
+ // folder at the root, and a change beside it — `Sql/` — is code.
48
+ function isNoise(relPath, prefix = '') {
49
+ const rel = fromRepoPath(relPath, prefix)
50
+ return rel !== null && (rel.startsWith('specs/') || rel.startsWith('.spec-env/'))
45
51
  }
46
52
 
47
53
  /**
@@ -57,8 +63,10 @@ function isNoise(relPath) {
57
63
  * On a page whose SUBJECT is the spec, applying it folds away every file and
58
64
  * renders a page with nothing open on it.
59
65
  */
60
- function isSpecDocOf(relPath, folder) {
61
- const parts = String(relPath).split('/')
66
+ function isSpecDocOf(relPath, folder, prefix = '') {
67
+ const rel = fromRepoPath(String(relPath), prefix)
68
+ if (rel === null) return false
69
+ const parts = rel.split('/')
62
70
  return parts.length > 3 && parts[0] === 'specs' && parts[2] === folder
63
71
  }
64
72
 
@@ -266,7 +274,10 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
266
274
  // reads the spec's worktree, and for those the two are the same path — so
267
275
  // `treePath` left null keeps the existing behaviour exactly. The `docs` mode
268
276
  // has no worktree to read, which is the whole reason it exists.
269
- const root = treePath || spec.worktreePath
277
+ //
278
+ // `treePath` is a git ROOT, like every tree the readers are bound to — the
279
+ // spec's documents are in the project folder inside it.
280
+ const root = treePath ? projectIn(treePath, spec.prefix || '') : spec.projectPath || spec.worktreePath
270
281
 
271
282
  // AN EXPLICIT FILE SET, or every changed file. `only` is a whitelist of
272
283
  // repo-relative paths, and it exists because the `docs` mode reads a tree
@@ -280,7 +291,8 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
280
291
  // else the spec's own documents are the bookkeeping beside the code; on a
281
292
  // docs page they are the code, and the companions the project declared (a
282
293
  // tracker snapshot, say) are what belongs folded away.
283
- const noiseOf = (p) => (mode === 'docs' ? !isSpecDocOf(p, spec.folder) : isNoise(p))
294
+ const prefix = spec.prefix || ''
295
+ const noiseOf = (p) => (mode === 'docs' ? !isSpecDocOf(p, spec.folder, prefix) : isNoise(p, prefix))
284
296
 
285
297
  // THE SURFACES BLOCK, built here so the page never has to know which tiers
286
298
  // exist or which of them can be turned on. `null` when the caller passed
@@ -2579,7 +2591,9 @@ function reviewFileUrl(outPath) {
2579
2591
  const encoded = path
2580
2592
  .resolve(outPath)
2581
2593
  .split(path.sep)
2582
- .map((seg) => encodeURIComponent(seg))
2594
+ // A Windows drive (`C:`) stays as it is: encoded, `file:///C%3A/…` is a
2595
+ // link no browser opens (chore-windows-ci).
2596
+ .map((seg, i) => (i === 0 && /^[A-Za-z]:$/.test(seg) ? seg : encodeURIComponent(seg)))
2583
2597
  .join('/')
2584
2598
  return `file://${encoded.startsWith('/') ? '' : '/'}${encoded}`
2585
2599
  }
@@ -32,6 +32,7 @@ const fs = require('node:fs')
32
32
  const path = require('node:path')
33
33
  const crypto = require('node:crypto')
34
34
  const { spawn } = require('node:child_process')
35
+ const { signalGroup } = require('./supervise.js')
35
36
 
36
37
  const BUNDLED_ADAPTERS = { coderabbit: require('./reviewers/coderabbit.js') }
37
38
 
@@ -287,7 +288,9 @@ function runReviewer(entry, ctx) {
287
288
  // Through a shell, deliberately: the config holds a command LINE, with
288
289
  // pipes and quoting the project chose. It is read from a committed config
289
290
  // in the project's own repo — the same trust level as a package script.
290
- child = spawnFn('/bin/sh', ['-c', rendered], {
291
+ // `sh` from PATH on Windows — Git for Windows' — where `/bin/sh` does not
292
+ // exist and no reviewer could run at all (chore-windows-ci).
293
+ child = spawnFn(process.platform === 'win32' ? 'sh' : '/bin/sh', ['-c', rendered], {
291
294
  cwd: worktree,
292
295
  stdio: ['ignore', 'pipe', 'pipe'],
293
296
  // THE CHILD LEADS ITS OWN PROCESS GROUP, and the timeout below depends
@@ -314,15 +317,9 @@ function runReviewer(entry, ctx) {
314
317
  timedOut = true
315
318
  // The group, not the shell: `/bin/sh -c "cr review"` killed on its own
316
319
  // leaves the reviewer running and holding the port/rate-limit slot.
317
- try {
318
- process.kill(-child.pid, 'SIGKILL')
319
- } catch {
320
- try {
321
- child.kill('SIGKILL')
322
- } catch {
323
- /* already gone */
324
- }
325
- }
320
+ // `signalGroup` is the group on POSIX and the process tree on Windows,
321
+ // which has no groups (env/supervise.js).
322
+ signalGroup(child.pid, 'SIGKILL')
326
323
  }, entry.timeout * 1000)
327
324
 
328
325
  const settle = (spawnError) => {
package/src/env/serve.js CHANGED
@@ -38,6 +38,7 @@ const {
38
38
  } = require('./resolve.js')
39
39
  const { readRegistry } = require('./registry.js')
40
40
  const { loadEnvConfig } = require('./config.js')
41
+ const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
41
42
  const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
42
43
  const { liveStateFor } = require('./live.js')
43
44
  const { preferRemoteBase } = require('./host.js')
@@ -219,8 +220,11 @@ ${body}
219
220
  * file in the tree IS evidence that the tree is being used for something else,
220
221
  * and that answer must stay unchanged — see the stays-silent test.
221
222
  */
222
- function isProjectBookkeeping(p) {
223
- return String(p).startsWith('specs/.core/')
223
+ //
224
+ // `p` is a repo path; the project's `specs/.core/` is under its prefix.
225
+ function isProjectBookkeeping(p, prefix = '') {
226
+ const rel = fromRepoPath(String(p), prefix)
227
+ return rel !== null && rel.startsWith('specs/.core/')
224
228
  }
225
229
 
226
230
  function docsWorktree(wt, spec, config) {
@@ -246,18 +250,22 @@ function docsWorktree(wt, spec, config) {
246
250
  // which is what `--docs` showed from the CLI — a served page that listed a
247
251
  // file the run's own report did not would be a different page from the one
248
252
  // the reader was told about.
249
- const intruders = foreign.filter((p) => !isProjectBookkeeping(p))
253
+ const intruders = foreign.filter((p) => !isProjectBookkeeping(p, prefixOf(config)))
250
254
  if (!owned.length || intruders.length) return null
251
255
  return { owned }
252
256
  }
253
257
 
254
258
  function viewFor(dir, config, spec, git, { fallback = false } = {}) {
255
259
  if (!spec) return null
260
+ // Every tree a view names is a git ROOT, so the reader bound to it prints
261
+ // root-relative paths and takes root-relative pathspecs. `dir` is the project
262
+ // folder, which is the root unless the project sits in a subfolder.
263
+ const root = repoRootOf(dir, config)
256
264
  // LIVE COMES FIRST, because while a spec is live its worktree still exists —
257
265
  // detached — and would win the check below while holding none of the work.
258
266
  // `live take` checks the branch out HERE, and a fix made while live is made
259
267
  // here too, so this checkout is the tree that answers.
260
- if (spec.branch && headBranchOf(git) === spec.branch) return { kind: 'live', tree: dir }
268
+ if (spec.branch && headBranchOf(git) === spec.branch) return { kind: 'live', tree: root }
261
269
  const wt = spec.worktreePath
262
270
  if (wt && wt !== dir && fs.existsSync(wt)) {
263
271
  // A DOCS WORKTREE IS NOT A CODE WORKTREE, and this used to be unreachable.
@@ -287,7 +295,7 @@ function viewFor(dir, config, spec, git, { fallback = false } = {}) {
287
295
  if (docs) return { kind: 'docs', tree: wt, owned: docs.owned }
288
296
  return { kind: 'worktree', tree: wt }
289
297
  }
290
- const found = specDocsIn(dir, spec, config, trimmedGitReader(dir))
298
+ const found = specDocsIn(root, spec, config, trimmedGitReader(root))
291
299
  // `error` is cannot-tell — not a page, and not an error page either (rule 4:
292
300
  // the harmless branch).
293
301
  if (found.error) return null
@@ -310,9 +318,9 @@ function viewFor(dir, config, spec, git, { fallback = false } = {}) {
310
318
  // omits them in the first place. A direct request is someone opening an
311
319
  // address they were given, and that has to keep resolving.
312
320
  if (!fallback) return null
313
- const committed = committedDocsFor(dir, config, spec)
321
+ const committed = committedDocsFor(root, config, spec)
314
322
  if (!committed) return null
315
- return { kind: 'docs-committed', tree: dir, owned: committed }
323
+ return { kind: 'docs-committed', tree: root, owned: committed }
316
324
  }
317
325
 
318
326
  /**
@@ -322,9 +330,9 @@ function viewFor(dir, config, spec, git, { fallback = false } = {}) {
322
330
  * that is no spec at all must stay a 404 rather than render an empty page with
323
331
  * a commit button on it.
324
332
  */
325
- function committedDocsFor(dir, config, spec) {
326
- const git = trimmedGitReader(dir)
327
- const out = git(['ls-files', '--', `specs/*/${spec.folder}/*`])
333
+ function committedDocsFor(root, config, spec) {
334
+ const git = trimmedGitReader(root)
335
+ const out = git(['ls-files', '--', toRepoPath(`specs/*/${spec.folder}/*`, prefixOf(config))])
328
336
  if (out == null) return null
329
337
  const paths = String(out)
330
338
  .split('\n')
@@ -1035,6 +1043,9 @@ if (require.main === module) {
1035
1043
  }
1036
1044
  const { dir, port, host, token } = JSON.parse(fs.readFileSync(settingsFile, 'utf-8'))
1037
1045
  const { config } = loadEnvConfig(dir)
1046
+ // `dir` is the project folder the CLI anchored on; re-derive where it sits in
1047
+ // its repo so worktree paths resolve beside the repo, as the CLI's do.
1048
+ attachProject(config, primaryAnchor(dir, trimmedGitReader(dir)))
1038
1049
  const server = createReviewServer({ ...serverHooks(dir, config), token })
1039
1050
  startReviewServer(server, { port, host }).then(
1040
1051
  () => {},
@@ -12,7 +12,7 @@
12
12
 
13
13
  const fs = require('node:fs')
14
14
  const path = require('node:path')
15
- const { spawn } = require('node:child_process')
15
+ const { spawn, spawnSync } = require('node:child_process')
16
16
 
17
17
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
18
18
 
@@ -34,7 +34,18 @@ function isAlive(pid) {
34
34
  // Signal a detached process's whole group (its leader pid is `pid`, so the group
35
35
  // id is `-pid`) — reaches children like vite/tsc that a bare `pnpm dev` spawns.
36
36
  // Falls back to signalling just the leader if the group send fails.
37
- function signalGroup(pid, sig) {
37
+ //
38
+ // WINDOWS HAS NO PROCESS GROUPS: `-pid` throws, the fallback kills only the
39
+ // `sh` wrapper, and the server it started survives — holding its port and its
40
+ // worktree, which then cannot be removed (chore-windows-ci). `taskkill /T` walks
41
+ // the tree instead; `/F` for both signals, because a console process ignores
42
+ // the polite close a bare `taskkill` sends. Run with an argument list, never a
43
+ // shell. `opts` is injectable for tests.
44
+ function signalGroup(pid, sig, { platform = process.platform, run = spawnSync } = {}) {
45
+ if (platform === 'win32') {
46
+ run('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
47
+ return
48
+ }
38
49
  try {
39
50
  process.kill(-pid, sig)
40
51
  } catch {
@@ -81,6 +92,8 @@ function startProcess(proc, { cwd, rootDir, spawnImpl = spawn }) {
81
92
  cwd,
82
93
  env: { ...process.env, ...proc.env },
83
94
  detached: true,
95
+ // No console window per dev server on Windows; nothing anywhere else.
96
+ windowsHide: true,
84
97
  stdio: ['ignore', out, out],
85
98
  })
86
99
  child.unref()
@@ -23,6 +23,7 @@
23
23
 
24
24
  const { expandTokens } = require('./resolve.js')
25
25
  const { composeFileArg } = require('./provision.js')
26
+ const { shellPath } = require('./project.js')
26
27
 
27
28
  /**
28
29
  * @param {object} spec resolved spec: { slug, branch, worktreePath, projectName, ... }
@@ -131,7 +132,7 @@ function planDown(spec, config, flags, ctx) {
131
132
  commands.push(
132
133
  force
133
134
  ? `git worktree remove --force ${spec.worktreePath}`
134
- : `git worktree remove ${spec.worktreePath}`,
135
+ : `git worktree remove ${shellPath(spec.worktreePath)}`,
135
136
  )
136
137
 
137
138
  // --- delete the branch ---
@@ -282,8 +283,8 @@ function planDownCheckout(spec, config, flags, ctx) {
282
283
  }
283
284
 
284
285
  const commands = []
285
- if (onBranch !== false) commands.push(`git -C ${checkoutPath} switch ${base}`)
286
- commands.push(`git -C ${checkoutPath} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
286
+ if (onBranch !== false) commands.push(`git -C ${shellPath(checkoutPath)} switch ${base}`)
287
+ commands.push(`git -C ${shellPath(checkoutPath)} branch ${landed ? '-D' : '-d'} ${spec.branch}`)
287
288
  return { ...result, commands }
288
289
  }
289
290
 
package/src/env/trust.js CHANGED
@@ -41,8 +41,11 @@ function writeSettings(file, settings) {
41
41
  * - `added` — the root was merged into an existing file
42
42
  * - `present` — the root was already listed (no write)
43
43
  * - `malformed` — the file exists but isn't parseable JSON (left untouched)
44
+ *
45
+ * `{ dryRun: true }` answers the same question and writes nothing — `changed`
46
+ * then means "would change", which is what `spec-env up --plan` reports.
44
47
  */
45
- function ensureWorktreeDirTrusted(dir, rootAbs) {
48
+ function ensureWorktreeDirTrusted(dir, rootAbs, { dryRun = false } = {}) {
46
49
  const file = settingsPath(dir)
47
50
 
48
51
  let raw
@@ -50,7 +53,7 @@ function ensureWorktreeDirTrusted(dir, rootAbs) {
50
53
  raw = fs.readFileSync(file, 'utf-8')
51
54
  } catch (error) {
52
55
  if (error.code === 'ENOENT') {
53
- writeSettings(file, { permissions: { additionalDirectories: [rootAbs] } })
56
+ if (!dryRun) writeSettings(file, { permissions: { additionalDirectories: [rootAbs] } })
54
57
  return { changed: true, reason: 'created' }
55
58
  }
56
59
  throw error
@@ -70,6 +73,7 @@ function ensureWorktreeDirTrusted(dir, rootAbs) {
70
73
  : []
71
74
 
72
75
  if (dirs.includes(rootAbs)) return { changed: false, reason: 'present' }
76
+ if (dryRun) return { changed: true, reason: 'added' }
73
77
 
74
78
  writeSettings(file, {
75
79
  ...parsed,
package/src/init.js CHANGED
@@ -3,10 +3,12 @@
3
3
  const fs = require('fs')
4
4
  const path = require('path')
5
5
  const crypto = require('crypto')
6
+ const { execFileSync } = require('child_process')
6
7
 
7
8
  const { ensureWorktreeDirTrusted } = require('./env/trust.js')
8
9
  const { ensureHooks } = require('./env/hooks.js')
9
10
  const { repoInfo, expandTokens } = require('./env/resolve.js')
11
+ const { primaryAnchor } = require('./env/project.js')
10
12
 
11
13
  const ASSETS = path.join(__dirname, '..', 'assets')
12
14
 
@@ -286,8 +288,11 @@ const RETIRED_FILES = [
286
288
  path.join('specs', 'complete', '00-index.md'),
287
289
  ]
288
290
 
291
+ // `/`-separated on every platform: these are the manifest's keys and the
292
+ // report's lines, and a Windows install recording `specs\\.core\\…` would read
293
+ // as a different file to every other machine (chore-windows-ci).
289
294
  function rel(dir, p) {
290
- return path.relative(dir, p) || '.'
295
+ return path.relative(dir, p).split(path.sep).join('/') || '.'
291
296
  }
292
297
 
293
298
  function ensureDir(p) {
@@ -310,8 +315,22 @@ const MANIFEST_VERSION = 1
310
315
  // reset each init() alongside `report`.
311
316
  const writtenHashes = {}
312
317
 
318
+ // Every judgement about a managed file compares content with its line endings
319
+ // normalised. On Windows with `core.autocrlf=true` a checkout rewrites LF to
320
+ // CRLF, and an exact compare read that conversion as the user's edit: every
321
+ // skill, command and rule became "your edit — kept" and stopped updating.
322
+ // Assets ship LF, so hashes of LF files — every manifest already written — are
323
+ // unchanged by this.
324
+ function normalizeEol(content) {
325
+ return content.replace(/\r\n/g, '\n')
326
+ }
327
+
328
+ function sameContent(a, b) {
329
+ return normalizeEol(a) === normalizeEol(b)
330
+ }
331
+
313
332
  function sha1(content) {
314
- return crypto.createHash('sha1').update(content).digest('hex')
333
+ return crypto.createHash('sha1').update(normalizeEol(content)).digest('hex')
315
334
  }
316
335
 
317
336
  // The full managed set for a target dir: repo-relative path, absolute path, and
@@ -349,10 +368,18 @@ function readManifest(dir) {
349
368
  try {
350
369
  const parsed = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST_FILE), 'utf8'))
351
370
  if (parsed && typeof parsed === 'object' && parsed.files && typeof parsed.files === 'object') {
371
+ // KEYS ARE `/`-SEPARATED ON READ, whoever wrote them. A Windows install
372
+ // before chore-windows-ci recorded `.claude\\skills\\…`; looked up by the
373
+ // `/` paths every caller now uses, its records went missing — and a
374
+ // missing record is what turns a user's edited retired file into one
375
+ // that gets deleted. No managed path contains a backslash, so this
376
+ // cannot merge two genuine entries.
377
+ const files = {}
378
+ for (const [key, hash] of Object.entries(parsed.files)) files[key.replace(/\\/g, '/')] = hash
352
379
  return {
353
380
  version: parsed.version || MANIFEST_VERSION,
354
- files: parsed.files,
355
- baselined: Object.keys(parsed.files).length > 0,
381
+ files,
382
+ baselined: Object.keys(files).length > 0,
356
383
  }
357
384
  }
358
385
  } catch {
@@ -406,10 +433,13 @@ function writeManifest(dir, files) {
406
433
  // `pruneRetiredManaged` passes no `bundled` on purpose: the package no longer
407
434
  // ships that file, so there is nothing to compare it against.
408
435
  function managedState(dir, relPath, manifest, bundled) {
436
+ // Manifest keys are `/`-separated; a caller holding an OS path still finds
437
+ // its file's record (chore-windows-ci).
438
+ relPath = String(relPath).split(path.sep).join('/')
409
439
  const abs = path.join(dir, relPath)
410
440
  if (!fs.existsSync(abs)) return 'missing'
411
441
  const onDisk = fs.readFileSync(abs, 'utf8')
412
- if (bundled !== undefined && onDisk === bundled) return 'pristine'
442
+ if (bundled !== undefined && sameContent(onDisk, bundled)) return 'pristine'
413
443
  const known = manifest.files[relPath]
414
444
  if (known) return sha1(onDisk) === known ? 'pristine' : 'customized'
415
445
  return manifest.baselined ? 'adopted' : 'customized'
@@ -715,8 +745,18 @@ function trustWorktreeRoot(dir) {
715
745
  report.warnings.push('could not read worktree.root — skipped trusting the worktree dir')
716
746
  return
717
747
  }
718
- const { repo, repoSlug } = repoInfo(dir)
719
- const rootAbs = path.resolve(dir, expandTokens(root, { repo, repoSlug }))
748
+ // Resolved against the REPO's root, and named for it, exactly as `spec-env`
749
+ // resolves it — `dir` is the project folder, which is a subfolder of the repo
750
+ // for some projects (feat-subfolder-project). Not a repo → `dir`, as before.
751
+ const anchor = primaryAnchor(dir, (args) => {
752
+ try {
753
+ return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
754
+ } catch {
755
+ return null
756
+ }
757
+ })
758
+ const { repo, repoSlug } = repoInfo(anchor.root)
759
+ const rootAbs = path.resolve(anchor.root, expandTokens(root, { repo, repoSlug }))
720
760
  const res = ensureWorktreeDirTrusted(dir, rootAbs)
721
761
  const label = '.claude/settings.local.json (trusted worktree root)'
722
762
  if (res.reason === 'malformed') {
@@ -777,7 +817,7 @@ function checkSync(dir, { claudeMd = true, log = console.log } = {}) {
777
817
  else if (state === 'customized') rows.push([relPath, 'your edit — kept (--force overwrites)'])
778
818
  else if (state === 'adopted')
779
819
  rows.push([relPath, 'adopted upstream — yours kept, theirs not installed (--force takes theirs)'])
780
- else if (fs.readFileSync(abs, 'utf8') !== bundled) rows.push([relPath, 'out of date — would be updated'])
820
+ else if (!sameContent(fs.readFileSync(abs, 'utf8'), bundled)) rows.push([relPath, 'out of date — would be updated'])
781
821
  }
782
822
  const section = claudeMd ? claudeMdSectionState(dir) : 'fresh'
783
823
  // A healthy area says NOTHING. A report that lists what is already fine is a
@@ -876,7 +916,7 @@ function resyncManagedFile(dir, target, manifest, force) {
876
916
  return report[state].push({ relPath, added, removed, hunks })
877
917
  }
878
918
  // pristine — update only if the bundled content actually changed
879
- if (fs.readFileSync(abs, 'utf8') === bundled) {
919
+ if (sameContent(fs.readFileSync(abs, 'utf8'), bundled)) {
880
920
  // The file is ours and current, but the manifest disagreed — record the
881
921
  // repair rather than healing in silence: a file that quietly starts
882
922
  // updating again is as opaque as one that quietly stopped.
@@ -36,7 +36,9 @@ function collectMarkdown(target) {
36
36
  // Skip VCS/deps, and `.core` — skitterspec's own manifest-managed docs.
37
37
  // Reflowing a managed file makes the next `update` see it as customized and
38
38
  // freeze the shipped version, silently pinning stale docs.
39
- if (/(^|\/)(node_modules|\.git|\.core)$/.test(p)) return
39
+ // Either separator: on Windows `p` is `specs\\.core`, and a `/`-only test
40
+ // walked straight into the managed docs it exists to protect.
41
+ if (/(^|[\\/])(node_modules|\.git|\.core)$/.test(p)) return
40
42
  for (const name of fs.readdirSync(p).sort()) walk(path.join(p, name))
41
43
  } else if (st.isFile() && p.endsWith('.md')) {
42
44
  out.push(p)
@@ -95,10 +97,13 @@ async function specSanitise(argv, { cwd = process.cwd(), out = process.stdout }
95
97
 
96
98
  const excludeRes = opts.exclude.map(globToRe)
97
99
  const excluded = (rel) => excludeRes.some((re) => re.test(rel))
100
+ // Repo paths are `/`-separated everywhere — what `--exclude` globs are
101
+ // written against, and what the report prints.
102
+ const relOf = (f) => path.relative(cwd, f).split(path.sep).join('/')
98
103
  const files = new Set()
99
104
  for (const p of opts.paths) {
100
105
  for (const f of collectMarkdown(path.resolve(cwd, p))) {
101
- if (!excluded(path.relative(cwd, f))) files.add(f)
106
+ if (!excluded(relOf(f))) files.add(f)
102
107
  }
103
108
  }
104
109
 
@@ -108,7 +113,7 @@ async function specSanitise(argv, { cwd = process.cwd(), out = process.stdout }
108
113
  for (const file of [...files].sort()) {
109
114
  const src = fs.readFileSync(file, 'utf-8')
110
115
  const res = sanitizeSpecMarkdown(src, opts.width ? { width: opts.width } : {})
111
- const rel = path.relative(cwd, file)
116
+ const rel = relOf(file)
112
117
  if (res.refused) {
113
118
  refusedFiles++
114
119
  out.write(`skipped ${rel} (would alter structure — left untouched)\n`)
@@ -25,7 +25,7 @@ const path = require('node:path')
25
25
 
26
26
  const { BUCKETS, findSpecFolder, branchFor, splitPrefix, currentBranch } = require('../../env/resolve.js')
27
27
  const { loadEnvConfig } = require('../../env/config.js')
28
- const { ticketsInRange, nameTickets, refuseRemovedVerb } = require('./released.js')
28
+ const { ticketsInRange, nameTickets, refuseRemovedVerb, projectPrefixOf } = require('./released.js')
29
29
  const { retiredKeysRow } = require('../provider-kit/src/config.js')
30
30
  const { doctorRow } = require('../provider-kit/src/doctor.js')
31
31
  const { execFileSync } = require('node:child_process')
@@ -437,7 +437,7 @@ function specSyncRecord(dir, config, specArg, out) {
437
437
  if (!snapshotDir) return 1
438
438
  const identifier = specIdentifier(snapshotDir, config)
439
439
  const file = recordPush({ dir, snapshotDir, identifier, config })
440
- out.write(`spec-sync record: snapshot written → ${path.relative(dir, file)}\n`)
440
+ out.write(`spec-sync record: snapshot written → ${path.relative(dir, file).split(path.sep).join('/')}\n`)
441
441
  }
442
442
 
443
443
  // `spec-sync status <spec> [--remote file] [--workspace-states file]` — read-only
@@ -1085,7 +1085,11 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
1085
1085
  }
1086
1086
  const { range, commits } = read
1087
1087
 
1088
- const report = ticketsInRange(commits, { ignorePaths: releaseIgnorePaths(config) })
1088
+ const report = ticketsInRange(commits, {
1089
+ ignorePaths: releaseIgnorePaths(config),
1090
+ // A nested project's commits carry its folder in every path (feat-subfolder-project).
1091
+ prefix: projectPrefixOf(dir),
1092
+ })
1089
1093
  report.tickets = nameTickets(report.tickets, listSpecs(dir, config, { urls: true }))
1090
1094
 
1091
1095
  // Titles are an ENRICHMENT: the scan itself is offline. No key, the MCP
@@ -2651,7 +2655,8 @@ function labelList(value) {
2651
2655
  */
2652
2656
  function specSyncInitConfig(dir, flags, out) {
2653
2657
  const file = path.join(dir, CONFIG_FILE)
2654
- const rel = CONFIG_FILE
2658
+ // Printed, so `/`-separated on every platform.
2659
+ const rel = CONFIG_FILE.split(path.sep).join('/')
2655
2660
  const existed = fs.existsSync(file)
2656
2661
  const fail = (lines, extra = {}) => {
2657
2662
  if (flags.json) {
@@ -83,6 +83,9 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
83
83
  const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
84
84
  const lines = []
85
85
  const result = { issue: null, subIssues: {} }
86
+ // Which items this apply carried a state for — the snapshot records today's
87
+ // state name for these and only these (`recordPush`).
88
+ const sent = { issue: !!(plan.issue && plan.issue.state != null), subIssues: new Set() }
86
89
  // Handed out immediately, so a throw from anywhere below still reports what
87
90
  // had been stamped by the time it happened.
88
91
  if (progress) progress.result = result
@@ -167,6 +170,7 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
167
170
  const file = resolvePhaseFileIn(snapshotDir, sub.ref)
168
171
  if (!file) throw new Error(`no phase file for ref ${sub.ref}`)
169
172
  stampSubIssueId(snapshotDir, file, created.identifier, config)
173
+ if (sub.state != null) sent.subIssues.add(String(created.identifier))
170
174
  result.subIssues[sub.ref] = created.identifier
171
175
  lines.push(` sub-issue created: ${sub.ref} → ${created.identifier}`)
172
176
  }
@@ -193,6 +197,7 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
193
197
  sub = spliced(sub, 'goal', before, config, sub.id, lines)
194
198
  }
195
199
  await ops.updateSubIssue(sub)
200
+ if (sub.state != null) sent.subIssues.add(String(sub.id))
196
201
  result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
197
202
  lines.push(` sub-issue updated: ${sub.id}`)
198
203
  }
@@ -212,8 +217,10 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
212
217
  const lost = verify.some((l) => l.includes('!!') || l.includes('??'))
213
218
 
214
219
  // 7. Record the snapshot from the now-stamped files, so the next push is empty.
215
- const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config })
216
- lines.push(` snapshot: ${path.relative(dir, file)}`)
220
+ const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent })
221
+ // A repo path, `/`-separated on every platform — the form every other
222
+ // spec path in this output takes.
223
+ lines.push(` snapshot: ${path.relative(dir, file).split(path.sep).join('/')}`)
217
224
  return { result, lines, lost }
218
225
  }
219
226
 
@@ -63,7 +63,7 @@ function storePath(env = process.env, homedir = os.homedir) {
63
63
  * `absent` (no file — the normal default, not a problem), `permissions`
64
64
  * (group/world readable), `unreadable`, `malformed`.
65
65
  */
66
- function readStore(file, { stat = fs.statSync, read = fs.readFileSync } = {}) {
66
+ function readStore(file, { stat = fs.statSync, read = fs.readFileSync, platform = process.platform } = {}) {
67
67
  let info
68
68
  try {
69
69
  info = stat(file)
@@ -74,7 +74,12 @@ function readStore(file, { stat = fs.statSync, read = fs.readFileSync } = {}) {
74
74
  return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
75
75
  }
76
76
 
77
- if (info.mode & GROUP_OR_WORLD) {
77
+ // ON WINDOWS THE MODE BITS SAY NOTHING. Node reports every file there as
78
+ // 0o666, so this check refused every store on Windows and no stored
79
+ // credential could ever be read (chore-windows-ci). Access there is the
80
+ // profile directory's ACL, which these bits do not describe — cannot tell,
81
+ // and cannot-tell does not accuse (`.claude/rules/negative-checks.md`).
82
+ if (platform !== 'win32' && info.mode & GROUP_OR_WORLD) {
78
83
  const mode = (info.mode & 0o777).toString(8)
79
84
  return {
80
85
  ok: false,
@@ -1,5 +1,25 @@
1
1
  'use strict'
2
2
 
3
+ const { execFileSync } = require('node:child_process')
4
+ const { primaryAnchor, fromRepoPath } = require('../../../env/project.js')
5
+
6
+ /**
7
+ * The project's prefix within its repo, read from `dir` — `''` at the root, and
8
+ * `''` whenever git cannot answer (today's behaviour). What `ticketsInRange`
9
+ * needs to read a commit's root-relative paths against the project's
10
+ * `ignorePaths`.
11
+ */
12
+ function projectPrefixOf(dir) {
13
+ const git = (args) => {
14
+ try {
15
+ return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
16
+ } catch {
17
+ return null
18
+ }
19
+ }
20
+ return primaryAnchor(dir, git).prefix
21
+ }
22
+
3
23
  /**
4
24
  * Which tickets a release contains.
5
25
  *
@@ -99,7 +119,14 @@ function asGlobal(pattern) {
99
119
  * @param {string[]|null|undefined} paths repo-relative paths the commit changed
100
120
  * @param {string[]} ignorePaths repo-relative prefixes that are bookkeeping
101
121
  */
102
- function onlyIgnoredPaths(paths, ignorePaths) {
122
+ //
123
+ // `paths` are what `git log --name-only` prints — from the REPO ROOT — while
124
+ // `ignorePaths` are the project's, like every path in its config. For a project
125
+ // in a subfolder of its repo (`prefix`, spec feat-subfolder-project) each path
126
+ // is made project-relative first, and a path OUTSIDE the project is never
127
+ // bookkeeping: a commit that touched `Sql/` did real work. Prefix '' compares
128
+ // exactly as before.
129
+ function onlyIgnoredPaths(paths, ignorePaths, prefix = '') {
103
130
  if (!Array.isArray(paths) || !paths.length) return false
104
131
  const prefixes = (Array.isArray(ignorePaths) ? ignorePaths : [])
105
132
  .filter((p) => typeof p === 'string' && p.trim())
@@ -113,7 +140,9 @@ function onlyIgnoredPaths(paths, ignorePaths) {
113
140
  // An unreadable entry is an unknown, not an ignored one — it makes the whole
114
141
  // commit count, per the bias above.
115
142
  if (!file) return false
116
- return prefixes.some((prefix) => file === prefix || file.startsWith(`${prefix}/`))
143
+ const rel = fromRepoPath(file, prefix)
144
+ if (rel === null) return false
145
+ return prefixes.some((p) => rel === p || rel.startsWith(`${p}/`))
117
146
  })
118
147
  }
119
148
 
@@ -140,6 +169,7 @@ function onlyIgnoredPaths(paths, ignorePaths) {
140
169
  */
141
170
  function ticketsInRange(commits, options = {}) {
142
171
  const ignorePaths = (options && options.ignorePaths) || []
172
+ const prefix = (options && options.prefix) || ''
143
173
  const refPattern = options && options.refPattern
144
174
  const foreign = ((options && options.foreignPatterns) || []).map(asGlobal).filter(Boolean)
145
175
  const seen = new Map()
@@ -150,7 +180,7 @@ function ticketsInRange(commits, options = {}) {
150
180
  let sawMergeFlag = false
151
181
  for (const commit of commits || []) {
152
182
  if (commit && commit.isMerge !== undefined) sawMergeFlag = true
153
- if (onlyIgnoredPaths(commit && commit.paths, ignorePaths)) {
183
+ if (onlyIgnoredPaths(commit && commit.paths, ignorePaths, prefix)) {
154
184
  // Not counted as unreferenced either: that number exists to surface a
155
185
  // MISSED trailer, and a paperwork commit is not a gap someone should hunt.
156
186
  ignored++
@@ -222,6 +252,7 @@ function refuseRemovedVerb(out, program, verb) {
222
252
  }
223
253
 
224
254
  module.exports = {
255
+ projectPrefixOf,
225
256
  ticketsInRange,
226
257
  refuseRemovedVerb,
227
258
  nameTickets,