pantheon-opencode 1.6.0-beta.8 → 1.6.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.
Files changed (141) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +126 -346
  4. package/README.md +83 -608
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +366 -132
  7. package/commands/pantheon-audit.md +7 -1
  8. package/commands/pantheon-consolidate.md +1 -1
  9. package/commands/pantheon-deepwork.md +14 -3
  10. package/commands/pantheon-focus.md +17 -0
  11. package/commands/pantheon-vision.md +61 -12
  12. package/package.json +19 -11
  13. package/plugin.json +1 -1
  14. package/pyproject.toml +6 -2
  15. package/scripts/_pantheon_paths.py +24 -0
  16. package/scripts/build-agents-md.mjs +368 -69
  17. package/scripts/changelog-merge.mjs +161 -0
  18. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  19. package/scripts/docs-check-changelog.mjs +204 -0
  20. package/scripts/docs-link-check.mjs +314 -0
  21. package/scripts/docs-media.mjs +157 -0
  22. package/scripts/doctor.mjs +828 -40
  23. package/scripts/install/agents-md.mjs +2 -2
  24. package/scripts/install/backup.mjs +648 -0
  25. package/scripts/install/cli-ui.mjs +303 -72
  26. package/scripts/install/component-selection.mjs +61 -0
  27. package/scripts/install/config-migration.mjs +583 -27
  28. package/scripts/install/exit-codes.mjs +26 -0
  29. package/scripts/install/file-inventory.mjs +555 -0
  30. package/scripts/install/health-check.mjs +31 -25
  31. package/scripts/install/interactive.mjs +78 -383
  32. package/scripts/install/migrate.mjs +49 -25
  33. package/scripts/install/model-picker.mjs +218 -250
  34. package/scripts/install/opencode-version.mjs +83 -21
  35. package/scripts/install/opencode.mjs +1465 -180
  36. package/scripts/install/plan-artifact.mjs +517 -0
  37. package/scripts/install/plan.mjs +475 -0
  38. package/scripts/install/plugin.mjs +251 -30
  39. package/scripts/install/prompt-result.mjs +2 -0
  40. package/scripts/install/shared.mjs +256 -99
  41. package/scripts/install/state.mjs +63 -8
  42. package/scripts/install/strings.mjs +60 -4
  43. package/scripts/install/venv.mjs +90 -47
  44. package/scripts/install/verify.mjs +128 -0
  45. package/scripts/install/vision-prompt.mjs +173 -0
  46. package/scripts/install-mcp.mjs +2 -2
  47. package/scripts/manifest-inventory.mjs +49 -3
  48. package/scripts/mcp_persistence.py +1535 -1050
  49. package/scripts/memory_mcp.py +12 -843
  50. package/scripts/node-engine-policy.mjs +85 -0
  51. package/scripts/package-evidence.mjs +10 -2
  52. package/scripts/postinstall.mjs +26 -26
  53. package/scripts/probe-pantheon-cost.mjs +118 -19
  54. package/scripts/prune.mjs +9 -3
  55. package/scripts/reconcile.mjs +325 -0
  56. package/scripts/release-gates.mjs +682 -0
  57. package/scripts/restore.mjs +222 -0
  58. package/scripts/run-node-tests.mjs +24 -8
  59. package/scripts/sync-artifacts.mjs +20 -7
  60. package/scripts/sync-tui.mjs +29 -4
  61. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  62. package/scripts/uninstall.mjs +369 -34
  63. package/scripts/update.mjs +164 -0
  64. package/scripts/validate-node-engine-policy.mjs +13 -0
  65. package/scripts/version-check.mjs +34 -1
  66. package/scripts/versioning.mjs +23 -3
  67. package/scripts/vision-status.mjs +682 -0
  68. package/skills-lock.json +8 -8
  69. package/src/agents/aphrodite.md +13 -10
  70. package/src/agents/apollo.md +4 -5
  71. package/src/agents/athena.md +74 -46
  72. package/src/agents/demeter.md +10 -7
  73. package/src/agents/gaia.md +0 -1
  74. package/src/agents/hephaestus.md +4 -3
  75. package/src/agents/hermes.md +10 -9
  76. package/src/agents/iris.md +6 -1
  77. package/src/agents/mnemosyne.md +14 -15
  78. package/src/agents/nyx.md +4 -4
  79. package/src/agents/prometheus.md +12 -11
  80. package/src/agents/talos.md +6 -0
  81. package/src/agents/zeus.md +84 -56
  82. package/src/instructions/agent-return-format.instructions.md +12 -41
  83. package/src/instructions/memory-protocol.instructions.md +5 -11
  84. package/src/instructions/test-economy.instructions.md +12 -0
  85. package/src/instructions/yagni.instructions.md +6 -15
  86. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  87. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  88. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  89. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  90. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  91. package/src/mcp/_pantheon_paths.py +24 -0
  92. package/src/mcp/mcp_codemap_module.py +86 -18
  93. package/src/mcp/mcp_persistence.py +1535 -1050
  94. package/src/mcp/memory_mcp.py +444 -94
  95. package/src/mcp/pantheon_vision.py +285 -41
  96. package/src/mcp/requirements-mcp.txt +5 -0
  97. package/src/pantheon/context-pruner.ts +541 -0
  98. package/src/pantheon/cost-command.ts +814 -60
  99. package/src/pantheon/goal-loop.ts +11 -8
  100. package/src/pantheon/memory-context.ts +1017 -0
  101. package/src/pantheon/model-agents.ts +19 -0
  102. package/src/pantheon/model-command.ts +218 -56
  103. package/src/pantheon/model-pricing.ts +536 -0
  104. package/src/pantheon/presets.mjs +2 -0
  105. package/src/pantheon/task-result-guard.ts +50 -14
  106. package/src/pantheon/v2-bounded-read.ts +640 -0
  107. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  108. package/src/pantheon/v2-execute-after.ts +135 -24
  109. package/src/pantheon/v2-model-overrides.ts +275 -0
  110. package/src/pantheon/v2-tools.ts +89 -35
  111. package/src/pantheon/v2-unsupported.mjs +2 -3
  112. package/src/pantheon/v2-vision.ts +622 -0
  113. package/src/pantheon/vision-local.ts +531 -0
  114. package/src/pantheon/vision.ts +1160 -115
  115. package/src/plugin-v2.ts +654 -162
  116. package/src/plugin.ts +15 -11
  117. package/src/plugins/tui/dist/tui-v2.d.ts +1036 -0
  118. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -0
  119. package/src/plugins/tui/dist/tui-v2.js +3808 -0
  120. package/src/plugins/tui/dist/tui-v2.js.map +1 -0
  121. package/src/plugins/tui/dist/tui.js +4 -4
  122. package/src/plugins/tui/index-v2.ts +6 -0
  123. package/src/plugins/tui/package-lock.json +5416 -1297
  124. package/src/plugins/tui/package.json +14 -10
  125. package/src/plugins/tui/src/index-v2.tsx +4372 -0
  126. package/src/plugins/tui/src/index.tsx +3 -3
  127. package/src/plugins/tui/src/opencode-v2.d.ts +13 -0
  128. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  129. package/src/plugins/tui/tsdown.config.ts +2 -2
  130. package/src/plugins/tui/tui-v2.ts +2 -0
  131. package/src/plugins/tui/tui.ts +3 -0
  132. package/src/routing.yml +50 -5
  133. package/src/skills/agent-coordination/SKILL.md +7 -2
  134. package/src/skills/artifact-management/SKILL.md +5 -1
  135. package/src/skills/auto-continue/SKILL.md +14 -6
  136. package/src/skills/codemap/SKILL.md +1 -1
  137. package/src/skills/memory-bank/SKILL.md +21 -13
  138. package/src/skills/session-goal/SKILL.md +14 -15
  139. package/src/skills/spec-driven-development/SKILL.md +3 -1
  140. package/src/skills/worktrees/SKILL.md +30 -11
  141. package/scripts/probe-context-rehydrate.mjs +0 -263
@@ -1,19 +1,16 @@
1
+ import { basename, dirname, join, resolve } from 'node:path'
2
+ import { spinner as clackSpinner } from '@clack/prompts'
1
3
  import { strings } from './strings.mjs'
2
4
 
3
5
  export const icons = {
4
- success: '\u2705',
5
- warning: '\u26a0\ufe0f ',
6
- error: '\u274c',
7
- info: '\u2139\ufe0f ',
8
- progress: '\u23f3',
9
- done: '\u2705',
10
- arrow: '\u2192',
11
- bullet: '\u2022',
12
- star: '\u2b50',
13
- wrench: '\u{1F527}',
14
- rocket: '\u{1F680}',
15
- package: '\u{1F4E6}',
16
- gear: '\u2699\ufe0f',
6
+ success: '[OK]',
7
+ warning: '[WARN]',
8
+ error: '[ERROR]',
9
+ info: '[INFO]',
10
+ progress: '[RUNNING]',
11
+ done: '[DONE]',
12
+ bullet: '*',
13
+ rocket: '[OK]',
17
14
  }
18
15
 
19
16
  export const colors = {
@@ -27,13 +24,32 @@ export const colors = {
27
24
 
28
25
  let _quiet = false
29
26
  let _dryRun = false
27
+ // Step-by-step detail (section/step/info/bullet/success) is ON by default so
28
+ // every pre-existing caller (doctor, migrate, direct setupRuntimePhase calls)
29
+ // keeps its output. `init` opts OUT in favor of the gauge, unless --verbose.
30
+ let _verbose = true
30
31
 
32
+ /**
33
+ * Update the UI channel state and return the PREVIOUS state so a caller can
34
+ * restore it (the installer flips verbose off for the duration of one run).
35
+ *
36
+ * @param {{ quiet?: boolean, dryRun?: boolean, verbose?: boolean }} [opts]
37
+ * @returns {{ quiet: boolean, dryRun: boolean, verbose: boolean }}
38
+ */
31
39
  export function configure(opts = {}) {
40
+ const previous = { quiet: _quiet, dryRun: _dryRun, verbose: _verbose }
32
41
  if (opts.quiet !== undefined) _quiet = opts.quiet
33
42
  if (opts.dryRun !== undefined) _dryRun = opts.dryRun
43
+ if (opts.verbose !== undefined) _verbose = opts.verbose
44
+ return previous
34
45
  }
35
46
 
36
- function tag(msg) {
47
+ /**
48
+ * Prefix a message with the `[DRY-RUN]` marker while a dry run is configured.
49
+ * Exported so callers that print through raw `console.log` (e.g. the per-file
50
+ * change plan) stay consistent with every other dry-run line.
51
+ */
52
+ export function tag(msg) {
37
53
  return _dryRun ? `[DRY-RUN] ${msg}` : msg
38
54
  }
39
55
 
@@ -42,48 +58,87 @@ function tty() {
42
58
  }
43
59
 
44
60
  export function section(title) {
45
- if (_quiet) return
61
+ if (_quiet || !_verbose) return
46
62
  const width = Math.min(process.stdout.columns || 60, 72)
47
63
  const text = `\u2500\u2500 ${title} `
48
64
  const line = text + '\u2500'.repeat(Math.max(0, width - text.length + 1))
49
- console.log(tag(line))
65
+ console.log(line)
50
66
  }
51
67
 
52
- export function step(message) {
53
- const text = tag(`${icons.progress} ${message}...`)
54
- if (!_quiet) process.stdout.write(text)
55
- return (ok = true) => {
56
- const icon = ok ? icons.success : icons.error
57
- const doneText = tag(`${icon} ${message}`)
58
- if (_quiet && !ok) {
59
- console.warn(doneText)
60
- } else if (!_quiet) {
61
- process.stdout.write(`\r${doneText}\n`)
68
+ function progress(message) {
69
+ const startedAt = Date.now()
70
+ const elapsed = () => `${((Date.now() - startedAt) / 1000).toFixed(1)}s`
71
+
72
+ // The gauge owns the terminal while it is active: per-step lines would fight
73
+ // with the single rewritten line. A FAILED step still surfaces as a warning
74
+ // (silently dropping a failure would be dishonest), exactly like quiet mode.
75
+ if (!_verbose) {
76
+ return (ok = true) => {
77
+ if (!ok) {
78
+ console.warn(`${icons.error} ${message} — failed in ${elapsed()}`)
79
+ }
80
+ }
81
+ }
82
+
83
+ if (tty() && !_quiet) {
84
+ const indicator = clackSpinner()
85
+ indicator.start(message)
86
+ return (ok = true) => {
87
+ const doneText = `${message} — ${ok ? 'complete' : 'failed'} in ${elapsed()}`
88
+ if (ok) indicator.stop(doneText)
89
+ else indicator.error(doneText)
62
90
  }
63
91
  }
92
+
93
+ if (!_quiet) console.log(`${icons.progress} ${message}`)
94
+ return (ok = true) => {
95
+ const doneText = `${ok ? icons.done : icons.error} ${message} — ${ok ? 'complete' : 'failed'} in ${elapsed()}`
96
+ if (_quiet && !ok) console.warn(doneText)
97
+ else if (!_quiet) console.log(doneText)
98
+ }
99
+ }
100
+
101
+ export function step(message) {
102
+ return progress(message)
64
103
  }
65
104
 
66
105
  export function success(message) {
67
- console.log(tag(`${icons.success} ${message}`))
106
+ if (_quiet || !_verbose) return
107
+ console.log(`${icons.success} ${message}`)
68
108
  }
69
109
 
70
110
  export function warning(message) {
71
- console.warn(tag(`${icons.warning}${message}`))
111
+ if (_quiet) return
112
+ endGaugeLine()
113
+ console.warn(tag(`${icons.warning} ${message}`))
72
114
  }
73
115
 
74
116
  export function error(message) {
117
+ if (_quiet) return
118
+ endGaugeLine()
75
119
  console.error(tag(`${icons.error} ${message}`))
76
120
  }
77
121
 
78
122
  export function info(message) {
123
+ if (_quiet || !_verbose) return
124
+ console.log(`${icons.info} ${message}`)
125
+ }
126
+
127
+ /**
128
+ * A message that must survive the gauge (gate outcomes: declined, plan-only,
129
+ * canceled). It is suppressed only by `--quiet`/JSON, never by the progress
130
+ * mode: losing "re-run with --yes" would leave the user with a dead end.
131
+ */
132
+ export function notice(message) {
79
133
  if (_quiet) return
80
- console.log(tag(`${icons.info}${message}`))
134
+ endGaugeLine()
135
+ console.log(`${icons.info} ${message}`)
81
136
  }
82
137
 
83
138
  export function bullet(text, indent = 0) {
84
- if (_quiet) return
139
+ if (_quiet || !_verbose) return
85
140
  const pad = ' '.repeat(indent)
86
- console.log(tag(`${pad}${icons.bullet} ${text}`))
141
+ console.log(`${pad}${icons.bullet} ${text}`)
87
142
  }
88
143
 
89
144
  export function summaryTable(items) {
@@ -112,55 +167,159 @@ export function summaryTable(items) {
112
167
  }
113
168
 
114
169
  export function spinner(message) {
115
- const frames = [
116
- '\u280b',
117
- '\u2819',
118
- '\u2839',
119
- '\u2838',
120
- '\u283c',
121
- '\u2834',
122
- '\u2826',
123
- '\u2827',
124
- '\u2807',
125
- '\u280f',
126
- ]
127
- let i = 0
128
- let running = true
170
+ return progress(message)
171
+ }
129
172
 
130
- if (tty() && !_quiet) {
131
- const interval = setInterval(() => {
132
- if (!running) {
133
- clearInterval(interval)
173
+ const GAUGE_BAR_WIDTH = 10
174
+
175
+ // A TTY gauge owns the current line (no trailing newline). Any regular output
176
+ // must terminate that line first or it would be appended to the gauge text.
177
+ let _gaugeLineOpen = false
178
+
179
+ /** Close an in-flight TTY gauge line so normal output starts on its own line. */
180
+ export function endGaugeLine() {
181
+ if (!_gaugeLineOpen) return
182
+ process.stdout.write('\n')
183
+ _gaugeLineOpen = false
184
+ }
185
+
186
+ /** Render the progress bar, with a half block for the fractional cell. */
187
+ function gaugeBar(ratio, width = GAUGE_BAR_WIDTH) {
188
+ const clamped = Math.min(1, Math.max(0, Number.isFinite(ratio) ? ratio : 0))
189
+ const exact = clamped * width
190
+ const full = Math.floor(exact)
191
+ const half = exact - full >= 0.5 && full < width
192
+ const empty = Math.max(0, width - full - (half ? 1 : 0))
193
+ return '\u2588'.repeat(full) + (half ? '\u258c' : '') + '\u2591'.repeat(empty)
194
+ }
195
+
196
+ /**
197
+ * Build one gauge line: `[████████░░] 80% 12/15 Installing TUI dependencies`.
198
+ * The label is truncated to the terminal width so the gauge can never wrap.
199
+ */
200
+ function gaugeText({ current, total, label, columns }) {
201
+ const ratio = total > 0 ? current / total : 1
202
+ const percent = Math.min(100, Math.round(ratio * 100))
203
+ const prefix = `[${gaugeBar(ratio)}] ${percent}% ${current}/${total}`
204
+ const available = Math.max(0, (columns || 80) - prefix.length - 2)
205
+ const text =
206
+ label.length > available ? `${label.slice(0, Math.max(0, available - 1))}\u2026` : label
207
+ return text ? `${prefix} ${text}` : prefix
208
+ }
209
+
210
+ /**
211
+ * Progress gauge for the installer: ONE line of output per phase, never one
212
+ * line per file.
213
+ *
214
+ * * TTY — a single line rewritten in place with `\r` + clear, so the user
215
+ * sees motion instead of a log. `done()` leaves `✔ 15/15 em 41.2s`.
216
+ * * non-TTY/CI — one line per COMPLETED phase:
217
+ * `[12/15] Installing TUI dependencies — 13.0s`. It deliberately adds no
218
+ * separate `done()` line so the log size stays proportional to the number
219
+ * of phases (the final `✔` line is a TTY affordance).
220
+ *
221
+ * `_quiet` (JSON output, doctor's internal preview) makes the gauge silent:
222
+ * nothing it writes may contaminate a structured stream.
223
+ *
224
+ * @param {{ total: number, label?: string }} options
225
+ * @returns {{
226
+ * total: number,
227
+ * readonly current: number,
228
+ * readonly finished: boolean,
229
+ * advance: (n?: number, label?: string) => void,
230
+ * done: () => void,
231
+ * fail: (message: string) => void,
232
+ * cancel: () => void,
233
+ * }}
234
+ */
235
+ export function gauge({ total: rawTotal, label: initialLabel = '' } = {}) {
236
+ const total = Math.max(0, Math.trunc(Number(rawTotal) || 0))
237
+ const startedAt = Date.now()
238
+ const interactive = Boolean(process.stdout.isTTY)
239
+ const silent = _quiet
240
+
241
+ let current = 0
242
+ let label = initialLabel
243
+ let phaseStartedAt = startedAt
244
+ let rendered = false
245
+ let finished = false
246
+
247
+ const seconds = (from) => ((Date.now() - from) / 1000).toFixed(1)
248
+ const write = (text) => process.stdout.write(text)
249
+
250
+ const render = () => {
251
+ write(
252
+ `\r\x1b[2K${gaugeText({
253
+ current,
254
+ total,
255
+ label,
256
+ columns: process.stdout.columns,
257
+ })}`,
258
+ )
259
+ rendered = true
260
+ _gaugeLineOpen = true
261
+ }
262
+
263
+ return {
264
+ total,
265
+ get current() {
266
+ return current
267
+ },
268
+ get finished() {
269
+ return finished
270
+ },
271
+ advance(n = 1, nextLabel) {
272
+ if (finished) return
273
+ const steps = Math.max(1, Math.trunc(Number(n) || 1))
274
+ if (typeof nextLabel === 'string' && nextLabel.length > 0) label = nextLabel
275
+ if (interactive) {
276
+ current = Math.min(total, current + steps)
277
+ phaseStartedAt = Date.now()
278
+ if (!silent) render()
134
279
  return
135
280
  }
136
- process.stdout.write(`\r${frames[i % frames.length]} ${tag(message)}...`)
137
- i++
138
- }, 80)
139
- process.stdout.write(`\r${frames[0]} ${tag(message)}...`)
140
-
141
- return (ok = true) => {
142
- running = false
143
- clearInterval(interval)
144
- const icon = ok ? icons.success : icons.error
145
- process.stdout.write(`\r${icon} ${tag(message)}\n`)
146
- }
147
- } else {
148
- const text = tag(`${icons.progress} ${message}...`)
149
- if (!_quiet) process.stdout.write(text)
150
- return (ok = true) => {
151
- const icon = ok ? icons.success : icons.error
152
- const doneText = tag(`${icon} ${message}`)
153
- if (_quiet && !ok) {
154
- console.warn(doneText)
155
- } else if (!_quiet) {
156
- process.stdout.write(`\r${doneText}\n`)
281
+ // non-TTY: one line per completed phase, each with its own duration.
282
+ for (let index = 0; index < steps; index += 1) {
283
+ current = Math.min(total, current + 1)
284
+ const phaseSeconds = seconds(phaseStartedAt)
285
+ phaseStartedAt = Date.now()
286
+ if (!silent) write(`[${current}/${total}] ${label} — ${phaseSeconds}s\n`)
157
287
  }
158
- }
288
+ },
289
+ done() {
290
+ if (finished) return
291
+ finished = true
292
+ if (silent || !interactive) return
293
+ write(`\r\x1b[2K\u2714 ${total}/${total} em ${seconds(startedAt)}s\n`)
294
+ _gaugeLineOpen = false
295
+ },
296
+ fail(message) {
297
+ if (finished) return
298
+ finished = true
299
+ if (silent) return
300
+ const reason = String(message ?? 'failed')
301
+ const suffix = label ? ` ${label} — ${reason}` : ` — ${reason}`
302
+ if (interactive) {
303
+ write(`\r\x1b[2K\u2716 ${current}/${total}${suffix}\n`)
304
+ _gaugeLineOpen = false
305
+ } else {
306
+ write(`\u2716 ${current}/${total}${suffix}\n`)
307
+ }
308
+ },
309
+ cancel() {
310
+ if (finished) return
311
+ finished = true
312
+ if (!silent && interactive && rendered) {
313
+ write('\r\x1b[2K')
314
+ _gaugeLineOpen = false
315
+ }
316
+ },
159
317
  }
160
318
  }
161
319
 
162
320
  export function printSummary(target, _platforms, stats) {
163
321
  if (_quiet) return
322
+ endGaugeLine()
164
323
 
165
324
  const S = strings()
166
325
  const line = '\u2500'.repeat(Math.min(process.stdout.columns || 60, 60))
@@ -186,8 +345,80 @@ export function printSummary(target, _platforms, stats) {
186
345
  console.log('')
187
346
  }
188
347
 
189
- console.log(tag(` ${icons.star} ${S.summaryNext.trim()}`))
348
+ console.log(tag(` ${S.summaryNext.trim()}`))
190
349
  console.log(tag(S.summaryNextAgents))
191
350
  console.log(tag(S.summaryNextMcp))
192
351
  console.log(tag(S.summaryNextDoctor))
193
352
  }
353
+
354
+ /**
355
+ * Build a persistent worktree location outside the project directory.
356
+ *
357
+ * @param {string} projectRoot - Project directory whose exact basename, including spaces, is retained.
358
+ * @returns {{ pattern: string, example: string }} Recommended paths for future worktrees.
359
+ */
360
+ export function getWorktreeRecommendation(projectRoot = process.cwd()) {
361
+ const resolvedProject = resolve(projectRoot)
362
+ const projectName = basename(resolvedProject)
363
+ const repositoryWorktreeRoot = resolve(
364
+ dirname(resolvedProject),
365
+ '.pantheon-worktrees',
366
+ projectName || 'project',
367
+ )
368
+
369
+ return {
370
+ pattern: join(repositoryWorktreeRoot, '<task>'),
371
+ example: join(repositoryWorktreeRoot, 'feature-name'),
372
+ }
373
+ }
374
+
375
+ /**
376
+ * Show the suggested external worktree location in a real interactive TTY setup.
377
+ * Pantheon provides guidance only; it never creates a worktree or its directory.
378
+ *
379
+ * @param {object} [options]
380
+ * @param {string} [options.projectRoot=process.cwd()] - Project path for the recommendation.
381
+ * @param {boolean} [options.interactive=false] - Whether setup is interactive.
382
+ * @param {boolean} [options.dryRun=false] - Whether setup is preview-only.
383
+ * @returns {void}
384
+ */
385
+ export function printWorktreeGuidance({
386
+ projectRoot = process.cwd(),
387
+ interactive = false,
388
+ dryRun = false,
389
+ } = {}) {
390
+ if (!interactive || dryRun || !tty()) return
391
+
392
+ const recommendation = getWorktreeRecommendation(projectRoot)
393
+ const rows = [
394
+ { label: 'Default: ', value: recommendation.pattern, color: colors.green },
395
+ { label: 'Example: ', value: recommendation.example, color: colors.cyan },
396
+ {
397
+ label: 'Use: ',
398
+ value:
399
+ 'Persistent location; preserve the exact project directory basename, including spaces.',
400
+ color: colors.dim,
401
+ },
402
+ {
403
+ label: 'Note: ',
404
+ value: 'Pantheon does not create Git worktrees or directories automatically.',
405
+ color: colors.yellow,
406
+ },
407
+ ]
408
+ const contentWidth = Math.max(
409
+ 'Worktrees'.length,
410
+ ...rows.map(({ label, value }) => label.length + value.length),
411
+ )
412
+ const border = colors.cyan
413
+
414
+ console.log('')
415
+ console.log(` ${border(`┌${'─'.repeat(contentWidth + 2)}┐`)}`)
416
+ console.log(` ${border('│')} ${colors.bold('Worktrees'.padEnd(contentWidth))} ${border('│')}`)
417
+ console.log(` ${border(`├${'─'.repeat(contentWidth + 2)}┤`)}`)
418
+ for (const { label, value, color } of rows) {
419
+ const padding = ' '.repeat(contentWidth - label.length - value.length)
420
+ console.log(` ${border('│')} ${colors.bold(label)}${color(value)}${padding} ${border('│')}`)
421
+ }
422
+ console.log(` ${border(`└${'─'.repeat(contentWidth + 2)}┘`)}`)
423
+ console.log('')
424
+ }
@@ -0,0 +1,61 @@
1
+ const DEFAULT_INSTALL_COMPONENTS = ['agents', 'skills', 'instructions', 'commands', 'plugins']
2
+ const KNOWN_COMPONENTS = ['agents', 'skills', 'instructions', 'commands', 'plugins', 'runtime']
3
+
4
+ /**
5
+ * Resolve CLI component flags without widening an explicit component selection.
6
+ *
7
+ * @param {string[]} args CLI arguments
8
+ * @param {{ reviewedComponents?: string[] | null }} [options]
9
+ * @returns {{ components: string[], requestedComponentsForPrompt: string[] | null }}
10
+ */
11
+ export function resolveComponentSelection(args, { reviewedComponents = null } = {}) {
12
+ const noMcp = args.includes('--no-mcp')
13
+ if (reviewedComponents !== null) {
14
+ return {
15
+ components: [...reviewedComponents],
16
+ requestedComponentsForPrompt: null,
17
+ noMcp,
18
+ }
19
+ }
20
+
21
+ const componentsIndex = args.indexOf('--components')
22
+ const inlineComponents = args.find((arg) => arg.startsWith('--components='))
23
+ const componentsOpt =
24
+ componentsIndex >= 0
25
+ ? (args[componentsIndex + 1] ?? null)
26
+ : (inlineComponents?.split('=', 2)[1] ?? null)
27
+
28
+ let explicitComponents = null
29
+ if (componentsOpt !== null) {
30
+ explicitComponents = componentsOpt
31
+ .split(',')
32
+ .map((component) => component.trim())
33
+ .filter(Boolean)
34
+ const unknown = explicitComponents.filter((component) => !KNOWN_COMPONENTS.includes(component))
35
+ if (explicitComponents.length === 0 || unknown.length > 0) {
36
+ throw new Error(
37
+ `Invalid --components "${componentsOpt}" — expected comma-separated names from: ${KNOWN_COMPONENTS.join(', ')}`,
38
+ )
39
+ }
40
+ }
41
+
42
+ const components = explicitComponents ? [...explicitComponents] : [...DEFAULT_INSTALL_COMPONENTS]
43
+ if (noMcp) {
44
+ return {
45
+ components: components.filter((component) => component !== 'runtime'),
46
+ requestedComponentsForPrompt: explicitComponents
47
+ ? explicitComponents.filter((component) => component !== 'runtime')
48
+ : null,
49
+ noMcp,
50
+ }
51
+ }
52
+
53
+ // Runtime is a default only for an unscoped install. Explicit --components
54
+ // remains the user's exact scope; runtime can still be requested by name.
55
+ if (explicitComponents === null && !components.includes('runtime')) components.push('runtime')
56
+ return {
57
+ components,
58
+ requestedComponentsForPrompt: explicitComponents ? [...explicitComponents] : null,
59
+ noMcp,
60
+ }
61
+ }