@skitterbyte/skitterspec-linear 17.3.2 → 17.4.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.
@@ -90,7 +90,17 @@ through to a documented conservative default; see the field notes below.
90
90
  "projectNamePattern": "{repoSlug}_{slug}", // → COMPOSE_PROJECT_NAME
91
91
  "portBase": 3000, // first port of slot 0's block
92
92
  "portsPerSpec": 10, // block width; slot n → portBase + n*portsPerSpec
93
- "envFile": ".env", // written into the worktree
93
+ // Written into the worktree, and passed to compose as `--env-file`. A
94
+ // Docker spec's worktree steps run in this order: seedFiles, this env file
95
+ // (COMPOSE_PROJECT_NAME and PORT_OFFSET appended only where missing, so a
96
+ // value `setup` or you put there is kept), `setup`, then
97
+ // `docker compose … up -d` — all from inside the worktree, so the stack
98
+ // reads this spec's values and not the primary checkout's.
99
+ // It must be a file of its OWN: if it is also in `seedFiles` as a symlink,
100
+ // the write is refused rather than send this spec's port block into the
101
+ // primary checkout's file. Name a different file here (".worktree.env")
102
+ // and have your compose file read the values from it.
103
+ "envFile": ".env",
94
104
  "backupCommand": "" // optional pre-teardown backup (e.g. pg_dump);
95
105
  // empty = no backup, volumes dropped directly.
96
106
  },
@@ -116,6 +126,8 @@ through to a documented conservative default; see the field notes below.
116
126
  // `local.settings.json`, `config/local.yml`.
117
127
  // Seeded files are gitignored, so they never make the worktree "dirty" and
118
128
  // never block teardown; they vanish with the worktree at `spec-env down`.
129
+ // On a Docker project, do not seed `docker.envFile` as a symlink — the env
130
+ // file step refuses to write through one (see `envFile` above).
119
131
  // [] (or absent) = seed nothing (current behaviour).
120
132
  "seedFiles": {
121
133
  "mode": "symlink",
@@ -147,6 +147,28 @@ That is `[{ spec, bucket, identifier }]`. Key it by `identifier` and attach each
147
147
  issue's local `spec` folder name. Format the rows exactly as the API path does
148
148
  (step 5), including the archived-exclusion line and the `showing N of M` count.
149
149
 
150
+ **Then build the local-only section from the same output.** Entries with
151
+ `identifier: null` are specs Linear has never seen. Keep only those in a live
152
+ bucket the scope covers: `backlog` and `in-progress` by default, `backlog` alone
153
+ under `--next`, `in-progress` alone under `--in-progress`. Never `complete` or
154
+ `cancelled`, under any scope, because those hold specs from before Linear was
155
+ adopted. Print them below the rows, outside the count and outside any `--next`
156
+ cap, exactly as the API path does:
157
+
158
+ ```
159
+ local only — not linked on this branch (2)
160
+ bug-compose-before-env backlog /spec-push bug-compose-before-env
161
+ ```
162
+
163
+ Say **"not linked on this branch"**, never "not in Linear". The identifier is
164
+ read from this branch's copy of the file, so a spec pushed from its own worktree
165
+ whose stamp has not landed here looks exactly the same.
166
+
167
+ Under `--mine` or `--by`, leave the section out. These specs have no Linear
168
+ assignee to match, so instead print one line:
169
+ `N unpushed specs not filtered by assignee — the bare listing shows them`.
170
+ When there are none, print nothing at all: no heading, and no line.
171
+
150
172
  ## 4. Degrade — never leave them with nothing
151
173
 
152
174
  Linear unreachable, no credential, no MCP tool, a Linear error: **do not stop**.
@@ -182,6 +204,11 @@ user reads:
182
204
  - **A row with no local match stays in**, marked `— (not linked here)`. It is not
183
205
  noise: a teammate's unlanded spec, or one authored inside another spec's
184
206
  worktree, is precisely what the repo could not have told them.
207
+ - **The local-only section, when there is one** —
208
+ `local only — not linked on this branch (N)`, each row with its
209
+ `/spec-push <name>` hint, or the hidden-count line under `--mine` / `--by`.
210
+ It is the reverse of the row above: a spec this branch holds that Linear
211
+ cannot list. Leaving it out is how a written spec goes invisible.
185
212
 
186
213
  Finish with the hand-off, because every row carries the folder name for it —
187
214
  as a sentence, not a fenced block: say that `/spec-start <name>` starts any of
@@ -216,3 +243,5 @@ would have to pick one. The counts — `showing N of M` — and the archived
216
243
  exclusion belong to the listing above, where the engine already prints them.
217
244
 
218
245
  `Next` is the hand-off: `/spec-start <name>`, with a name copied from a row.
246
+ When the only rows are local-only ones, `Next` is `/spec-push <name>` instead,
247
+ because a spec Linear cannot see is linked before it is started.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "17.3.2",
3
+ "version": "17.4.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -1097,21 +1097,20 @@ function specEnvUp(dir, config, specArg, flags = {}) {
1097
1097
  out.push('')
1098
1098
  out.push(' to provision, run:')
1099
1099
  for (const cmd of plan.commands) out.push(` ${cmd}`)
1100
- // Seed files first (setup may depend on them), then the setup commands —
1101
- // both run in the worktree, under one heading.
1102
- const worktreeSteps = [...plan.seedCommands, ...plan.setupCommands]
1100
+ // Everything after the fork runs in the worktree, under one heading, in the
1101
+ // order each step depends on the last: seeds (the env file may be one), the
1102
+ // env file, setup (which may derive values into it), and only then the stack.
1103
+ const worktreeSteps = [
1104
+ ...plan.seedCommands,
1105
+ ...(plan.envCommands || []),
1106
+ ...plan.setupCommands,
1107
+ ...(plan.dockerCommands || []),
1108
+ ]
1103
1109
  if (worktreeSteps.length) {
1104
1110
  out.push('')
1105
1111
  out.push(' then, in the worktree, run:')
1106
1112
  for (const cmd of worktreeSteps) out.push(` ${cmd}`)
1107
1113
  }
1108
- if (plan.envContents) {
1109
- out.push('')
1110
- out.push(` write ${config.docker.envFile} in the worktree:`)
1111
- for (const line of plan.envContents.replace(/\n$/, '').split('\n')) {
1112
- out.push(` ${line}`)
1113
- }
1114
- }
1115
1114
  process.stdout.write(out.join('\n') + '\n')
1116
1115
  }
1117
1116
 
@@ -4,8 +4,8 @@
4
4
  * Pure provisioning planner for `spec-env up`.
5
5
  *
6
6
  * Given a resolved spec and its allocated slot, `planUp` returns the exact
7
- * side-effecting commands the `/spec-env` skill runs (`git worktree add`,
8
- * `docker compose up`) and the rendered `.env` contents — but performs no side
7
+ * side-effecting commands the `/spec-env` skill runs (`git worktree add`, the
8
+ * env file, `docker compose up`) and the rendered `.env` contents — but performs no side
9
9
  * effects itself. The caller (the CLI) reads/allocates the
10
10
  * registry and passes the slot; this stays deterministic and unit-testable with
11
11
  * no live git/docker.
@@ -73,6 +73,50 @@ function seedCommandFor(file, mode) {
73
73
  }
74
74
 
75
75
 
76
+ // Single-quote a value for POSIX sh: the only character that needs escaping
77
+ // inside single quotes is the single quote itself.
78
+ function shq(value) {
79
+ return `'${String(value).replace(/'/g, `'\\''`)}'`
80
+ }
81
+
82
+ /**
83
+ * Build one idempotent POSIX-sh command that writes the spec's env file in the
84
+ * current worktree (the cwd when the skill runs it).
85
+ *
86
+ * It was prose once — "write <envFile> in the worktree:" — which left the write
87
+ * to whoever read the plan, and a secrets guard that blocks any tool call naming
88
+ * `.env` refused it. As a command it is one more step the plan runs.
89
+ *
90
+ * Idempotent and additive: it `touch`es the file and appends each key only when
91
+ * no line already sets it, so a re-run changes nothing and a file `setup` has
92
+ * already written to keeps every value it holds — including a deliberate
93
+ * `PORT_OFFSET` of its own.
94
+ *
95
+ * A SYMLINK IS REFUSED, loudly. Seeding links gitignored files from the primary
96
+ * checkout, so a seeded env file is the primary checkout's own; appending
97
+ * through it would write this spec's port block into the main stack's
98
+ * configuration. It runs after the seeds precisely so that collision is caught
99
+ * rather than hidden. The fix is a `docker.envFile` naming a file of its own.
100
+ */
101
+ function envFileCommandFor(envFile, projectName, offset) {
102
+ const f = shq(envFile)
103
+ const ensure = (key, value) =>
104
+ `{ grep -q '^${key}=' ${f} || echo ${shq(`${key}=${value}`)} >> ${f}; }`
105
+ return (
106
+ `if [ -L ${f} ]; then echo ${shq(
107
+ `env file ${envFile} is a symlink — docker.envFile must name a file of its ` +
108
+ "own, not a seeded one; refusing to write this spec's port block through it",
109
+ )} >&2; exit 1; fi; ` +
110
+ `touch ${f} && ` +
111
+ // A file without a trailing newline would glue the first appended key onto
112
+ // its last line.
113
+ `{ [ ! -s ${f} ] || [ -z "$(tail -c 1 ${f})" ] || echo >> ${f}; } && ` +
114
+ `${ensure('COMPOSE_PROJECT_NAME', projectName)} && ` +
115
+ `${ensure('PORT_OFFSET', offset)} && ` +
116
+ `echo ${shq(`env file ${envFile}: ready`)}`
117
+ )
118
+ }
119
+
76
120
  // Cap a path list in a message: enough to recognise, not a wall of text.
77
121
  function listPaths(paths) {
78
122
  const shown = paths.slice(0, 5).join(', ')
@@ -294,8 +338,10 @@ function resolveStack(spec, config, { docs = false, composeFilePresent } = {}) {
294
338
  * @param {object} config normalised env config.
295
339
  * @param {object} opts { docs } — documents mode (see below). Optional.
296
340
  * @returns {object} { worktreePath, branch, projectName, slot, portOffset,
297
- * envContents, commands, seedCommands,
298
- * setupCommands, docs, attached }
341
+ * envContents, commands, seedCommands, envCommands,
342
+ * setupCommands, dockerCommands, docs, attached }
343
+ *
344
+ * The worktree steps run in that order: seeds, env file, setup, compose.
299
345
  */
300
346
  function planUp(spec, alloc, config, ctx, opts = {}) {
301
347
  const { slot, attached } = alloc
@@ -367,12 +413,24 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
367
413
  ? `git worktree add ${spec.worktreePath} ${spec.branch}`
368
414
  : `git worktree add ${spec.worktreePath} -b ${spec.branch}${forkPoint}`,
369
415
  )
370
- if (wantsDocker) {
371
- commands.push(
372
- `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
373
- ` --project-name ${spec.projectName} up -d`,
374
- )
375
- }
416
+ // The stack comes up LAST, in the worktree: after the seeds, after the env
417
+ // file, after `setup` — which may derive values into that file. It once ran
418
+ // from the primary checkout before the worktree existed, so compose read the
419
+ // primary checkout's env file, fell back to its defaults and collided with the
420
+ // main stack. `--env-file` is always passed: with the default `.env` it is what
421
+ // compose would have found anyway, and with any other name it is the only way
422
+ // compose finds it.
423
+ const envFile = (config.docker && config.docker.envFile) || '.env'
424
+ const envCommands = wantsDocker
425
+ ? [`${guard}; ${envFileCommandFor(envFile, spec.projectName, offset)}`]
426
+ : []
427
+ const dockerCommands = wantsDocker
428
+ ? [
429
+ `${guard}; docker compose` +
430
+ composeFileArg(config, ctx ? ctx.composeFilePresent : undefined) +
431
+ ` --env-file ${shq(envFile)} --project-name ${spec.projectName} up -d`,
432
+ ]
433
+ : []
376
434
 
377
435
  // The tree gate. A worktree forks from the base branch's tree, so an
378
436
  // uncommitted spec would produce a branch missing the spec it is for — this is
@@ -398,11 +456,13 @@ function planUp(spec, alloc, config, ctx, opts = {}) {
398
456
  envContents,
399
457
  commands: gate.blocked ? [] : [...gate.commands, ...commands],
400
458
  seedCommands: gate.blocked ? [] : seedCommands,
459
+ envCommands: gate.blocked ? [] : envCommands,
401
460
  // Documents mode drops these, and keeps the seed commands above. The two are
402
461
  // not the same kind of thing: seeding links the gitignored files a worktree
403
462
  // has none of — cheap, and a spec author may well want `.env` present —
404
463
  // while `setup` is the expensive half that exists to make the tree run.
405
464
  setupCommands: gate.blocked || docs ? [] : setupCommands,
465
+ dockerCommands: gate.blocked ? [] : dockerCommands,
406
466
  // Reported so a caller reading `--json` can tell a documents worktree from a
407
467
  // full one POSITIVELY, rather than inferring it from what is missing. An
408
468
  // empty `setupCommands` also describes a project that configured no setup
@@ -481,6 +541,7 @@ module.exports = {
481
541
  planCheckoutUp,
482
542
  planSpecCommit,
483
543
  seedCommandFor,
544
+ envFileCommandFor,
484
545
  worktreeCd,
485
546
  resolveStack,
486
547
  composeFileArg,
@@ -94,6 +94,10 @@ function planDown(spec, config, flags, ctx) {
94
94
  }
95
95
 
96
96
  // --- docker compose down (drop volumes unless kept) ---
97
+ // Run from the primary checkout with no `--env-file`, unlike `up`, and on
98
+ // purpose: compose finds the stack's containers, networks and volumes by the
99
+ // project label `--project-name` gives it, so it needs nothing from the env
100
+ // file — which may already be gone with a half-removed worktree.
97
101
  if (wantsDocker) {
98
102
  const base =
99
103
  `docker compose${composeFileArg(config, ctx ? ctx.composeFilePresent : undefined)}` +
@@ -2372,11 +2372,31 @@ async function specSyncList(dir, config, flags, out) {
2372
2372
  // is what every existing caller already reads.
2373
2373
  const ordered = next === null ? issues : issues.slice().sort(backlogOrder)
2374
2374
 
2375
+ const localSpecs = listSpecs(dir, config)
2375
2376
  const byIdentifier = new Map(
2376
- listSpecs(dir, config)
2377
+ localSpecs
2377
2378
  .filter((s) => s.identifier)
2378
2379
  .map((s) => [s.identifier, s]),
2379
2380
  )
2381
+ // Specs Linear has never seen: no identifier, in a live bucket the scope
2382
+ // covers. Only the live buckets, under every scope — complete/ holds specs
2383
+ // from before Linear was adopted, never pushed and never going to be.
2384
+ //
2385
+ // WHAT WOULD FOOL THIS: the identifier is read from THIS branch's copy of the
2386
+ // file. A spec pushed from its own worktree whose stamp has not landed here
2387
+ // reads exactly like one never pushed — which is why the section says "not
2388
+ // linked on this branch" and never "not in Linear".
2389
+ const localBuckets = next !== null
2390
+ ? ['backlog']
2391
+ : flags.inProgress === true
2392
+ ? ['in-progress']
2393
+ : ['backlog', 'in-progress']
2394
+ const unlinked = localSpecs
2395
+ .filter((s) => !s.identifier && localBuckets.includes(s.bucket))
2396
+ .map((s) => ({ spec: s.spec, bucket: s.bucket }))
2397
+ // An assignee filter cannot be applied to a spec with no Linear assignee, so
2398
+ // the section is withheld under one — counted, never silently dropped.
2399
+ const localHidden = assignee ? unlinked.length : null
2380
2400
  // Identifier → Linear uuid, for the phase lookup below. Kept beside the rows
2381
2401
  // rather than on them, so the --json shape stays exactly what it prints.
2382
2402
  const uuidOf = new Map(ordered.map((i) => [i.identifier, i.id]))
@@ -2483,6 +2503,7 @@ async function specSyncList(dir, config, flags, out) {
2483
2503
  ...(next !== null ? { unprioritised } : {}),
2484
2504
  assignedTo: assignee,
2485
2505
  specs: shown,
2506
+ ...(localHidden === null ? { local: unlinked } : { localHidden }),
2486
2507
  },
2487
2508
  null,
2488
2509
  2,
@@ -2516,6 +2537,11 @@ async function specSyncList(dir, config, flags, out) {
2516
2537
  ` ! could not read the phases of ${phaseFailures.join(', ')} — those rows show no phase`,
2517
2538
  )
2518
2539
  }
2540
+ if (localHidden) {
2541
+ lines.push(
2542
+ ` ${localHidden} unpushed spec${localHidden === 1 ? '' : 's'} not filtered by assignee — the bare listing shows them`,
2543
+ )
2544
+ }
2519
2545
  lines.push('')
2520
2546
  if (!shown.length) {
2521
2547
  lines.push(' no spec issues in scope')
@@ -2536,6 +2562,17 @@ async function specSyncList(dir, config, flags, out) {
2536
2562
  )
2537
2563
  if (row.title) lines.push(` ${pad}${row.title}`)
2538
2564
  }
2565
+ }
2566
+ if (localHidden === null && unlinked.length) {
2567
+ const nameW = Math.max(...unlinked.map((s) => s.spec.length))
2568
+ const bucketW = Math.max(...unlinked.map((s) => s.bucket.length))
2569
+ lines.push('')
2570
+ lines.push(` local only — not linked on this branch (${unlinked.length})`)
2571
+ for (const s of unlinked) {
2572
+ lines.push(` ${s.spec.padEnd(nameW)} ${s.bucket.padEnd(bucketW)} /spec-push ${s.spec}`)
2573
+ }
2574
+ }
2575
+ if (shown.length) {
2539
2576
  lines.push('')
2540
2577
  lines.push(' start one with: /spec-start <name>')
2541
2578
  }