@skitterbyte/skitterspec-jira 2.4.0 → 2.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/hotfix.js CHANGED
@@ -22,6 +22,7 @@
22
22
 
23
23
  const path = require('node:path')
24
24
  const { afterLandFor, rangeOf } = require('./integrate.js')
25
+ const { shellPath } = require('./project.js')
25
26
 
26
27
  /**
27
28
  * Parse a semver-ish tag and return it with its PATCH bumped by one. Preserves any
@@ -227,15 +228,17 @@ function planHotfixLand(spec, config, ctx) {
227
228
  // The tag is the command's to choose and is unknown until it has run, so
228
229
  // there is nothing to check a collision against here — the command refuses
229
230
  // a tag that exists, and the runner refuses one a target also planned.
230
- commands.push(`(cd ${spec.worktreePath} && ${releaseWith})`)
231
- steps.push({ kind: 'release', via: 'command', command: releaseWith, cwd: spec.worktreePath })
231
+ // The release command is the project's, so it runs in the project folder.
232
+ const releaseCwd = spec.projectPath || spec.worktreePath
233
+ commands.push(`(cd ${shellPath(releaseCwd)} && ${releaseWith})`)
234
+ steps.push({ kind: 'release', via: 'command', command: releaseWith, cwd: releaseCwd })
232
235
  } else {
233
236
  prodTag = nextTag(baseRef, c.existingTags, bump)
234
237
  if (taken.has(prodTag)) {
235
238
  return block(`tag ${prodTag} already exists${freeTagHint(baseRef, c.existingTags, bump)}`)
236
239
  }
237
240
  taken.add(prodTag)
238
- commands.push(`git -C ${spec.worktreePath} tag ${prodTag}`)
241
+ commands.push(`git -C ${shellPath(spec.worktreePath)} tag ${prodTag}`)
239
242
  steps.push({
240
243
  kind: 'release',
241
244
  via: 'tag',
@@ -281,10 +284,10 @@ function planHotfixLand(spec, config, ctx) {
281
284
  const tmpBranch = `hotfix/${slug}`
282
285
  const tmpPath = path.join(wtRoot, slug)
283
286
  commands.push(
284
- `git worktree add ${tmpPath} -b ${tmpBranch} ${t}`,
285
- `git -C ${tmpPath} cherry-pick ${fixPick.join(' ')}`,
286
- `git -C ${tmpPath} tag ${tag}`,
287
- `git worktree remove ${tmpPath}`,
287
+ `git worktree add ${shellPath(tmpPath)} -b ${tmpBranch} ${t}`,
288
+ `git -C ${shellPath(tmpPath)} cherry-pick ${fixPick.join(' ')}`,
289
+ `git -C ${shellPath(tmpPath)} tag ${tag}`,
290
+ `git worktree remove ${shellPath(tmpPath)}`,
288
291
  `git branch -D ${tmpBranch}`,
289
292
  )
290
293
  const root = c.mainRepoPath
@@ -320,8 +323,8 @@ function planHotfixLand(spec, config, ctx) {
320
323
  const picks = carry.commits || [fixRange]
321
324
  commands.push(
322
325
  carry.strategy === 'worktree'
323
- ? `git worktree add ${carry.tmpPath} ${c.base} && git -C ${carry.tmpPath} cherry-pick ${picks.join(' ')}`
324
- : `git -C ${carry.path} cherry-pick ${picks.join(' ')}`,
326
+ ? `git worktree add ${shellPath(carry.tmpPath)} ${c.base} && git -C ${shellPath(carry.tmpPath)} cherry-pick ${picks.join(' ')}`
327
+ : `git -C ${shellPath(carry.path)} cherry-pick ${picks.join(' ')}`,
325
328
  )
326
329
  steps.push({
327
330
  kind: 'carry',
@@ -21,6 +21,7 @@
21
21
  */
22
22
 
23
23
  const { spawnSync } = require('node:child_process')
24
+ const { shellPath } = require('./project.js')
24
25
 
25
26
  // The fields skittership's `release-hotfix.cjs --json` prints, and their types.
26
27
  // `versionCommit` is null only on its `--dry-run`, which skitterspec never
@@ -219,7 +220,7 @@ function runCarry(step, release, ctx) {
219
220
  outcome: 'refused',
220
221
  line:
221
222
  `carry: ${step.cwd} has uncommitted changes on ${step.base} — commit or stash them, ` +
222
- `then run: git -C ${step.cwd} cherry-pick ${commits.join(' ')}`,
223
+ `then run: git -C ${shellPath(step.cwd)} cherry-pick ${commits.join(' ')}`,
223
224
  }
224
225
  }
225
226
  const git = (argv) =>
@@ -22,19 +22,22 @@ const { progressText } = require('./phases.js')
22
22
  /**
23
23
  * @param {object} a
24
24
  * - `dir` the checkout the command was run from
25
- * - `provisioned` `[{ folder, wt, specless }]`, from the worktree list
25
+ * - `provisioned` `[{ folder, wt, project, specless }]`, from the worktree
26
+ * list — `project` is the project folder inside `wt`, the
27
+ * same path unless the project sits in a subfolder
26
28
  * - `read` `readSpecState`, injectable
27
29
  */
28
30
  function collectInFlight({ dir, provisioned, read = readSpecState }) {
29
- return provisioned.map(({ folder, wt, specless }) => {
31
+ return provisioned.map(({ folder, wt, project, specless }) => {
32
+ const at = project || wt
30
33
  // A `/no-spec` record has a branch and no document BY DESIGN (Decision 6).
31
34
  // It is listed, and never read, so it can never be called unknown.
32
- if (specless) return { spec: folder, worktree: wt, specless: true }
33
- const there = read(wt, folder)
35
+ if (specless) return { spec: folder, worktree: at, specless: true }
36
+ const there = read(at, folder)
34
37
  const here = read(dir, folder)
35
38
  return {
36
39
  spec: folder,
37
- worktree: wt,
40
+ worktree: at,
38
41
  specless: false,
39
42
  ...there,
40
43
  // Where this checkout files it: a bucket, or null when it is not on this
@@ -1,6 +1,7 @@
1
1
  'use strict'
2
2
 
3
3
  const { globToRegExp } = require('./glob.js')
4
+ const { shellPath } = require('./project.js')
4
5
 
5
6
  /**
6
7
  * Pure integrate planner for `spec-env integrate`.
@@ -69,8 +70,8 @@ function planIntegrate(spec, config, ctx) {
69
70
  ...result,
70
71
  commands: [
71
72
  ...(primarySwitch ? [switchCommand(mainRepoPath, base, primarySwitch)] : []),
72
- `git -C ${spec.worktreePath} rebase ${base}`,
73
- `git -C ${mainRepoPath} merge --ff-only ${branch}`,
73
+ `git -C ${shellPath(spec.worktreePath)} rebase ${base}`,
74
+ `git -C ${shellPath(mainRepoPath)} merge --ff-only ${branch}`,
74
75
  ],
75
76
  afterLand: afterLandFor(config, mainRepoPath, rangeOf(ctx)),
76
77
  }
@@ -80,8 +81,8 @@ function planIntegrate(spec, config, ctx) {
80
81
  // when this clone has never had it (a release candidate cut since).
81
82
  function switchCommand(repo, base, { create, remote }) {
82
83
  return create
83
- ? `git -C ${repo} switch -c ${base} --track ${remote || 'origin'}/${base}`
84
- : `git -C ${repo} switch ${base}`
84
+ ? `git -C ${shellPath(repo)} switch -c ${base} --track ${remote || 'origin'}/${base}`
85
+ : `git -C ${shellPath(repo)} switch ${base}`
85
86
  }
86
87
 
87
88
  /**
@@ -134,9 +135,9 @@ function planIntegrateCheckout(spec, config, ctx) {
134
135
  return {
135
136
  ...result,
136
137
  commands: [
137
- `git -C ${checkoutPath} rebase ${base}`,
138
- `git -C ${checkoutPath} switch ${base}`,
139
- `git -C ${checkoutPath} merge --ff-only ${branch}`,
138
+ `git -C ${shellPath(checkoutPath)} rebase ${base}`,
139
+ `git -C ${shellPath(checkoutPath)} switch ${base}`,
140
+ `git -C ${shellPath(checkoutPath)} merge --ff-only ${branch}`,
140
141
  ],
141
142
  afterLand: afterLandFor(config, checkoutPath, rangeOf(ctx)),
142
143
  }
@@ -196,8 +197,8 @@ function planIntegratePr(spec, config, ctx) {
196
197
  const finish = {
197
198
  commands: ctx.primaryPath
198
199
  ? [
199
- `git -C ${ctx.primaryPath} fetch ${remote} ${base}`,
200
- `git -C ${ctx.primaryPath} merge --ff-only ${remote}/${base}`,
200
+ `git -C ${shellPath(ctx.primaryPath)} fetch ${remote} ${base}`,
201
+ `git -C ${shellPath(ctx.primaryPath)} merge --ff-only ${remote}/${base}`,
201
202
  ]
202
203
  : [],
203
204
  afterLand: afterLandFor(config, ctx.primaryPath || null, rangeOf(ctx)),
@@ -212,12 +213,12 @@ function planIntegratePr(spec, config, ctx) {
212
213
  }
213
214
 
214
215
  const commands = [
215
- `git -C ${treePath} fetch ${remote} ${base}`,
216
- `git -C ${treePath} rebase ${remote}/${base}`,
216
+ `git -C ${shellPath(treePath)} fetch ${remote} ${base}`,
217
+ `git -C ${shellPath(treePath)} rebase ${remote}/${base}`,
217
218
  ]
218
219
  // --force-with-lease because the rebase rewrites; -u so the first push sets
219
220
  // the upstream the unpushed guard reads.
220
- const pushCommand = `git -C ${treePath} push --force-with-lease -u ${remote} ${branch}`
221
+ const pushCommand = `git -C ${shellPath(treePath)} push --force-with-lease -u ${remote} ${branch}`
221
222
  // Composed by the host adapter where one exists; until the caller supplies
222
223
  // one, a comment line that cannot be run by accident.
223
224
  const prCommand = (ctx && ctx.prCreateCommand)
package/src/env/live.js CHANGED
@@ -19,6 +19,7 @@
19
19
  const fs = require('node:fs')
20
20
  const path = require('node:path')
21
21
  const { globToRegExp } = require('./glob.js')
22
+ const { shellPath } = require('./project.js')
22
23
 
23
24
  const REQUIRED = ['spec', 'branch', 'holder', 'heldSince', 'baseMainCommit']
24
25
 
@@ -341,9 +342,9 @@ function planTake(spec, config, ctx) {
341
342
  return {
342
343
  ...result,
343
344
  commands: [
344
- `git -C ${spec.worktreePath} rebase ${base}`,
345
- `git -C ${spec.worktreePath} switch --detach`,
346
- `git -C ${c.primaryPath} checkout ${branch}`,
345
+ `git -C ${shellPath(spec.worktreePath)} rebase ${base}`,
346
+ `git -C ${shellPath(spec.worktreePath)} switch --detach`,
347
+ `git -C ${shellPath(c.primaryPath)} checkout ${branch}`,
347
348
  ],
348
349
  warnings,
349
350
  receipt: {
@@ -405,8 +406,8 @@ function planRelease(spec, config, ctx) {
405
406
  }
406
407
  }
407
408
 
408
- const commands = [`git -C ${c.primaryPath} checkout ${base}`]
409
- if (c.worktreeExists) commands.push(`git -C ${spec.worktreePath} switch ${branch}`)
409
+ const commands = [`git -C ${shellPath(c.primaryPath)} checkout ${base}`]
410
+ if (c.worktreeExists) commands.push(`git -C ${shellPath(spec.worktreePath)} switch ${branch}`)
410
411
  return { ...result, commands, clears: true }
411
412
  }
412
413
 
@@ -457,8 +458,8 @@ function planAbort(config, ctx) {
457
458
 
458
459
  const branch = c.receipt.branch
459
460
  const commands = []
460
- if (!(c.primary && c.primary.onBase)) commands.push(`git -C ${c.primaryPath} checkout ${base}`)
461
- if (c.worktreeExists) commands.push(`git -C ${c.worktreePath} switch ${branch}`)
461
+ if (!(c.primary && c.primary.onBase)) commands.push(`git -C ${shellPath(c.primaryPath)} checkout ${base}`)
462
+ if (c.worktreeExists) commands.push(`git -C ${shellPath(c.worktreePath)} switch ${branch}`)
462
463
  return { ...result, commands, clears: true, branch }
463
464
  }
464
465
 
@@ -33,7 +33,8 @@
33
33
  const fs = require('node:fs')
34
34
  const path = require('node:path')
35
35
 
36
- const { assertPrimaryOnMain, resolvePrimaryCheckout } = require('./resolve.js')
36
+ const { assertPrimaryOnMain } = require('./resolve.js')
37
+ const { primaryAnchor } = require('./project.js')
37
38
 
38
39
  // Where the allow lives. Gitignored, machine-local and beside the registry —
39
40
  // this is one person's decision about one session, never the project's policy.
@@ -169,7 +170,7 @@ function checkoutOf(target, gitAt) {
169
170
  // the same directory. Cannot-tell is "not the same", the branch that allows.
170
171
  function sameDir(a, b) {
171
172
  try {
172
- return fs.realpathSync(a) === fs.realpathSync(b)
173
+ return fs.realpathSync.native(a) === fs.realpathSync.native(b)
173
174
  } catch {
174
175
  return false
175
176
  }
@@ -218,12 +219,20 @@ function checkMainWrite(dir, config, git, opts = {}) {
218
219
  // the primary checkout's own, wherever the session is standing.
219
220
  let branchGit = git
220
221
  try {
221
- primary = resolvePrimaryCheckout(dir, git)
222
+ // `primary` is the PROJECT folder in the primary checkout — where the allow
223
+ // file lives. The question "is this write in the primary checkout?" is
224
+ // asked of its ROOT: `--show-toplevel` answers with the root, and a project
225
+ // in a subfolder of its repo compared the two, never matched, and let every
226
+ // write through. The whole primary checkout is guarded, not only the
227
+ // project folder: a write to `Sql/` on the base branch is unreviewed work
228
+ // too (feat-subfolder-project, decision 6).
229
+ const anchor = primaryAnchor(dir, git)
230
+ primary = anchor.dir
222
231
  if (opts.target && typeof opts.gitAt === 'function') {
223
232
  const top = checkoutOf(opts.target, opts.gitAt)
224
- isPrimary = Boolean(top) && Boolean(primary) && sameDir(top, primary)
233
+ isPrimary = Boolean(top) && Boolean(anchor.root) && sameDir(top, anchor.root)
225
234
  if (!isPrimary) return ALLOWS
226
- branchGit = opts.gitAt(primary)
235
+ branchGit = opts.gitAt(anchor.root)
227
236
  } else {
228
237
  isPrimary = Boolean(primary) && path.resolve(primary) === path.resolve(dir)
229
238
  }
@@ -0,0 +1,223 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Where the skitterspec project sits inside its git repo.
5
+ *
6
+ * Most projects ARE the repo: `specs/` and `.claude/` live at the git root and
7
+ * the prefix is `''`. Some live in a subfolder — a .NET solution folder beside
8
+ * `Sql/` and a prototype or two, where sessions start in the solution folder and
9
+ * that is where `specs/` has to be. This module is the one place that knows the
10
+ * difference, so every other site asks it rather than assuming `specs/` is at
11
+ * the root.
12
+ *
13
+ * Two kinds of path, kept apart on purpose:
14
+ *
15
+ * - a **repo path** is what git prints: relative to the git root, `/`-separated
16
+ * on every platform (git emits forward slashes on Windows too).
17
+ * - an **OS path** is what `fs` and `spawn` take, built with `path`.
18
+ *
19
+ * `fromRepoPath` / `toRepoPath` convert between a repo path and a
20
+ * project-relative one; `projectIn` turns a checkout root into the project's OS
21
+ * folder within it.
22
+ */
23
+
24
+ const fs = require('node:fs')
25
+ const path = require('node:path')
26
+
27
+ // What marks a project folder: the config folder the installer always writes
28
+ // into. A positive signal (`.claude/rules/negative-checks.md` rule 1) — not
29
+ // "the lifecycle folders are there", which git drops whenever one empties.
30
+ const MARKER = path.join('specs', '.core')
31
+
32
+ function isDir(p) {
33
+ try {
34
+ return fs.statSync(p).isDirectory()
35
+ } catch {
36
+ return false
37
+ }
38
+ }
39
+
40
+ // `.native`, never the JS `realpathSync`: on Windows only the native call
41
+ // expands an 8.3 short name (`C:\Users\RUNNER~1\…`), and git always reports the
42
+ // long one. Compared un-expanded, every folder under a short-named temp dir
43
+ // looked outside its own repo, and the project was never found.
44
+ function real(p) {
45
+ try {
46
+ return fs.realpathSync.native(p)
47
+ } catch {
48
+ return path.resolve(p)
49
+ }
50
+ }
51
+
52
+ /** An OS-relative path as a repo path: `/`-separated, no leading `./`. */
53
+ function toPosix(p) {
54
+ return String(p).split(path.sep).join('/').replace(/^\.\/?/, '')
55
+ }
56
+
57
+ /**
58
+ * The project's prefix within `toplevel`, found by walking up from `from` to the
59
+ * nearest folder holding `specs/.core/`, stopping at `toplevel`. `''` when the
60
+ * project is the root, and `''` when nothing is found — today's behaviour.
61
+ *
62
+ * WHAT WOULD FOOL THIS: a `specs/.core/` that is not a project's — a fixture
63
+ * folder checked into the repo, say — between `from` and the real project. The
64
+ * walk takes the nearest, so a command run from inside such a folder anchors
65
+ * there. Several projects in one repo are out of scope, and nothing here
66
+ * arbitrates between two. Run from the root's own subfolders (the ordinary
67
+ * case for a root-layout repo) the walk reaches the root and answers `''`.
68
+ *
69
+ * Paths are compared as REAL paths: git reports the toplevel resolved through
70
+ * symlinks (macOS `/var` → `/private/var`) where a caller's cwd may not be.
71
+ */
72
+ function findPrefix(from, toplevel) {
73
+ const top = real(toplevel)
74
+ let at = real(from)
75
+ const rel = path.relative(top, at)
76
+ // `from` outside the toplevel is cannot-tell, and cannot-tell is `''`.
77
+ if (rel.startsWith('..') || path.isAbsolute(rel)) return ''
78
+ for (;;) {
79
+ if (isDir(path.join(at, MARKER))) return toPosix(path.relative(top, at))
80
+ if (at === top) return ''
81
+ const up = path.dirname(at)
82
+ if (up === at) return ''
83
+ at = up
84
+ }
85
+ }
86
+
87
+ /**
88
+ * Locate the project from `from` in the primary checkout.
89
+ *
90
+ * `git(args)` is a reader bound to `from`, returning trimmed stdout or `null`
91
+ * (not a repo) — injected, as everywhere in `env/`. Returns
92
+ * `{ root, prefix, dir }`: the primary checkout's root, the project's prefix
93
+ * within it, and the project folder there (`root` itself when the prefix is
94
+ * `''`). Not a repo → `{ root: from, prefix: '', dir: from }`.
95
+ *
96
+ * The primary root is the parent of the shared git dir — `.git` relative from
97
+ * the primary checkout, `../../.git` from a subfolder of it, an absolute
98
+ * `<main>/.git` from a linked worktree. The prefix is found in the tree you are
99
+ * standing in and applied to the primary, which holds because a worktree is a
100
+ * checkout of the same repo: the project is at the same place in both.
101
+ */
102
+ function primaryAnchor(from, git) {
103
+ const common = git(['rev-parse', '--git-common-dir'])
104
+ if (!common) return { root: from, prefix: '', dir: from }
105
+ // Canonical, so one folder prints one way wherever the command was run from.
106
+ // From the primary checkout `common` is relative (`.git`) and the root came
107
+ // out spelled as `from` was; from a worktree git hands back an absolute,
108
+ // long-form path — on Windows `RUNNER~1` against `runneradmin` for the same
109
+ // folder, and `integrate` printed two different plans (chore-windows-ci).
110
+ const root = real(path.dirname(path.resolve(from, common)))
111
+ const toplevel = git(['rev-parse', '--show-toplevel'])
112
+ const prefix = toplevel ? findPrefix(from, toplevel) : ''
113
+ return { root, prefix, dir: projectIn(root, prefix) }
114
+ }
115
+
116
+ /** The project's OS folder within a checkout root (the root when prefix is `''`). */
117
+ function projectIn(root, prefix) {
118
+ return prefix ? path.join(root, ...prefix.split('/')) : root
119
+ }
120
+
121
+ /**
122
+ * A repo path as a project-relative path, or `null` when it is outside the
123
+ * project. Prefix `''` returns the path unchanged.
124
+ */
125
+ function fromRepoPath(rel, prefix) {
126
+ if (!prefix) return rel
127
+ if (rel === prefix) return ''
128
+ return rel.startsWith(`${prefix}/`) ? rel.slice(prefix.length + 1) : null
129
+ }
130
+
131
+ /**
132
+ * A repo path as seen from the project folder: `fromRepoPath` inside the
133
+ * project, `../…` outside it — the form a pathspec takes when it is run from the
134
+ * project folder, which is where a session stands. Prefix `''` returns it
135
+ * unchanged.
136
+ */
137
+ function projectRelative(rel, prefix) {
138
+ if (!prefix) return rel
139
+ const inside = fromRepoPath(rel, prefix)
140
+ return inside !== null ? inside : path.posix.relative(prefix, rel)
141
+ }
142
+
143
+ /** A project-relative path as a repo path. Prefix `''` returns it unchanged. */
144
+ function toRepoPath(rel, prefix) {
145
+ if (!prefix) return rel
146
+ return rel ? `${prefix}/${rel}` : prefix
147
+ }
148
+
149
+ /**
150
+ * Record where the project sits on a loaded config, for the code that needs the
151
+ * repo's root rather than the project folder — the worktree layout and `{repo}`
152
+ * resolve against the root, so worktrees land beside the repo rather than
153
+ * inside it. Non-enumerable, so it never reaches a JSON dump or a hash of the
154
+ * config.
155
+ */
156
+ function attachProject(config, anchor) {
157
+ Object.defineProperty(config, 'project', {
158
+ value: Object.freeze({ root: anchor.root, prefix: anchor.prefix }),
159
+ enumerable: false,
160
+ configurable: true,
161
+ })
162
+ return config
163
+ }
164
+
165
+ /**
166
+ * A path as one shell word, for the commands the engine PRINTS for a person or
167
+ * a skill to run. Quoted only when it has to be, so a path without spaces or
168
+ * shell characters prints byte-identically to before. Double quotes, because
169
+ * they mean the same in bash, zsh, Git Bash and cmd for an ordinary path; the
170
+ * three characters bash still expands inside them are escaped.
171
+ *
172
+ * A WINDOWS DRIVE PATH PRINTS WITH FORWARD SLASHES (`C:/Users/x/wt`): git, Git
173
+ * Bash, cmd and PowerShell all take that form unquoted, where `C:\Users` loses
174
+ * its backslashes in Git Bash (`C:Users`) unless quoted (chore-windows-ci).
175
+ *
176
+ * WHY QUOTING AT ALL: a repo at `C:\Code\LSC App` lays its worktrees out at
177
+ * `LSC App-wt`, and `git worktree add C:/Code/LSC App-wt/x -b …` is two
178
+ * arguments.
179
+ */
180
+ function shellPath(p, platform = process.platform) {
181
+ let s = String(p)
182
+ // A drive path anywhere; on Windows every backslash, which is always a
183
+ // separator there — `\\wt\\x` from a rooted path is no different.
184
+ if (platform === 'win32' || /^[A-Za-z]:[\\/]/.test(s)) s = s.replace(/\\/g, '/')
185
+ // `~` only where bash expands it — at the start; `RUNNER~1` needs no quotes.
186
+ if (!/[\s"'$`!&|;<>()*?[\]{}#\\]/.test(s) && !s.startsWith('~')) return s
187
+ return `"${s.replace(/(["$`])/g, '\\$1')}"`
188
+ }
189
+
190
+ /** The repo root a config was loaded for, else `dir` — today's behaviour. */
191
+ function repoRootOf(dir, config) {
192
+ return (config && config.project && config.project.root) || dir
193
+ }
194
+
195
+ /** The project prefix a config was loaded for, else `''`. */
196
+ function prefixOf(config) {
197
+ return (config && config.project && config.project.prefix) || ''
198
+ }
199
+
200
+ /**
201
+ * The one line that says where the project is, or `''` at the root — a root
202
+ * layout prints nothing new.
203
+ */
204
+ function projectLine(anchor) {
205
+ if (!anchor || !anchor.prefix) return ''
206
+ return `subfolder: ${anchor.prefix}/ (in repo ${anchor.root})\n`
207
+ }
208
+
209
+ module.exports = {
210
+ MARKER,
211
+ findPrefix,
212
+ primaryAnchor,
213
+ projectIn,
214
+ fromRepoPath,
215
+ projectRelative,
216
+ toRepoPath,
217
+ toPosix,
218
+ shellPath,
219
+ attachProject,
220
+ repoRootOf,
221
+ prefixOf,
222
+ projectLine,
223
+ }
@@ -15,6 +15,7 @@ const { classifyDirtyTree } = require('./classify.js')
15
15
  const { portOffset } = require('./registry.js')
16
16
  const { renderEnvFile } = require('./render.js')
17
17
  const { expandTokens } = require('./resolve.js')
18
+ const { shellPath, prefixOf, projectRelative } = require('./project.js')
18
19
 
19
20
  // Cap a path list in a message: enough to recognise, not a wall of text.
20
21
  function listPaths(paths) {
@@ -90,7 +91,13 @@ function planSpecCommit(spec, ctx, config, { carriesChanges = false } = {}) {
90
91
  return ok
91
92
  }
92
93
 
93
- const { owned, foreign } = classifyDirtyTree(spec, c.dirtyPaths, config)
94
+ // Git paths in, PROJECT paths out: the planned `git add -- …` runs from the
95
+ // project folder, and a project in a subfolder of its repo must not name
96
+ // `<prefix>/specs/…` from inside `<prefix>` (feat-subfolder-project).
97
+ const split = classifyDirtyTree(spec, c.dirtyPaths, config)
98
+ const prefix = prefixOf(config)
99
+ const owned = split.owned.map((p) => projectRelative(p, prefix))
100
+ const foreign = split.foreign.map((p) => projectRelative(p, prefix))
94
101
 
95
102
  // FOREIGN DIRT REFUSES ONLY WHERE IT CAN REACH THE BRANCH, which is checkout
96
103
  // mode and nowhere else. `git switch -c` carries the working tree onto the new
@@ -252,7 +259,9 @@ function worktreeSteps(spec, offset, config, opts = {}) {
252
259
  const seed = config.seedFiles || { mode: 'symlink', files: [] }
253
260
  const mode = seed.mode === 'copy' ? 'copy' : 'symlink'
254
261
  const tokens = {
255
- worktreePath: spec.worktreePath,
262
+ // The step's own cwd — the project folder inside the worktree — so the
263
+ // documented "{worktreePath} is the cwd" stays true for a subfolder project.
264
+ worktreePath: spec.projectPath || spec.worktreePath,
256
265
  slug: spec.slug,
257
266
  branch: spec.branch,
258
267
  projectName: spec.projectName,
@@ -361,12 +370,12 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
361
370
  const resume = !attached && spec.resumeFrom ? spec.resumeFrom : null
362
371
  if (resume) {
363
372
  commands.push(`git fetch ${resume.remote} ${spec.branch}`)
364
- commands.push(`git worktree add ${spec.worktreePath} -b ${spec.branch} --track ${resume.remote}/${spec.branch}`)
373
+ commands.push(`git worktree add ${shellPath(spec.worktreePath)} -b ${spec.branch} --track ${resume.remote}/${spec.branch}`)
365
374
  } else {
366
375
  commands.push(
367
376
  attached
368
- ? `git worktree add ${spec.worktreePath} ${spec.branch}`
369
- : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
377
+ ? `git worktree add ${shellPath(spec.worktreePath)} ${spec.branch}`
378
+ : `git worktree add ${shellPath(spec.worktreePath)} -b ${spec.branch}${forkPoint}`,
370
379
  )
371
380
  }
372
381
  // The tree gate. A worktree forks from the base branch's tree, so an
@@ -386,6 +395,7 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
386
395
  // report from "provisioned", and the caller cannot reconstruct it.
387
396
  untouched: gate.foreign || [],
388
397
  worktreePath: spec.worktreePath,
398
+ projectPath: spec.projectPath || spec.worktreePath,
389
399
  branch: spec.branch,
390
400
  projectName: spec.projectName,
391
401
  slot: wantsDocker ? slot : null,
@@ -16,6 +16,7 @@
16
16
 
17
17
  const fs = require('node:fs')
18
18
  const path = require('node:path')
19
+ const { primaryAnchor, repoRootOf, prefixOf, projectIn } = require('./project.js')
19
20
 
20
21
  const BUCKETS = ['backlog', 'in-progress', 'complete', 'cancelled']
21
22
 
@@ -524,17 +525,20 @@ function newestMatch(config, git, pattern) {
524
525
  }
525
526
 
526
527
  /**
527
- * Resolve `dir` to the primary checkout root — the parent of the shared git dir.
528
- * From the primary checkout `git rev-parse --git-common-dir` is `.git` (relative),
529
- * so the parent is `dir`; from a linked worktree it's the absolute `<main>/.git`,
530
- * so the parent is `<main>`. Anchoring every `spec-env` command here means they
531
- * resolve `{repo}` / worktree paths / the registry identically whether run from
532
- * `main` or a worktree. `git(args)` returns trimmed stdout or `null` (not a repo)
533
- * — injected for testability; a `null` degrades to `dir` (today's behaviour).
528
+ * Resolve `dir` to the PROJECT FOLDER in the primary checkout — the primary root
529
+ * (the parent of the shared git dir) joined with the project's prefix, which is
530
+ * `''` when the project is the repo. From the primary checkout
531
+ * `git rev-parse --git-common-dir` is `.git` (relative), so the root is `dir`;
532
+ * from a linked worktree it's the absolute `<main>/.git`, so the root is
533
+ * `<main>`. Anchoring every `spec-env` command here means they read the config
534
+ * and registry identically whether run from `main` or a worktree.
535
+ * `git(args)` returns trimmed stdout or `null` (not a repo) — injected for
536
+ * testability; a `null` degrades to `dir` (today's behaviour). `env/project.js`
537
+ * carries how the prefix is found; `{repo}` and the worktree layout resolve
538
+ * against the root, which a loaded config carries (`attachProject`).
534
539
  */
535
540
  function resolvePrimaryCheckout(dir, git) {
536
- const common = git(['rev-parse', '--git-common-dir'])
537
- return common ? path.dirname(path.resolve(dir, common)) : dir
541
+ return primaryAnchor(dir, git).dir
538
542
  }
539
543
 
540
544
  /**
@@ -601,7 +605,8 @@ function assertPrimaryOnMain(config, git) {
601
605
  * Pure but for `repoInfo`, like `resolveSpec`.
602
606
  */
603
607
  function resolveSpecless(name, dir, config, entry = {}) {
604
- const { repo, repoSlug } = repoInfo(dir)
608
+ const root = repoRootOf(dir, config)
609
+ const { repo, repoSlug } = repoInfo(root)
605
610
  // AN AUTHORING RECORD RESOLVES AS THE SPEC IT WILL BE. `spec: true` marks a
606
611
  // record written by `up --docs` for a spec not written yet (the `/spec`
607
612
  // authoring lane), so type and slug come from the name's own prefix — the
@@ -634,14 +639,19 @@ function resolveSpecless(name, dir, config, entry = {}) {
634
639
  branch,
635
640
  worktreeRoot,
636
641
  worktreeFolder,
637
- worktreePath: path.resolve(dir, worktreeRoot, worktreeFolder),
642
+ worktreePath: path.resolve(root, worktreeRoot, worktreeFolder),
643
+ projectPath: projectIn(path.resolve(root, worktreeRoot, worktreeFolder), prefixOf(config)),
644
+ prefix: prefixOf(config),
638
645
  projectName: expandTokens(config.docker.projectNamePattern, tokens),
639
646
  }
640
647
  }
641
648
 
642
649
  function resolveSpec(specArg, dir, config, opts = {}) {
643
- const searchDirs = opts.searchDirs || []
644
- const preferDirs = opts.preferDirs || []
650
+ // Both are CHECKOUT ROOTS (worktrees, from `git worktree list` or the config's
651
+ // layout); a spec lives in the project folder inside each one.
652
+ const prefix = prefixOf(config)
653
+ const searchDirs = (opts.searchDirs || []).map((d) => projectIn(d, prefix))
654
+ const preferDirs = (opts.preferDirs || []).map((d) => projectIn(d, prefix))
645
655
  const found = findSpecFolder(specArg, dir, searchDirs, preferDirs)
646
656
  if (!found) {
647
657
  // A SPECLESS BRANCH, but only on the registry's word. `/no-spec` work has a
@@ -667,7 +677,10 @@ function resolveSpec(specArg, dir, config, opts = {}) {
667
677
  }
668
678
 
669
679
  const { type, slug } = splitPrefix(found.folder)
670
- const { repo, repoSlug } = repoInfo(dir)
680
+ // The repo's root, not the project folder: `{repo}` names the repo and the
681
+ // worktree layout sits beside it (spec feat-subfolder-project, decision 4).
682
+ const root = repoRootOf(dir, config)
683
+ const { repo, repoSlug } = repoInfo(root)
671
684
  const tokens = { repo, repoSlug, slug }
672
685
 
673
686
  const stack = readStackField(found.path, config)
@@ -693,7 +706,10 @@ function resolveSpec(specArg, dir, config, opts = {}) {
693
706
 
694
707
  const worktreeRoot = expandTokens(config.worktree.root, tokens)
695
708
  const worktreeFolder = expandTokens(config.worktree.folderPattern, tokens)
696
- const worktreePath = path.resolve(dir, worktreeRoot, worktreeFolder)
709
+ const worktreePath = path.resolve(root, worktreeRoot, worktreeFolder)
710
+ // Where the project sits inside the worktree — what a session stands in and
711
+ // what project-scoped steps run in. The worktree itself when the prefix is ''.
712
+ const projectPath = projectIn(worktreePath, prefixOf(config))
697
713
  const projectName = expandTokens(config.docker.projectNamePattern, tokens)
698
714
 
699
715
  return {
@@ -704,6 +720,10 @@ function resolveSpec(specArg, dir, config, opts = {}) {
704
720
  worktreeRoot,
705
721
  worktreeFolder,
706
722
  worktreePath,
723
+ projectPath,
724
+ // The project's folder within the repo, as a repo path ('' at the root) —
725
+ // what turns a git path into a project path (env/project.js).
726
+ prefix: prefixOf(config),
707
727
  projectName,
708
728
  }
709
729
  }
@@ -755,13 +775,15 @@ function collectSpecFolders(roots) {
755
775
  function allSpecs(dir, config, worktreePaths, specless = {}) {
756
776
  const searchDirs = [...worktreePaths]
757
777
  const specs = []
758
- for (const folder of collectSpecFolders([dir, ...searchDirs])) {
778
+ const projects = searchDirs.map((d) => projectIn(d, prefixOf(config)))
779
+ for (const folder of collectSpecFolders([dir, ...projects])) {
759
780
  try {
760
781
  const spec = resolveSpec(folder, dir, config, { searchDirs })
761
782
  specs.push({
762
783
  folder: spec.folder,
763
784
  slug: spec.slug,
764
785
  worktreePath: spec.worktreePath,
786
+ projectPath: spec.projectPath,
765
787
  specless: false,
766
788
  })
767
789
  } catch {
@@ -786,6 +808,7 @@ function allSpecs(dir, config, worktreePaths, specless = {}) {
786
808
  folder: spec.folder,
787
809
  slug: spec.slug,
788
810
  worktreePath: spec.worktreePath,
811
+ projectPath: spec.projectPath,
789
812
  specless: true,
790
813
  })
791
814
  }