pantheon-opencode 1.6.0-beta.9 → 1.6.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.
Files changed (140) hide show
  1. package/AGENTS.global.md +118 -0
  2. package/AGENTS.md +18 -168
  3. package/CHANGELOG.md +144 -365
  4. package/README.md +124 -607
  5. package/README.pt-BR.md +120 -345
  6. package/bin/pantheon-init.mjs +504 -141
  7. package/commands/pantheon-deepwork.md +14 -3
  8. package/commands/pantheon-vision.md +61 -12
  9. package/package.json +22 -13
  10. package/plugin.json +1 -1
  11. package/pyproject.toml +6 -2
  12. package/scripts/_pantheon_paths.py +24 -0
  13. package/scripts/build-agents-md.mjs +368 -69
  14. package/scripts/changelog-merge.mjs +161 -0
  15. package/scripts/check-plugin-v2-coverage.mjs +11 -8
  16. package/scripts/docs-check-changelog.mjs +204 -0
  17. package/scripts/docs-link-check.mjs +314 -0
  18. package/scripts/docs-media.mjs +157 -0
  19. package/scripts/doctor.mjs +850 -45
  20. package/scripts/install/agents-md.mjs +2 -2
  21. package/scripts/install/backup.mjs +648 -0
  22. package/scripts/install/cli-ui.mjs +303 -72
  23. package/scripts/install/component-selection.mjs +61 -0
  24. package/scripts/install/config-migration.mjs +583 -27
  25. package/scripts/install/exit-codes.mjs +26 -0
  26. package/scripts/install/file-inventory.mjs +555 -0
  27. package/scripts/install/health-check.mjs +31 -25
  28. package/scripts/install/interactive.mjs +99 -383
  29. package/scripts/install/interrupt.mjs +78 -0
  30. package/scripts/install/migrate.mjs +49 -25
  31. package/scripts/install/model-picker.mjs +218 -250
  32. package/scripts/install/opencode-state.mjs +91 -0
  33. package/scripts/install/opencode-version.mjs +83 -21
  34. package/scripts/install/opencode.mjs +1675 -187
  35. package/scripts/install/plan-artifact.mjs +517 -0
  36. package/scripts/install/plan.mjs +475 -0
  37. package/scripts/install/plugin.mjs +214 -27
  38. package/scripts/install/prompt-result.mjs +2 -0
  39. package/scripts/install/run-record.mjs +115 -0
  40. package/scripts/install/shared.mjs +256 -99
  41. package/scripts/install/state.mjs +63 -8
  42. package/scripts/install/strings.mjs +93 -8
  43. package/scripts/install/v2-capabilities.mjs +205 -0
  44. package/scripts/install/venv.mjs +90 -47
  45. package/scripts/install/verify.mjs +128 -0
  46. package/scripts/install/vision-prompt.mjs +173 -0
  47. package/scripts/install-mcp.mjs +2 -2
  48. package/scripts/manifest-inventory.mjs +49 -3
  49. package/scripts/mcp_persistence.py +1535 -1050
  50. package/scripts/memory_mcp.py +12 -843
  51. package/scripts/node-engine-policy.mjs +85 -0
  52. package/scripts/package-evidence.mjs +10 -2
  53. package/scripts/postinstall.mjs +26 -26
  54. package/scripts/probe-pantheon-cost.mjs +118 -19
  55. package/scripts/prune.mjs +9 -3
  56. package/scripts/reconcile.mjs +325 -0
  57. package/scripts/release-gates.mjs +687 -0
  58. package/scripts/restore.mjs +222 -0
  59. package/scripts/run-node-tests.mjs +24 -8
  60. package/scripts/sync-artifacts.mjs +19 -7
  61. package/scripts/sync-tui.mjs +5 -1
  62. package/scripts/test-opencode-v2-sandbox.sh +36 -123
  63. package/scripts/uninstall.mjs +369 -34
  64. package/scripts/update.mjs +164 -0
  65. package/scripts/validate-node-engine-policy.mjs +13 -0
  66. package/scripts/version-check.mjs +34 -1
  67. package/scripts/versioning.mjs +23 -3
  68. package/scripts/vision-status.mjs +682 -0
  69. package/skills-lock.json +8 -8
  70. package/src/agents/aphrodite.md +13 -10
  71. package/src/agents/apollo.md +4 -5
  72. package/src/agents/athena.md +74 -46
  73. package/src/agents/demeter.md +10 -7
  74. package/src/agents/gaia.md +0 -1
  75. package/src/agents/hephaestus.md +4 -3
  76. package/src/agents/hermes.md +10 -9
  77. package/src/agents/iris.md +6 -1
  78. package/src/agents/mnemosyne.md +10 -4
  79. package/src/agents/nyx.md +4 -4
  80. package/src/agents/prometheus.md +12 -11
  81. package/src/agents/talos.md +6 -0
  82. package/src/agents/zeus.md +84 -56
  83. package/src/instructions/agent-return-format.instructions.md +12 -41
  84. package/src/instructions/memory-protocol.instructions.md +5 -11
  85. package/src/instructions/test-economy.instructions.md +12 -0
  86. package/src/instructions/yagni.instructions.md +6 -15
  87. package/src/instructions/zeus-anti-stall.instructions.md +6 -6
  88. package/src/instructions/zeus-communication-rules.instructions.md +6 -6
  89. package/src/instructions/zeus-council-synthesis.instructions.md +11 -12
  90. package/src/instructions/zeus-memory-operations.instructions.md +13 -7
  91. package/src/instructions/zeus-timeout-retry.instructions.md +36 -10
  92. package/src/mcp/_pantheon_paths.py +24 -0
  93. package/src/mcp/mcp_codemap_module.py +86 -18
  94. package/src/mcp/mcp_persistence.py +1535 -1050
  95. package/src/mcp/memory_mcp.py +444 -94
  96. package/src/mcp/pantheon_vision.py +285 -41
  97. package/src/mcp/requirements-mcp.txt +6 -1
  98. package/src/mcp/requirements-vision.txt +1 -1
  99. package/src/pantheon/context-pruner.ts +541 -0
  100. package/src/pantheon/cost-command.ts +901 -60
  101. package/src/pantheon/delegation-enforce.ts +160 -23
  102. package/src/pantheon/goal-loop.ts +11 -8
  103. package/src/pantheon/guard-path.ts +162 -0
  104. package/src/pantheon/memory-context.ts +1017 -0
  105. package/src/pantheon/model-agents.ts +19 -0
  106. package/src/pantheon/model-command.ts +218 -56
  107. package/src/pantheon/model-pricing.ts +536 -0
  108. package/src/pantheon/presets.mjs +2 -0
  109. package/src/pantheon/task-result-guard.ts +50 -14
  110. package/src/pantheon/v2-bounded-read.ts +654 -0
  111. package/src/pantheon/v2-bridge.ts +27 -0
  112. package/src/pantheon/v2-delegation-enforce.ts +133 -6
  113. package/src/pantheon/v2-execute-after.ts +135 -24
  114. package/src/pantheon/v2-model-overrides.ts +275 -0
  115. package/src/pantheon/v2-shell-hooks.ts +260 -0
  116. package/src/pantheon/v2-tools.ts +89 -35
  117. package/src/pantheon/v2-unsupported.mjs +34 -7
  118. package/src/pantheon/v2-vision.ts +622 -0
  119. package/src/pantheon/vision-local.ts +531 -0
  120. package/src/pantheon/vision.ts +1166 -116
  121. package/src/plugin-v2.ts +1039 -171
  122. package/src/plugin.ts +37 -13
  123. package/src/plugins/tui/dist/tui-v2.d.ts +1029 -2
  124. package/src/plugins/tui/dist/tui-v2.d.ts.map +1 -1
  125. package/src/plugins/tui/dist/tui-v2.js +3742 -85
  126. package/src/plugins/tui/dist/tui.js +1 -1
  127. package/src/plugins/tui/package-lock.json +15 -15
  128. package/src/plugins/tui/package.json +7 -5
  129. package/src/plugins/tui/src/index-v2.tsx +4314 -50
  130. package/src/plugins/tui/tsconfig.typecheck.json +5 -0
  131. package/src/routing.yml +50 -5
  132. package/src/skills/agent-coordination/SKILL.md +7 -2
  133. package/src/skills/artifact-management/SKILL.md +5 -1
  134. package/src/skills/auto-continue/SKILL.md +14 -6
  135. package/src/skills/codemap/SKILL.md +1 -1
  136. package/src/skills/memory-bank/SKILL.md +21 -13
  137. package/src/skills/session-goal/SKILL.md +12 -22
  138. package/src/skills/spec-driven-development/SKILL.md +3 -1
  139. package/src/skills/worktrees/SKILL.md +30 -11
  140. package/scripts/probe-context-rehydrate.mjs +0 -263
@@ -0,0 +1,314 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Documentation link checker.
4
+ *
5
+ * Scans README.md and docs/**\/*.md and validates every Markdown link and
6
+ * image:
7
+ * - relative targets exist;
8
+ * - links inside docs/ stay inside docs/ (a link that leaves docs/ would 404
9
+ * on the published site; use an absolute GitHub URL instead);
10
+ * - `#anchors` match a heading slug in the target Markdown file;
11
+ * - reference-style links resolve through their `[ref]: target` definition;
12
+ * - image targets exist;
13
+ * - external URLs, mail links, and bare anchors are ignored.
14
+ *
15
+ * Exits 1 when any finding is reported, or when zero files were scanned.
16
+ */
17
+
18
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
19
+ import { dirname, extname, join, relative, resolve, sep } from 'node:path'
20
+ import { fileURLToPath, pathToFileURL } from 'node:url'
21
+
22
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
23
+ const ROOT = resolve(SCRIPT_DIR, '..')
24
+ const DOCS_ROOT = join(ROOT, 'docs')
25
+ const README = join(ROOT, 'README.md')
26
+
27
+ const INLINE_LINK = /(?<!!)\[([^\]]*)\]\(([^)]+)\)/g
28
+ const INLINE_IMAGE = /!\[([^\]]*)\]\(([^)]+)\)/g
29
+ const REFERENCE_LINK = /(?<!!)\[([^\]]*)\]\[([^\]]*)\]/g
30
+ const REFERENCE_IMAGE = /!\[([^\]]*)\]\[([^\]]*)\]/g
31
+ const REFERENCE_DEFINITION = /^\s{0,3}\[([^\]]+)\]:\s*(\S+)/
32
+ const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i
33
+ const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/
34
+
35
+ function collectMarkdown(dir) {
36
+ const out = []
37
+ for (const entry of readdirSync(dir)) {
38
+ const full = join(dir, entry)
39
+ const stat = statSync(full)
40
+ if (stat.isDirectory()) out.push(...collectMarkdown(full))
41
+ else if (extname(entry).toLowerCase() === '.md') out.push(full)
42
+ }
43
+ return out
44
+ }
45
+
46
+ function isInside(child, parent) {
47
+ const rel = relative(parent, child)
48
+ return rel === '' || (!rel.startsWith('..') && !rel.startsWith(`..${sep}`))
49
+ }
50
+
51
+ /** Remove fenced code blocks and inline code so examples are not parsed. */
52
+ function stripCode(source) {
53
+ const lines = source.split(/\r?\n/)
54
+ let inFence = false
55
+ let fence = ''
56
+ const kept = []
57
+ for (const line of lines) {
58
+ const match = /^\s*(`{3,}|~{3,})/.exec(line)
59
+ if (match) {
60
+ if (!inFence) {
61
+ inFence = true
62
+ fence = match[1][0]
63
+ } else if (match[1][0] === fence) {
64
+ inFence = false
65
+ }
66
+ kept.push('')
67
+ continue
68
+ }
69
+ kept.push(inFence ? '' : line)
70
+ }
71
+ return kept.join('\n').replace(/`[^`\n]*`/g, (match) => ' '.repeat(match.length))
72
+ }
73
+
74
+ /**
75
+ * Remove HTML tags in one pass.
76
+ *
77
+ * A single regex strip can leave a tag intact when the input nests angle
78
+ * brackets (`<scr<b>ipt>`), so this walks the string once:
79
+ * - a `<` outside a tag opens one;
80
+ * - a `>` outside quotes closes the innermost open tag;
81
+ * - a `<` inside a tag opens a nested level, so a malformed construct is
82
+ * dropped whole instead of leaving a fragment of its name behind;
83
+ * - `>` inside a quoted attribute does not close the tag;
84
+ * - an unbalanced `<` flushes the buffered text as literal input.
85
+ *
86
+ * @param {string} text
87
+ * @returns {string}
88
+ */
89
+ export function stripTags(text) {
90
+ let output = ''
91
+ let tag = ''
92
+ let depth = 0
93
+ let quote = null
94
+
95
+ for (const char of text) {
96
+ if (depth === 0) {
97
+ if (char === '<') {
98
+ depth = 1
99
+ tag = '<'
100
+ } else {
101
+ output += char
102
+ }
103
+ continue
104
+ }
105
+
106
+ tag += char
107
+ if (quote !== null) {
108
+ if (char === quote) quote = null
109
+ continue
110
+ }
111
+ if (char === '"' || char === "'") {
112
+ quote = char
113
+ } else if (char === '<') {
114
+ depth += 1
115
+ } else if (char === '>') {
116
+ depth -= 1
117
+ if (depth === 0) tag = ''
118
+ }
119
+ }
120
+
121
+ // No matching `>`: the buffered text was never a tag, so keep it literally.
122
+ if (depth > 0) output += tag
123
+ return output
124
+ }
125
+
126
+ /** Approximate the slug Python-Markdown/mkdocs produces for a heading. */
127
+ export function slugify(text) {
128
+ return stripTags(text)
129
+ .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
130
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
131
+ .replace(/[`*_~]/g, '')
132
+ .toLowerCase()
133
+ .replace(/[^\w\s-]/gu, '')
134
+ .trim()
135
+ .replace(/[-\s]+/g, '-')
136
+ .replace(/^[-_]+|[-_]+$/g, '')
137
+ }
138
+
139
+ /** Build the set of anchors a file exposes, including duplicate suffixes. */
140
+ function anchorsOf(source) {
141
+ const anchors = new Set()
142
+ const seen = new Map()
143
+ let inFence = false
144
+ let fence = ''
145
+ for (const line of source.split(/\r?\n/)) {
146
+ const fenceMatch = /^\s*(`{3,}|~{3,})/.exec(line)
147
+ if (fenceMatch) {
148
+ if (!inFence) {
149
+ inFence = true
150
+ fence = fenceMatch[1][0]
151
+ } else if (fenceMatch[1][0] === fence) {
152
+ inFence = false
153
+ }
154
+ continue
155
+ }
156
+ if (inFence) continue
157
+ const heading = HEADING.exec(line)
158
+ if (!heading) continue
159
+ const base = slugify(heading[2])
160
+ if (!base) continue
161
+ const count = seen.get(base) ?? 0
162
+ seen.set(base, count + 1)
163
+ anchors.add(count === 0 ? base : `${base}-${count}`)
164
+ if (count > 0) anchors.add(`${base}_${count}`)
165
+ }
166
+ return anchors
167
+ }
168
+
169
+ function lineOf(source, index) {
170
+ return source.slice(0, index).split(/\r?\n/).length
171
+ }
172
+
173
+ function normalizeTarget(raw) {
174
+ let target = raw.trim()
175
+ if (target.startsWith('<') && target.endsWith('>')) target = target.slice(1, -1)
176
+ target = target.replace(/\s+["'(].*$/, '')
177
+ return target
178
+ }
179
+
180
+ function referenceDefinitions(source) {
181
+ const definitions = new Map()
182
+ for (const line of source.split(/\r?\n/)) {
183
+ const match = REFERENCE_DEFINITION.exec(line)
184
+ if (match) definitions.set(match[1].trim().toLowerCase(), match[2].trim())
185
+ }
186
+ return definitions
187
+ }
188
+
189
+ function main() {
190
+ const files = []
191
+ if (existsSync(README)) files.push(README)
192
+ if (existsSync(DOCS_ROOT)) files.push(...collectMarkdown(DOCS_ROOT))
193
+
194
+ if (files.length === 0) {
195
+ console.error('docs:lint failed — no Markdown files were scanned')
196
+ process.exitCode = 1
197
+ return
198
+ }
199
+
200
+ const sourceCache = new Map()
201
+ const anchorCache = new Map()
202
+ const readCached = (file) => {
203
+ if (!sourceCache.has(file)) sourceCache.set(file, readFileSync(file, 'utf8'))
204
+ return sourceCache.get(file)
205
+ }
206
+ const anchorsCached = (file) => {
207
+ if (!anchorCache.has(file)) anchorCache.set(file, anchorsOf(readCached(file)))
208
+ return anchorCache.get(file)
209
+ }
210
+
211
+ const findings = []
212
+
213
+ const checkTarget = (file, pathPart, fragment, line, kind) => {
214
+ const resolved = resolve(dirname(file), pathPart)
215
+ const display = relative(ROOT, file)
216
+
217
+ if (file !== README && !isInside(resolved, DOCS_ROOT)) {
218
+ findings.push(
219
+ `${display}:${line}: ${kind} leaves docs/: ${pathPart} ` +
220
+ '(use an absolute GitHub URL for repository files)',
221
+ )
222
+ return
223
+ }
224
+ if (file === README && !isInside(resolved, ROOT)) {
225
+ findings.push(`${display}:${line}: ${kind} leaves the repository: ${pathPart}`)
226
+ return
227
+ }
228
+
229
+ let stat
230
+ try {
231
+ stat = statSync(resolved)
232
+ } catch {
233
+ findings.push(`${display}:${line}: missing ${kind} target ${pathPart}`)
234
+ return
235
+ }
236
+
237
+ if (fragment && extname(resolved).toLowerCase() === '.md' && stat.isFile()) {
238
+ if (!anchorsCached(resolved).has(fragment)) {
239
+ findings.push(`${display}:${line}: missing anchor #${fragment} in ${pathPart}`)
240
+ }
241
+ }
242
+ }
243
+
244
+ for (const file of files) {
245
+ const raw = readCached(file)
246
+ const source = stripCode(raw)
247
+ const definitions = referenceDefinitions(source)
248
+
249
+ // Inline links and images.
250
+ for (const match of source.matchAll(INLINE_LINK)) {
251
+ const target = normalizeTarget(match[2])
252
+ if (!target || EXTERNAL.test(target)) continue
253
+ const [pathPart, fragment] = target.split('#')
254
+ const line = lineOf(source, match.index)
255
+ if (pathPart === '') {
256
+ if (fragment && !anchorsCached(file).has(fragment)) {
257
+ findings.push(`${relative(ROOT, file)}:${line}: missing anchor #${fragment}`)
258
+ }
259
+ continue
260
+ }
261
+ checkTarget(file, pathPart, fragment, line, 'link')
262
+ }
263
+
264
+ for (const match of source.matchAll(INLINE_IMAGE)) {
265
+ const target = normalizeTarget(match[2])
266
+ if (!target || EXTERNAL.test(target)) continue
267
+ const [pathPart] = target.split('#')
268
+ checkTarget(file, pathPart, undefined, lineOf(source, match.index), 'image')
269
+ }
270
+
271
+ // Reference-style links and images.
272
+ for (const match of source.matchAll(REFERENCE_LINK)) {
273
+ const label = (match[2].trim() || match[1].trim()).toLowerCase()
274
+ const rawTarget = definitions.get(label)
275
+ if (rawTarget === undefined) {
276
+ findings.push(
277
+ `${relative(ROOT, file)}:${lineOf(source, match.index)}: undefined reference [${label}]`,
278
+ )
279
+ continue
280
+ }
281
+ const target = normalizeTarget(rawTarget)
282
+ if (!target || EXTERNAL.test(target)) continue
283
+ const [pathPart, fragment] = target.split('#')
284
+ checkTarget(file, pathPart, fragment, lineOf(source, match.index), 'link')
285
+ }
286
+
287
+ for (const match of source.matchAll(REFERENCE_IMAGE)) {
288
+ const label = (match[2].trim() || match[1].trim()).toLowerCase()
289
+ const rawTarget = definitions.get(label)
290
+ if (rawTarget === undefined) {
291
+ findings.push(
292
+ `${relative(ROOT, file)}:${lineOf(source, match.index)}: undefined image reference [${label}]`,
293
+ )
294
+ continue
295
+ }
296
+ const target = normalizeTarget(rawTarget)
297
+ if (!target || EXTERNAL.test(target)) continue
298
+ const [pathPart] = target.split('#')
299
+ checkTarget(file, pathPart, undefined, lineOf(source, match.index), 'image')
300
+ }
301
+ }
302
+
303
+ if (findings.length === 0) {
304
+ console.log(`docs:lint OK — ${files.length} Markdown files, no findings.`)
305
+ return
306
+ }
307
+
308
+ for (const finding of findings) console.error(finding)
309
+ console.error(`\ndocs:lint failed — ${findings.length} finding(s) in ${files.length} files.`)
310
+ process.exitCode = 1
311
+ }
312
+
313
+ const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
314
+ if (isDirectRun) main()
@@ -0,0 +1,157 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Regenerate the terminal captures embedded in docs/opencode-v2.md.
4
+ *
5
+ * Every capture is recorded by VHS from a tape committed next to its output in
6
+ * docs/assets/tui/. VHS shells out to ttyd (the terminal it drives) and ffmpeg
7
+ * (the encoder), so all three binaries must be on PATH; when one is absent this
8
+ * script exits 1 naming it instead of leaving stale media in place.
9
+ *
10
+ * Usage:
11
+ * node scripts/docs-media.mjs # record every *.tape
12
+ * node scripts/docs-media.mjs v2-sidebar # record one tape (name or file)
13
+ * node scripts/docs-media.mjs --check # verify prerequisites only
14
+ */
15
+
16
+ import { spawnSync } from 'node:child_process'
17
+ import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
18
+ import { dirname, join, resolve } from 'node:path'
19
+ import { fileURLToPath } from 'node:url'
20
+
21
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
22
+ const ASSETS_DIR = resolve(SCRIPT_DIR, '..', 'docs', 'assets', 'tui')
23
+
24
+ /** Binaries VHS needs, in the order a missing one blocks the run, plus the
25
+ * command that installs it. Detection is a real probe, not a PATH guess. */
26
+ const PREREQUISITES = [
27
+ {
28
+ bin: 'vhs',
29
+ probe: '--version',
30
+ install: 'go install github.com/charmbracelet/vhs@latest',
31
+ },
32
+ {
33
+ bin: 'ttyd',
34
+ probe: '--version',
35
+ install: 'build/install ttyd — https://github.com/tsl0922/ttyd#installation',
36
+ },
37
+ {
38
+ bin: 'ffmpeg',
39
+ probe: '-version',
40
+ install: 'install ffmpeg (e.g. `apt install ffmpeg`)',
41
+ },
42
+ ]
43
+
44
+ function probe(prerequisite) {
45
+ const result = spawnSync(prerequisite.bin, [prerequisite.probe], { encoding: 'utf8' })
46
+ return result.error === undefined || result.error === null
47
+ }
48
+
49
+ /** Print every missing prerequisite, why it is needed, and how to install it,
50
+ * then stop with a non-zero exit. Silent success on a machine that cannot
51
+ * record is exactly the failure this guard exists to prevent. */
52
+ function reportMissing(missing) {
53
+ const names = missing.map((entry) => entry.bin)
54
+ const plural = names.length === 1 ? '' : 's'
55
+ console.error(`docs:media: missing prerequisite${plural}: ${names.join(', ')}`)
56
+ console.error('')
57
+ console.error('VHS records the tapes; it drives ttyd and encodes with ffmpeg.')
58
+ for (const entry of missing) console.error(` - ${entry.bin}: ${entry.install}`)
59
+ console.error('')
60
+ console.error('No capture was produced. docs/assets/tui is unchanged.')
61
+ process.exit(1)
62
+ }
63
+
64
+ function tapesToRecord(requested) {
65
+ const available = readdirSync(ASSETS_DIR)
66
+ .filter((name) => name.endsWith('.tape'))
67
+ .sort()
68
+ if (requested.length === 0) return available
69
+ return requested.map((name) => {
70
+ const file = name.endsWith('.tape') ? name : `${name}.tape`
71
+ if (!available.includes(file)) {
72
+ console.error(`docs:media: no tape named ${file} in docs/assets/tui`)
73
+ console.error(`Available tapes: ${available.join(', ')}`)
74
+ process.exit(1)
75
+ }
76
+ return file
77
+ })
78
+ }
79
+
80
+ /** Artifacts a tape promises (`Output` and `Screenshot` commands), so a run
81
+ * that exits 0 without writing them is treated as a failure. */
82
+ function declaredArtifacts(tapeFile) {
83
+ const source = readFileSync(join(ASSETS_DIR, tapeFile), 'utf8')
84
+ const artifacts = []
85
+ for (const line of source.split(/\r?\n/)) {
86
+ const match = /^\s*(Output|Screenshot)\s+(\S+)\s*$/.exec(line)
87
+ if (match) artifacts.push({ kind: match[1], file: match[2] })
88
+ }
89
+ return artifacts
90
+ }
91
+
92
+ const args = process.argv.slice(2)
93
+ const checkOnly = args.includes('--check')
94
+ const requested = args.filter((arg) => !arg.startsWith('--'))
95
+
96
+ const missing = PREREQUISITES.filter((prerequisite) => !probe(prerequisite))
97
+ if (missing.length > 0) reportMissing(missing)
98
+ if (checkOnly) {
99
+ console.log(`docs:media: prerequisites present (${PREREQUISITES.map((p) => p.bin).join(', ')})`)
100
+ process.exit(0)
101
+ }
102
+
103
+ const tapes = tapesToRecord(requested)
104
+ if (tapes.length === 0) {
105
+ console.error('docs:media: no *.tape found in docs/assets/tui')
106
+ process.exit(1)
107
+ }
108
+
109
+ console.log(`docs:media: recording ${tapes.length} tape(s) from docs/assets/tui`)
110
+ for (const tape of tapes) {
111
+ console.log(`docs:media: vhs ${tape}`)
112
+ const declared = declaredArtifacts(tape)
113
+ if (declared.length === 0) {
114
+ console.error(`docs:media: ${tape} declares no Output or Screenshot`)
115
+ process.exit(1)
116
+ }
117
+ const runStartedAt = Date.now()
118
+ // Remove the artifacts this tape promises BEFORE recording, so existence and
119
+ // size afterwards prove this run wrote them. Without this, a previous run's
120
+ // file could satisfy both checks: filesystem mtime and Date.now() disagree by
121
+ // a few milliseconds here, so a fresh write may not look newer than the start.
122
+ // Trade-off: a failing vhs now leaves the artifact absent instead of stale,
123
+ // which the existence check below still reports as a failure.
124
+ for (const artifact of declared) {
125
+ rmSync(join(ASSETS_DIR, artifact.file), { force: true })
126
+ }
127
+ const result = spawnSync('vhs', [tape], { cwd: ASSETS_DIR, stdio: 'inherit' })
128
+ if (result.error) {
129
+ console.error(`docs:media: could not run vhs for ${tape}: ${result.error.message}`)
130
+ process.exit(1)
131
+ }
132
+ if (result.status !== 0) {
133
+ console.error(`docs:media: vhs exited ${result.status ?? 'unknown'} for ${tape}`)
134
+ process.exit(result.status ?? 1)
135
+ }
136
+ for (const artifact of declared) {
137
+ const artifactPath = join(ASSETS_DIR, artifact.file)
138
+ if (!existsSync(artifactPath)) {
139
+ console.error(
140
+ `docs:media: ${tape} declares ${artifact.kind} ${artifact.file}, but vhs did not write it`,
141
+ )
142
+ process.exit(1)
143
+ }
144
+ const stat = statSync(artifactPath)
145
+ if (stat.size === 0) {
146
+ console.error(`docs:media: ${tape} wrote an empty ${artifact.kind} ${artifact.file}`)
147
+ process.exit(1)
148
+ }
149
+ if (stat.mtimeMs < runStartedAt - 1000) {
150
+ console.error(
151
+ `docs:media: ${artifact.file} is stale — its mtime is older than this run's start`,
152
+ )
153
+ process.exit(1)
154
+ }
155
+ }
156
+ }
157
+ console.log(`docs:media: recorded ${tapes.length} tape(s)`)