@skitterbyte/skitterspec-linear 19.7.0 → 19.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/env/config.js CHANGED
@@ -60,7 +60,7 @@
60
60
  */
61
61
 
62
62
  const { createHash } = require('node:crypto')
63
- const { readFileSync, realpathSync } = require('node:fs')
63
+ const { existsSync, readFileSync, realpathSync } = require('node:fs')
64
64
  const { join, resolve, sep } = require('node:path')
65
65
 
66
66
  const CONFIG_FILE = join('specs', '.core', 'env.config.json')
@@ -230,9 +230,11 @@ const DEFAULT_CONFIG = Object.freeze({
230
230
  // follows the merge. `remote` names where the branch is pushed. `draft`
231
231
  // opens mid-spec PRs as drafts (a draft cannot be merged, so nothing
232
232
  // downstream can close a ticket early). `specDocs` decides where a spec
233
- // DOCUMENT lands under "pr": "trunk" keeps today's authoring land (needs
234
- // direct push for docs), "branch" has the spec ride the feature branch and
235
- // land with the work's PR.
233
+ // DOCUMENT lands: "trunk" keeps the authoring land (needs direct push for
234
+ // docs under "pr"), "branch" has the spec ride its feature branch and land
235
+ // with the work. The "trunk" here is only the base's default — with a
236
+ // ticketing provider configured and the key unset, `applyProviderSpecDocs`
237
+ // makes it "branch", whatever the strategy.
236
238
  land: Object.freeze({ strategy: 'ff', remote: 'origin', draft: true, specDocs: 'trunk' }),
237
239
  // `mainIsLandingZone` defaults ON wherever isolation is configured, matching
238
240
  // the review gate's precedent: the push toward not working on the base branch
@@ -307,6 +309,10 @@ const DEFAULT_CONFIG = Object.freeze({
307
309
  allowRemote: false,
308
310
  commitWith: '/commit',
309
311
  required: true,
312
+ // The name every generated page carries in its tab and above its heading.
313
+ // Empty means "the project folder's name" (`projectName` in project.js) —
314
+ // the override exists for a checkout named `app` or `repo`.
315
+ projectName: '',
310
316
  // External code reviewers whose findings render as CHECKS on the page.
311
317
  // Empty by default and never written by `init`: configuring one sends the
312
318
  // worktree's diff to whatever the command talks to, which is a decision
@@ -772,6 +778,8 @@ function mergeConfig(base, parsed) {
772
778
  // here. There is nothing it could mean instead: the hand-off has no off
773
779
  // switch, so a blank value is a typo rather than an instruction.
774
780
  assign(base.review, parsed.review, 'commitWith', 'string')
781
+ // A blank name falls back to the folder's, like `commitWith` above.
782
+ assign(base.review, parsed.review, 'projectName', 'string')
775
783
  // Same shape as `serveOnRemote`, and for a sharper reason: a non-boolean
776
784
  // leaves the gate ON. Turning off a check that refuses must be something
777
785
  // someone WROTE, never something a typo achieved on their behalf.
@@ -873,6 +881,33 @@ function applyProviderEnvDefaults(config, parsed) {
873
881
  return config
874
882
  }
875
883
 
884
+ // The provider's own config file, relative to the project root — set once per
885
+ // process by a provider superset's bin, like the defaults above. A registered
886
+ // file that EXISTS is the positive signal that a ticketing provider is attached
887
+ // to this project, and only then does `land.specDocs` default to "branch": the
888
+ // tracker is the backlog, so landing a spec document on the base branch just to
889
+ // make it findable buys nothing (feat-tracker-spec-branches).
890
+ //
891
+ // WHAT WOULD FOOL THIS: an installed superset whose project never ran its setup
892
+ // has no config file, and reads as no provider — which is the safe reading,
893
+ // since "trunk" is today's behaviour. An unregistered base distribution never
894
+ // asks at all.
895
+ let providerConfigFile = null
896
+ function setProviderConfigFile(rel) {
897
+ providerConfigFile = rel || null
898
+ }
899
+
900
+ // An explicit `specDocs` in the file — any value, even one the merge rejected —
901
+ // is the project's decision; a rejected typo stays on the conservative "trunk"
902
+ // rather than being promoted to the provider default.
903
+ function applyProviderSpecDocs(config, parsed, dir) {
904
+ if (!providerConfigFile) return config
905
+ const pLand = parsed && typeof parsed.land === 'object' && parsed.land !== null ? parsed.land : null
906
+ if (pLand && 'specDocs' in pLand) return config
907
+ if (existsSync(join(dir, providerConfigFile))) config.land.specDocs = 'branch'
908
+ return config
909
+ }
910
+
876
911
  function loadEnvConfig(dir = process.cwd()) {
877
912
  const base = defaults()
878
913
  const file = join(dir, CONFIG_FILE)
@@ -882,7 +917,12 @@ function loadEnvConfig(dir = process.cwd()) {
882
917
  raw = readFileSync(file, 'utf-8')
883
918
  } catch (error) {
884
919
  if (error.code === 'ENOENT') {
885
- return { config: applyProviderEnvDefaults(base, null), present: false, unknown: [], badReviewers: [] }
920
+ return {
921
+ config: applyProviderSpecDocs(applyProviderEnvDefaults(base, null), null, dir),
922
+ present: false,
923
+ unknown: [],
924
+ badReviewers: [],
925
+ }
886
926
  }
887
927
  throw error
888
928
  }
@@ -895,7 +935,7 @@ function loadEnvConfig(dir = process.cwd()) {
895
935
  }
896
936
 
897
937
  return {
898
- config: applyProviderEnvDefaults(mergeConfig(base, parsed), parsed),
938
+ config: applyProviderSpecDocs(applyProviderEnvDefaults(mergeConfig(base, parsed), parsed), parsed, dir),
899
939
  present: true,
900
940
  unknown: collectUnknownKeys(parsed),
901
941
  badReviewers: collectBadReviewers(parsed),
@@ -905,6 +945,7 @@ function loadEnvConfig(dir = process.cwd()) {
905
945
  module.exports = {
906
946
  loadEnvConfig,
907
947
  setProviderEnvDefaults,
948
+ setProviderConfigFile,
908
949
  resolveServePort,
909
950
  derivedServePort,
910
951
  servePortRoot,
package/src/env/epic.js CHANGED
@@ -292,12 +292,21 @@ function layer(members) {
292
292
  * - `index` `indexSpecTree` of the base branch
293
293
  * - `readFile` base-branch path → text, or null
294
294
  * - `candidates` base-branch overview paths that may carry an `Epic:` header
295
+ * - `waitIndex`/`waitRead` where a wait is resolved, when that is not where
296
+ * members are read — `epic status --here` reads members off a
297
+ * working tree and still meets a wait only on the base branch
295
298
  * - `worktrees` `[{ folder, bucket, overview, phases: [{ n, text }] }]` —
296
299
  * each provisioned spec's own copy, which is where an
297
300
  * in-flight spec's bucket and phase progress are true
301
+ * - `branches` the same shape, read off spec branches this machine has no
302
+ * worktree for (`env/specbranches.js`) — how a member that
303
+ * rides its own branch is seen at all. It can make a member
304
+ * VISIBLE and give it a bucket; it never meets a wait, which
305
+ * is still read only off the base branch.
298
306
  */
299
- function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] }) {
307
+ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [], branches = [], waitIndex = index, waitRead = readFile }) {
300
308
  const own = new Map(worktrees.map((w) => [w.folder, w]))
309
+ const onBranch = new Map(branches.filter((b) => !own.has(b.folder)).map((b) => [b.folder, b]))
301
310
  const members = new Map()
302
311
 
303
312
  for (const file of candidates) {
@@ -312,8 +321,10 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
312
321
  members.set(m[2], { spec: m[2], waits: h.waitsOn, area: h.area, phases })
313
322
  }
314
323
  // A member authored on its own branch and not landed yet is invisible on the
315
- // base branch; its worktree copy is what knows it belongs here.
316
- for (const w of worktrees) {
324
+ // base branch; its worktree copy is what knows it belongs here — or, with no
325
+ // worktree on this machine, its branch's copy. The worktree is read last, so
326
+ // it wins.
327
+ for (const w of [...onBranch.values(), ...worktrees]) {
317
328
  const h = epicHeaders(w.overview)
318
329
  // The worktree's copy is the newer word on a spec being built: it may have
319
330
  // joined, changed its waits, or moved to another epic.
@@ -327,15 +338,16 @@ function epicStatus({ epic, index, readFile, candidates = [], worktrees = [] })
327
338
  const base = index.get(m.spec)
328
339
  // In flight is the positive signal of a worktree whose own copy has not
329
340
  // finished; otherwise the base branch's bucket.
330
- m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : base ? base.bucket : wt ? wt.bucket : null
331
- m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, index, readFile) }))
341
+ const br = onBranch.get(m.spec)
342
+ m.bucket = wt && !['complete', 'cancelled'].includes(wt.bucket) ? 'in-progress' : br ? br.bucket : base ? base.bucket : wt ? wt.bucket : null
343
+ m.resolved = m.waits.map((w) => ({ ...w, ...resolveWait(w, waitIndex, waitRead) }))
332
344
  // A phase's own `Waits on:` holds that phase, not the spec's start: the
333
345
  // sync point the field example turned on (#154 phase 2 on #159 phase 1).
334
346
  // A phase already done has nothing left to wait for.
335
347
  m.phaseWaits = m.phases
336
348
  .filter((p) => p.text !== null && !phaseIsDone(p.text))
337
349
  .flatMap((p) =>
338
- epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, index, readFile) } })),
350
+ epicHeaders(p.text).waitsOn.map((w) => ({ at: p.n, wait: { ...w, ...resolveWait(w, waitIndex, waitRead) } })),
339
351
  )
340
352
  }
341
353
 
@@ -403,9 +415,12 @@ function aligned(lines, indent = ' ') {
403
415
  * cannot tell rather than guessing.
404
416
  */
405
417
  function formatEpicStatus(s) {
406
- if (!s.found && !s.members.length) return `no epic named ${s.epic}, and no spec names it as its Epic.\n`
418
+ if (!s.found && !s.members.length) {
419
+ return `no epic named ${s.epic}, and no spec names it as its Epic${s.here ? ` in ${s.here}` : ''}.\n`
420
+ }
407
421
  const lanes = s.lanes === null ? 'no lane cap' : `${s.lanes} lanes, ${s.freeLanes} free`
408
- const head = `${s.epic} — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${s.found ? '' : ' · epic not on the base branch'}`
422
+ const where = s.here ? ` · headers from ${s.here}` : s.found ? '' : ' · epic not on the base branch'
423
+ const head = `${s.epic} — ${s.members.length} member${s.members.length === 1 ? '' : 's'} · ${lanes}${where}`
409
424
  const out = [head, '']
410
425
  if (!s.members.length) {
411
426
  out.push(` no members — no spec carries \`> **Epic:** ${s.epic}\``)
@@ -51,7 +51,7 @@ function syncLine({ spec, phase, wait }) {
51
51
  return `${who} after ${wait.raw} (${mark})`
52
52
  }
53
53
 
54
- function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
54
+ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS, project = null } = {}) {
55
55
  const lanes = answer.lanes === null ? 'no lane cap' : `${answer.lanes} lanes, ${answer.freeLanes} free`
56
56
  const count = `${answer.members.length} member${answer.members.length === 1 ? '' : 's'}`
57
57
  const rows = (answer.rows || [])
@@ -83,7 +83,7 @@ function renderEpicPage(answer, { refreshSeconds = REFRESH_SECONDS } = {}) {
83
83
  <meta charset="utf-8">
84
84
  <meta name="viewport" content="width=device-width, initial-scale=1">
85
85
  <meta http-equiv="refresh" content="${Number(refreshSeconds)}">
86
- <title>${escapeHtml(answer.epic)}</title>
86
+ <title>${project ? `${escapeHtml(project)} · ` : ''}${escapeHtml(answer.epic)}</title>
87
87
  <style>
88
88
  :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --link:#0b5fbd; --hot:#a15c00 }
89
89
  @media (prefers-color-scheme: dark) {
@@ -94,6 +94,7 @@ body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
94
94
  font:15px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif }
95
95
  main { max-width:60rem; margin:0 auto }
96
96
  h1 { font-size:1.1rem; margin:0 0 .25rem; font-weight:600 }
97
+ .eyebrow { color:var(--dim); font-size:.8rem; margin:0 0 .1rem }
97
98
  .sub { color:var(--dim); margin:0 0 1.25rem }
98
99
  .wrap { overflow-x:auto }
99
100
  table { border-collapse:collapse; width:100% }
@@ -113,7 +114,7 @@ dt { color:var(--dim) } dd { margin:0 }
113
114
  </head>
114
115
  <body>
115
116
  <main>
116
- <h1>${escapeHtml(answer.epic)}</h1>
117
+ ${project ? `<p class="eyebrow">${escapeHtml(project)}</p>\n` : ''}<h1>${escapeHtml(answer.epic)}</h1>
117
118
  <p class="sub">${count} · ${escapeHtml(lanes)}</p>
118
119
  <div class="wrap">${table}</div>
119
120
  ${own}
@@ -36,6 +36,44 @@ function epicTree(git, base) {
36
36
  return { index: indexSpecTree(listing), readFile: (p) => git(['show', `${base}:${p}`]), candidates }
37
37
  }
38
38
 
39
+ /**
40
+ * The same shape as `epicTree`, read off a WORKING TREE on disk — uncommitted
41
+ * edits included. It is what `epic status --here` reads members and headers
42
+ * from, so a conversion can be checked in the worktree it is made in before it
43
+ * lands. Waits are still met only on the base branch: that is the caller's
44
+ * `waitIndex`, never this.
45
+ *
46
+ * WHAT WOULD FOOL THIS: a file git would ignore is read like any other. Under
47
+ * `specs/` there is nothing ignored by design, so the cost is a stray editor
48
+ * backup named `*.md`, read as one more phase file.
49
+ */
50
+ function workingTree(root) {
51
+ const files = []
52
+ const walk = (rel) => {
53
+ let entries
54
+ try {
55
+ entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true })
56
+ } catch {
57
+ return
58
+ }
59
+ for (const e of entries) {
60
+ const p = `${rel}/${e.name}`
61
+ if (e.isDirectory()) walk(p)
62
+ else if (e.isFile()) files.push(p)
63
+ }
64
+ }
65
+ walk('specs')
66
+ const readFile = (p) => {
67
+ try {
68
+ return fs.readFileSync(path.join(root, p), 'utf8')
69
+ } catch {
70
+ return null
71
+ }
72
+ }
73
+ const candidates = files.filter((p) => p.endsWith('/00-overview.md') && /^>\s*\*\*Epic:\*\*/m.test(readFile(p) || ''))
74
+ return { index: indexSpecTree(files.join('\n')), readFile, candidates }
75
+ }
76
+
39
77
  // A provisioned spec's own overview and bucket, read in its worktree — the
40
78
  // copy where an in-flight spec's bucket and headers are true. null when the
41
79
  // worktree holds no readable copy.
@@ -106,4 +144,4 @@ function epicAnswer(epic, inputs, readers) {
106
144
  return { ...status, rows, next }
107
145
  }
108
146
 
109
- module.exports = { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
147
+ module.exports = { epicTree, workingTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer }
@@ -243,6 +243,53 @@ function planIntegratePr(spec, config, ctx) {
243
243
  }
244
244
  }
245
245
 
246
+ /**
247
+ * Pure planner for the AUTHORING land of a spec document under
248
+ * `land.specDocs: "branch"` (`spec-env integrate --docs`).
249
+ *
250
+ * The document rides its own branch rather than landing on base, so the plan
251
+ * touches no base at all — no rebase, no fast-forward, no PR. What it does is
252
+ * publish the branch, because a spec on an unpushed branch is on one machine
253
+ * and nowhere else (the ticket's summary block cannot rebuild it). The push is
254
+ * consent-gated with `planIntegratePr`'s shape: already on the remote at HEAD
255
+ * is honoured (`via: "remote"`), `--push` is the recorded yes (`via: "push"`),
256
+ * otherwise it HOLDS (`via: "hold"`) with the push in `holdCommands`.
257
+ *
258
+ * NO REMOTE IS A HOLD, NEVER AN ERROR. A clone with no remote of that name
259
+ * cannot publish, and refusing would accuse a healthy local-only repo; the
260
+ * plan says so (`noRemote`) and the spec stays on its local branch.
261
+ *
262
+ * ctx: { worktreeState: { dirty }, remote, treePath, remoteConfigured,
263
+ * pushedAtHead, push }
264
+ */
265
+ function planIntegrateDocs(spec, config, ctx) {
266
+ const { worktreeState = {}, treePath, remoteConfigured } = ctx || {}
267
+ const remote = (ctx && ctx.remote) || 'origin'
268
+ const branch = spec.branch
269
+ const result = {
270
+ blocked: false, noop: false, reason: null, commands: [],
271
+ push: null, holdCommands: [], noRemote: false,
272
+ afterLand: noAfterLand(), branch, remote,
273
+ }
274
+
275
+ // The verdict's commit ran first, so anything still uncommitted is not this
276
+ // spec's — and a push would publish a branch missing it.
277
+ if (worktreeState.dirty) {
278
+ return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the spec first' }
279
+ }
280
+ if (!remoteConfigured) {
281
+ return { ...result, noRemote: true, push: { kind: 'push', via: 'hold', remote, branch } }
282
+ }
283
+ if (ctx.pushedAtHead) {
284
+ return { ...result, noop: true, push: { kind: 'push', via: 'remote', remote, branch } }
285
+ }
286
+ const pushCommand = `git -C ${shellPath(treePath)} push -u ${remote} ${branch}`
287
+ if (ctx.push) {
288
+ return { ...result, commands: [pushCommand], push: { kind: 'push', via: 'push', remote, branch } }
289
+ }
290
+ return { ...result, push: { kind: 'push', via: 'hold', remote, branch }, holdCommands: [pushCommand] }
291
+ }
292
+
246
293
  // The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
247
294
  // primary checkout, standing on base) once the land commands have succeeded.
248
295
  // A blocked plan carries the empty form — nothing landed, so nothing follows.
@@ -291,4 +338,4 @@ function noAfterLand() {
291
338
  return { cwd: null, commands: [], entries: [], range: null }
292
339
  }
293
340
 
294
- module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, afterLandFor, rangeOf }
341
+ module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs, afterLandFor, rangeOf }
@@ -162,6 +162,23 @@ function attachProject(config, anchor) {
162
162
  return config
163
163
  }
164
164
 
165
+ /**
166
+ * The name a generated page calls this project by: `review.projectName` when
167
+ * set, else the project folder's name in the PRIMARY checkout.
168
+ *
169
+ * NEVER THE CWD'S NAME. A worktree's folder is named after its spec, so a page
170
+ * rendered from one would repeat the spec name where the project's belongs —
171
+ * which is why this reads the anchor `attachProject` recorded. `null` when there
172
+ * is none: cannot tell, and the pages then render exactly as they did before.
173
+ */
174
+ function projectName(config) {
175
+ const set = config && config.review && config.review.projectName
176
+ if (typeof set === 'string' && set.trim()) return set.trim()
177
+ const p = config && config.project
178
+ if (!p || !p.root) return null
179
+ return path.basename(projectIn(p.root, p.prefix || '')) || null
180
+ }
181
+
165
182
  /**
166
183
  * A path as one shell word, for the commands the engine PRINTS for a person or
167
184
  * a skill to run. Quoted only when it has to be, so a path without spaces or
@@ -217,6 +234,7 @@ module.exports = {
217
234
  toPosix,
218
235
  shellPath,
219
236
  attachProject,
237
+ projectName,
220
238
  repoRootOf,
221
239
  prefixOf,
222
240
  projectLine,
package/src/env/review.js CHANGED
@@ -269,7 +269,7 @@ function resolveReader(config, env = {}) {
269
269
  * `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
270
270
  * caller's declaration about the work, not a reading of the gate.
271
271
  */
272
- function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null }) {
272
+ function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null, only = null, treePath = null, live = null, tiers = null, project = null }) {
273
273
  // WHICH TREE THE SPEC'S OWN DOCUMENTS ARE READ FROM. Every render but one
274
274
  // reads the spec's worktree, and for those the two are the same path — so
275
275
  // `treePath` left null keeps the existing behaviour exactly. The `docs` mode
@@ -360,6 +360,9 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
360
360
  return {
361
361
  spec: spec.folder,
362
362
  title: spec.folder,
363
+ // The project's name, for the tab and the line above the heading. Absent
364
+ // when the caller could not tell, and the page then renders as before.
365
+ ...(project ? { project } : {}),
363
366
  branch: spec.branch,
364
367
  // The tree the diff was read from. Identical to the worktree for every
365
368
  // mode but `docs`, where there is no worktree and this is the checkout the
@@ -603,6 +606,10 @@ const ACTIONS = ['live-on', 'allow-network', 'allow-remote']
603
606
  */
604
607
  function tierAction(tier) {
605
608
  if (!tier || !tier.off) return null
609
+ // A loopback bind is off for a reason no press can fix: widening it restarts
610
+ // the server, which mints a new token and kills every link already open. Its
611
+ // command is named on the line; the page offers nothing.
612
+ if (tier.bound === 'loopback') return null
606
613
  if (tier.tier === 'network') return 'allow-network'
607
614
  if (tier.tier === 'remote') return 'allow-remote'
608
615
  return null
@@ -742,6 +749,11 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
742
749
  return isTailnetAddress(host) ? { url: u, label: 'tailnet' } : { url: u }
743
750
  }),
744
751
  })
752
+ } else if (served && served.loopback && served.widen) {
753
+ // Permitted, and the machine has addresses — but the running server is
754
+ // bound to loopback. "No network address" here sent readers looking for a
755
+ // network problem; the fix is one command, so the line names it.
756
+ tiers.push({ tier: 'network', off: true, bound: 'loopback', enable: served.widen })
745
757
  } else {
746
758
  // Permitted, but there is no address to offer — a machine with no network,
747
759
  // or a server that could not take one. Not a problem to report as an error.
@@ -2309,16 +2321,22 @@ function fragmentTemplate(template = null) {
2309
2321
  */
2310
2322
  function renderReviewFragment(data, { template = null, reviewHtml = '' } = {}) {
2311
2323
  const values = {
2312
- [TITLE_PLACEHOLDER]: escapeHtml(data.title),
2324
+ [TITLE_PLACEHOLDER]: escapeHtml(tabTitle(data)),
2313
2325
  [REVIEW_PLACEHOLDER]: reviewHtml,
2314
2326
  [DATA_PLACEHOLDER]: escapeIsland(JSON.stringify(data)),
2315
2327
  }
2316
2328
  return fragmentTemplate(template).replace(PLACEHOLDER_RE, (m) => values[m])
2317
2329
  }
2318
2330
 
2331
+ // The tab name: `<project> · <spec>`, so pages from two projects open side by
2332
+ // side can be told apart from the tab alone — all a phone shows.
2333
+ function tabTitle(data) {
2334
+ return data.project ? `${data.project} · ${data.title}` : data.title
2335
+ }
2336
+
2319
2337
  function renderReviewPage(data, { template = null, reviewHtml = '' } = {}) {
2320
2338
  const values = {
2321
- [TITLE_PLACEHOLDER]: escapeHtml(data.title),
2339
+ [TITLE_PLACEHOLDER]: escapeHtml(tabTitle(data)),
2322
2340
  [REVIEW_PLACEHOLDER]: reviewHtml,
2323
2341
  [DATA_PLACEHOLDER]: escapeIsland(JSON.stringify(data)),
2324
2342
  }
package/src/env/serve.js CHANGED
@@ -38,10 +38,11 @@ const {
38
38
  isEpic,
39
39
  } = require('./resolve.js')
40
40
  const { epicTree, worktreeOverview, epicsInFlight, memberReaders, epicAnswer } = require('./epicread.js')
41
+ const { specBranchDocs } = require('./specbranches.js')
41
42
  const { renderEpicPage } = require('./epicpage.js')
42
43
  const { readRegistry } = require('./registry.js')
43
44
  const { loadEnvConfig } = require('./config.js')
44
- const { primaryAnchor, attachProject, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
45
+ const { primaryAnchor, attachProject, projectName, repoRootOf, prefixOf, fromRepoPath, toRepoPath } = require('./project.js')
45
46
  const { specDocsIn, classifyDirtyTree, dirtyPaths } = require('./classify.js')
46
47
  const { liveStateFor } = require('./live.js')
47
48
  const { preferRemoteBase } = require('./host.js')
@@ -127,8 +128,11 @@ function escapeHtml(s) {
127
128
  * palette on bare `:root`, redefined under `prefers-color-scheme`) so the two
128
129
  * do not disagree when opened side by side.
129
130
  */
130
- function renderIndex(entries, { token = null, epics = [] } = {}) {
131
+ function renderIndex(entries, { token = null, epics = [], project = null } = {}) {
131
132
  const prefix = token ? `/${token}` : ''
133
+ // The heading and tab name the project, so two servers' indexes open side by
134
+ // side can be told apart. No name — cannot tell — reads as it always did.
135
+ const heading = project ? `${escapeHtml(project)} · spec diffs` : 'spec diffs'
132
136
  // Epics with a member in flight, each a doorway to its epic page. Listed
133
137
  // above the diffs because an epic page is where a reader running several
134
138
  // members starts; absent entirely on a repo with no epic in flight.
@@ -161,7 +165,7 @@ function renderIndex(entries, { token = null, epics = [] } = {}) {
161
165
  <head>
162
166
  <meta charset="utf-8">
163
167
  <meta name="viewport" content="width=device-width, initial-scale=1">
164
- <title>spec diffs</title>
168
+ <title>${heading}</title>
165
169
  <style>
166
170
  :root { --bg:#fff; --fg:#1a1a1a; --dim:#6b6b6b; --line:#e3e3e3; --add:#0a7b34; --del:#b3261e; --link:#0b5fbd }
167
171
  @media (prefers-color-scheme: dark) {
@@ -188,7 +192,7 @@ code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace }
188
192
  </head>
189
193
  <body>
190
194
  <main>
191
- <h1>spec diffs</h1>
195
+ <h1>${heading}</h1>
192
196
  ${epicList}
193
197
  ${body}
194
198
  </main>
@@ -561,6 +565,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
561
565
  notes,
562
566
  gate: gateRead.corrupt ? null : gateRead.gate,
563
567
  buttons,
568
+ project: projectName(config),
564
569
  only: view.owned,
565
570
  treePath: view.tree,
566
571
  })
@@ -638,6 +643,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
638
643
  buttons,
639
644
  live,
640
645
  tiers,
646
+ project: projectName(config),
641
647
  })
642
648
 
643
649
  if (!branch && data.totals.files === 0) {
@@ -660,6 +666,7 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
660
666
  buttons,
661
667
  live,
662
668
  tiers,
669
+ project: projectName(config),
663
670
  fellBack: true,
664
671
  })
665
672
  if (wider.totals.files > 0) {
@@ -805,7 +812,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
805
812
  })
806
813
  }
807
814
 
808
- function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null }) {
815
+ function createReviewServer({ resolveEntries, resolveEpics = () => [], render, receive = null, passState = null, token = null, project = null }) {
809
816
  return http.createServer((req, res) => {
810
817
  const send = (code, body, type = 'text/html; charset=utf-8') => {
811
818
  res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
@@ -859,7 +866,7 @@ function createReviewServer({ resolveEntries, resolveEpics = () => [], render, r
859
866
  }
860
867
 
861
868
  try {
862
- if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics() }))
869
+ if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token, epics: resolveEpics(), project }))
863
870
  const out = render(route.spec, { branch: route.branch })
864
871
  if (!out) return send(404, 'not found', 'text/plain; charset=utf-8')
865
872
  if (out.error) return send(409, out.error, 'text/plain; charset=utf-8')
@@ -1027,14 +1034,16 @@ function serverHooks(dir, config) {
1027
1034
  }
1028
1035
  const tree = epicTree(trimmedGit, base)
1029
1036
  if (!tree) return { error: `cannot tell — the base branch ${base} could not be read` }
1030
- const inputs = { dir, config, base, ...tree, worktrees: worktrees() }
1037
+ const inputs = { dir, config, base, ...tree, worktrees: worktrees(), branches: specBranchDocs(trimmedGit, config, base) }
1031
1038
  const answer = epicAnswer(folder, inputs, memberReaders({ ...inputs, git: trimmedGitReader, linkFor: (s) => encodeURIComponent(s) }))
1032
1039
  if (!answer.found && !answer.members.length) return null
1033
- return { html: renderEpicPage(answer) }
1040
+ return { html: renderEpicPage(answer, { project: projectName(config) }) }
1034
1041
  }
1035
1042
 
1036
1043
  return {
1037
1044
  resolveEntries,
1045
+ // What the index calls this project. Read once: the server is per project.
1046
+ project: projectName(config),
1038
1047
  resolveEpics: () => {
1039
1048
  try {
1040
1049
  return epicsInFlight(worktrees())
@@ -0,0 +1,120 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * Specs that live only on their own branch (feat-tracker-spec-branches).
5
+ *
6
+ * Under `land.specDocs: "branch"` — the default once a ticketing provider is
7
+ * configured — a spec document never lands on the base branch until its work
8
+ * does, so `ls specs/backlog/` on base cannot see it. The checks that read the
9
+ * backlog (`gating check`, `epic status`, `docs-freshness check`) ask this
10
+ * instead, so the specs that mode produces are not invisible to them.
11
+ *
12
+ * What a branch is FOR is read off what it changed: the spec folders its range
13
+ * (`<base>...<ref>`) touches. Every spec branch forks from base and so carries
14
+ * every base spec too; only the ones it changed are its own.
15
+ *
16
+ * Read with git and never fetched. An advisory check that can hang on the
17
+ * network is worse than one that is a fetch behind, so remote-tracking refs are
18
+ * read as they stand and a caller labels them "as of last fetch".
19
+ *
20
+ * WHAT WOULD FOOL THIS: a remote that was never fetched (its specs are simply
21
+ * absent — an extra miss, never an accusation), and a spec branch whose name
22
+ * does not match `branch.pattern` (renamed by hand; it is not found). Every
23
+ * unreadable git call reads as nothing found.
24
+ */
25
+
26
+ const { BUCKETS } = require('./resolve.js')
27
+
28
+ const OVERVIEW_RE = /^specs\/([^/]+)\/([^/]+)\/00-overview\.md$/
29
+ const SPEC_PATH_RE = /^specs\/([^/]+)\/([^/]+)\//
30
+
31
+ // `branch.pattern` as a for-each-ref glob: every `{token}` becomes `*`.
32
+ function refGlob(config) {
33
+ const pattern = (config && config.branch && config.branch.pattern) || '{type}/{slug}'
34
+ return pattern.replace(/\{[^}]+\}/g, '*')
35
+ }
36
+
37
+ function lines(out) {
38
+ return String(out || '').split('\n').map((l) => l.trim()).filter(Boolean)
39
+ }
40
+
41
+ /**
42
+ * The spec branches this clone can see: local first, then remote-tracking, as
43
+ * `{ ref, name, local }`. The base branch itself is never a spec branch.
44
+ */
45
+ function specRefs(git, config, base) {
46
+ const glob = refGlob(config)
47
+ const remote = (config && config.land && config.land.remote) || 'origin'
48
+ const local = lines(git(['for-each-ref', '--format=%(refname)', `refs/heads/${glob}`]))
49
+ .map((ref) => ({ ref, name: ref.slice('refs/heads/'.length), local: true }))
50
+ const prefix = `refs/remotes/${remote}/`
51
+ const tracking = lines(git(['for-each-ref', '--format=%(refname)', `${prefix}${glob}`]))
52
+ .map((ref) => ({ ref, name: ref.slice(prefix.length), local: false }))
53
+ return [...local, ...tracking].filter((r) => r.name !== base && r.name !== 'HEAD')
54
+ }
55
+
56
+ /**
57
+ * Every spec folder a spec branch changed, read off that branch:
58
+ * `[{ folder, bucket, ref, local, overview, phases: [{ n, text }] }]`.
59
+ *
60
+ * Precedence (Decision 7): a folder the base branch has FINISHED — in
61
+ * `complete/` or `cancelled/` — is dropped, since the work is done and a
62
+ * lingering branch is history; otherwise a local branch beats a
63
+ * remote-tracking one. Base's own `backlog/` copy losing to a branch copy is
64
+ * the caller's merge, via `preferBranches`.
65
+ */
66
+ function specBranchDocs(git, config, base) {
67
+ if (!base) return []
68
+ const finished = new Set()
69
+ for (const p of lines(git(['ls-tree', '-r', '--name-only', base, '--', 'specs/complete', 'specs/cancelled']))) {
70
+ const m = OVERVIEW_RE.exec(p)
71
+ if (m) finished.add(m[2])
72
+ }
73
+ const found = new Map()
74
+ for (const { ref, local } of specRefs(git, config, base)) {
75
+ const changed = new Set()
76
+ for (const p of lines(git(['diff', '--name-only', `${base}...${ref}`, '--', 'specs']))) {
77
+ const m = SPEC_PATH_RE.exec(p)
78
+ if (m && BUCKETS.includes(m[1])) changed.add(m[2])
79
+ }
80
+ if (!changed.size) continue
81
+ const tree = lines(git(['ls-tree', '-r', '--name-only', ref, '--', 'specs']))
82
+ for (const folder of changed) {
83
+ if (finished.has(folder)) continue
84
+ if (found.has(folder) && (found.get(folder).local || !local)) continue
85
+ const overviewPath = tree.find((p) => {
86
+ const m = OVERVIEW_RE.exec(p)
87
+ return m && m[2] === folder
88
+ })
89
+ if (!overviewPath) continue // the branch deleted it, or moved it out of specs/
90
+ const overview = git(['show', `${ref}:${overviewPath}`])
91
+ if (overview === null) continue
92
+ const bucket = OVERVIEW_RE.exec(overviewPath)[1]
93
+ const dirPrefix = `specs/${bucket}/${folder}/`
94
+ const phases = tree
95
+ .filter((p) => p.startsWith(dirPrefix) && /^\d\d-.+\.md$/.test(p.slice(dirPrefix.length)) && !p.endsWith('/00-overview.md'))
96
+ .map((p) => ({ n: Number(p.slice(dirPrefix.length, dirPrefix.length + 2)), text: git(['show', `${ref}:${p}`]) }))
97
+ found.set(folder, { folder, bucket, ref, local, overview, phases })
98
+ }
99
+ }
100
+ return [...found.values()].sort((a, b) => a.folder.localeCompare(b.folder))
101
+ }
102
+
103
+ /**
104
+ * Merge a disk scan with branch copies: a branch copy replaces the disk entry
105
+ * for the same folder, and adds one where there is none. Both lists carry
106
+ * `folder`; the result keeps the disk entries' order, then the new ones.
107
+ */
108
+ function preferBranches(disk, branches) {
109
+ const byFolder = new Map(branches.map((b) => [b.folder, b]))
110
+ const merged = disk.map((d) => byFolder.get(d.folder) || d)
111
+ const seen = new Set(disk.map((d) => d.folder))
112
+ return [...merged, ...branches.filter((b) => !seen.has(b.folder))]
113
+ }
114
+
115
+ /** The label a branch-sourced row carries. */
116
+ function branchLabel(entry) {
117
+ return entry.local ? `on ${entry.ref.replace(/^refs\/heads\//, '')}` : `on ${entry.ref.replace(/^refs\/remotes\//, '')}, as of last fetch`
118
+ }
119
+
120
+ module.exports = { specBranchDocs, specRefs, preferBranches, branchLabel, refGlob }