@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.
@@ -35,6 +35,11 @@ exactly one):
35
35
  npx @skitterbyte/skitterspec-jira init
36
36
  ```
37
37
 
38
+ **A project in a subfolder of its repo** (a solution folder beside `Sql/`,
39
+ say) installs and runs exactly the same way, from that folder: install the
40
+ package there or above it, and run `spec-sync` from it. `specs/.core/env.config.md`
41
+ → *A project in a subfolder of its repo* has the details.
42
+
38
43
  ## 2. Credentials — an email + API-token pair
39
44
 
40
45
  Jira Cloud authenticates REST calls with basic auth: your Atlassian account
@@ -68,6 +68,8 @@ through to a documented conservative default; see the field notes below.
68
68
  "worktree": {
69
69
  "root": "../{repo}-wt", // dir that holds all spec worktrees; sibling of
70
70
  // the primary checkout, never nested inside it.
71
+ // Resolved against the REPO root, even for a
72
+ // project in a subfolder of its repo (below).
71
73
  "folderPattern": "{slug}" // per-spec worktree dir name.
72
74
  },
73
75
 
@@ -141,7 +143,8 @@ through to a documented conservative default; see the field notes below.
141
143
  // typechecks, builds and tests work immediately instead of failing on a
142
144
  // missing node_modules. An array, run in order, stopping at the first that
143
145
  // exits non-zero; [] = none. Each string is a shell command; {slug}/{branch}/{worktreePath}/{projectName}/{portOffset}
144
- // expand (the cwd is already the worktree, so {worktreePath} is usually
146
+ // expand (the cwd is already the worktree — the project folder inside it, for a
147
+ // project in a subfolder of its repo — so {worktreePath} is usually
145
148
  // redundant). Example: ["pnpm install --frozen-lockfile"].
146
149
  // An entry may also be { "run": "<cmd>", "when": ["<glob>", ...] }. `when` is
147
150
  // IGNORED here — a fresh worktree always runs every setup step — and exists
@@ -659,9 +662,57 @@ through to a documented conservative default; see the field notes below.
659
662
  }
660
663
  ```
661
664
 
665
+ ## A project in a subfolder of its repo
666
+
667
+ Most projects ARE their repo: `specs/` and `.claude/` sit at the git root. Some
668
+ cannot — a Visual Studio solution folder beside `Sql/` and a prototype or two,
669
+ where sessions start in the solution folder, so that is where `.claude/` must be
670
+ for its skills and hooks to load, and where `specs/` belongs. That works with no
671
+ configuration:
672
+
673
+ ```
674
+ C:\Code\LSC App\ ← git root
675
+ ├── FF.CSC.Solution\ ← the project: specs/, .claude/, run Claude here
676
+ ├── Sql\
677
+ └── Prototype\
678
+ C:\Code\LSC App-wt\<spec>\ ← each spec's worktree, beside the repo
679
+ ```
680
+
681
+ - **The project is found, not configured.** Every `spec-env` verb walks up from
682
+ where it is run to the nearest folder holding `specs/.core/`, stopping at the
683
+ git root. Found at the root, it behaves exactly as it always has; found in a
684
+ subfolder, that subfolder is the project — from inside it or anywhere beneath
685
+ it. `spec-env resolve` and `skitterspec status` print a
686
+ `subfolder: FF.CSC.Solution/ (in repo C:\Code\LSC App)` line when it is not
687
+ the root, and nothing extra when it is. Several projects in one repo are not
688
+ supported: the nearest `specs/.core/` wins.
689
+ - **Repo-level things resolve against the repo root**: `worktree.root`, `{repo}`
690
+ (`LSC App`, not the project folder's name) and therefore the worktree layout.
691
+ A spec's worktree is a checkout of the whole repo, with the project at the same
692
+ place inside it.
693
+ - **Everything in this file is project-relative**: `setup`, `dev`, seed files,
694
+ `docker.composeFile` and `docker.envFile`, `registry`, `spec.companionPaths`,
695
+ and the folder `/spec-start` moves the session into
696
+ (`<worktree>/FF.CSC.Solution`). Git commands run against the worktree.
697
+ - **The review page lists git paths**, so the project's files carry its folder
698
+ (`FF.CSC.Solution/specs/…`) and a change beside it (`Sql/…`) is shown as code.
699
+ - **The main guard covers the whole primary checkout**, not only the project
700
+ folder: a write to `Sql/` on the base branch is unreviewed work too.
701
+ - **Install skitterspec in the project folder or above it.** The hooks find the
702
+ engine by walking UP from the session's folder to a `node_modules/.bin`; an
703
+ install below the project (say an Angular `ClientApp/node_modules`) is not
704
+ found, and the hooks fall back to `skitterspec` on your PATH.
705
+ - **Run `spec-sync` from the project folder.** The tracker providers take the
706
+ project from where they are run (or `--dir`); `release.ignorePaths` are read
707
+ against the project, so `specs/` means the project's.
708
+ - **Windows**: git prints `/` and paths with spaces are quoted in every command
709
+ the engine prints. A deep spec folder inside a worktree can pass 260
710
+ characters — set `git config --global core.longpaths true` once.
711
+
662
712
  ## Token expansion
663
713
 
664
- - `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
714
+ - `{repo}` — the repo root's dir basename (e.g. `skitterspec`) — the primary
715
+ checkout's root, which for a project in a subfolder is the folder above it.
665
716
  - `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
666
717
  (safe for a `COMPOSE_PROJECT_NAME`).
667
718
  - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-`/`hotfix-`/`chore-` prefix).
@@ -81,12 +81,22 @@ function readPayload() {
81
81
  * the local install is looked for by path first — walking up from the project,
82
82
  * because a git worktree's checkout has its own `node_modules`.
83
83
  */
84
- function findEngine(projectDir) {
84
+ const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
85
+
86
+ function findEngine(projectDir, platform = process.platform) {
85
87
  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
86
88
  let at = projectDir
87
89
  for (let i = 0; i < 6 && at; i++) {
88
- for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
89
- const candidate = path.join(at, 'node_modules', '.bin', name)
90
+ for (const name of ENGINES) {
91
+ // ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
92
+ // shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
93
+ // `.cmd` beside it needs a shell — which a hook handing a tool's command
94
+ // line over as an argument must never use. Unreachable, the hook failed
95
+ // open, and every guard was silently off on Windows (chore-windows-ci).
96
+ const candidate =
97
+ platform === 'win32'
98
+ ? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
99
+ : path.join(at, 'node_modules', '.bin', name)
90
100
  if (fs.existsSync(candidate)) return candidate
91
101
  }
92
102
  const up = path.dirname(at)
@@ -96,6 +106,13 @@ function findEngine(projectDir) {
96
106
  return 'skitterspec'
97
107
  }
98
108
 
109
+ // How to run what `findEngine` found: a `.js` engine through this node, since
110
+ // Windows cannot execute one directly — anything else as itself, as before.
111
+ function engineCommand(projectDir, platform = process.platform) {
112
+ const engine = findEngine(projectDir, platform)
113
+ return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
114
+ }
115
+
99
116
  // The tools that write a file. A matcher is configured too, but a hook that is
100
117
  // reached some other way must still be inert rather than guessing.
101
118
  //
@@ -147,7 +164,8 @@ function main() {
147
164
  const target = writeTarget(payload.tool_input)
148
165
  if (target) argv.push('--path', target)
149
166
 
150
- const result = spawnSync(findEngine(cwd), argv, { cwd, encoding: 'utf8', timeout: 8000 })
167
+ const engine = engineCommand(cwd)
168
+ const result = spawnSync(engine.file, [...engine.args, ...argv], { cwd, encoding: 'utf8', timeout: 8000 })
151
169
 
152
170
  // No engine, a crash, a timeout — all cannot-tell. `status` is null when the
153
171
  // process never ran or was killed, and neither is a refusal.
@@ -175,4 +193,4 @@ if (require.main === module) {
175
193
  }
176
194
  }
177
195
 
178
- module.exports = { findEngine, WRITE_TOOLS, writeTarget, isRefusal }
196
+ module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, isRefusal }
@@ -78,12 +78,22 @@ function readPayload() {
78
78
  * is the fallback for a global install, and `SKITTERSPEC_BIN` overrides
79
79
  * everything for anyone whose layout is neither.
80
80
  */
81
- function findEngine(projectDir) {
81
+ const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
82
+
83
+ function findEngine(projectDir, platform = process.platform) {
82
84
  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
83
85
  let at = projectDir
84
86
  for (let i = 0; i < 6 && at; i++) {
85
- for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
86
- const candidate = path.join(at, 'node_modules', '.bin', name)
87
+ for (const name of ENGINES) {
88
+ // ON WINDOWS, THE PACKAGE'S OWN JS ENTRY, never `.bin/<name>`. That is a
89
+ // shell shim nothing here can execute (spawn refuses it: EFTYPE), and the
90
+ // `.cmd` beside it needs a shell — which a hook handing a tool's command
91
+ // line over as an argument must never use. Unreachable, the hook failed
92
+ // open, and every guard was silently off on Windows (chore-windows-ci).
93
+ const candidate =
94
+ platform === 'win32'
95
+ ? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
96
+ : path.join(at, 'node_modules', '.bin', name)
87
97
  if (fs.existsSync(candidate)) return candidate
88
98
  }
89
99
  const up = path.dirname(at)
@@ -93,6 +103,13 @@ function findEngine(projectDir) {
93
103
  return 'skitterspec'
94
104
  }
95
105
 
106
+ // How to run what `findEngine` found: a `.js` engine through this node, since
107
+ // Windows cannot execute one directly — anything else as itself, as before.
108
+ function engineCommand(projectDir, platform = process.platform) {
109
+ const engine = findEngine(projectDir, platform)
110
+ return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
111
+ }
112
+
96
113
  // The engine's own refusal line, from `spec-env review gate --check`. Pure.
97
114
  //
98
115
  // WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
@@ -117,9 +134,10 @@ function main() {
117
134
  // its own checkout, and the answer differs per worktree.
118
135
  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
119
136
 
137
+ const engine = engineCommand(cwd)
120
138
  const result = spawnSync(
121
- findEngine(cwd),
122
- ['spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
139
+ engine.file,
140
+ [...engine.args, 'spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
123
141
  { cwd, encoding: 'utf8', timeout: 8000 },
124
142
  )
125
143
 
@@ -160,4 +178,4 @@ if (require.main === module) {
160
178
  }
161
179
  }
162
180
 
163
- module.exports = { findEngine, isRefusal }
181
+ module.exports = { findEngine, engineCommand, isRefusal }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-jira",
3
- "version": "2.4.0",
3
+ "version": "2.5.1",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
5
5
  "keywords": [
6
6
  "claude",