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
@@ -4,11 +4,12 @@
4
4
 
5
5
  import { spawnSync } from 'node:child_process'
6
6
  import {
7
- copyFileSync,
8
- cpSync,
7
+ chmodSync,
8
+ closeSync,
9
9
  existsSync,
10
10
  lstatSync,
11
11
  mkdirSync,
12
+ openSync,
12
13
  readdirSync,
13
14
  readFileSync,
14
15
  renameSync,
@@ -16,17 +17,37 @@ import {
16
17
  statSync,
17
18
  writeFileSync,
18
19
  } from 'node:fs'
19
- import { basename, dirname, join } from 'node:path'
20
+ import { dirname, join } from 'node:path'
20
21
  import { fileURLToPath } from 'node:url'
22
+ import {
23
+ isSupportedNodeVersion,
24
+ MIN_SUPPORTED_NODE_VERSION,
25
+ unsupportedNodeVersionMessage,
26
+ } from '../node-engine-policy.mjs'
21
27
 
22
- const REQUIRED_NODE_MAJOR = 18
23
- if (parseInt(process.versions.node.split('.')[0], 10) < REQUIRED_NODE_MAJOR) {
24
- console.error(`❌ Node.js >= ${REQUIRED_NODE_MAJOR} required (current: ${process.versions.node})`)
28
+ if (!isSupportedNodeVersion(process.versions.node)) {
29
+ console.error(unsupportedNodeVersionMessage(process.versions.node))
25
30
  process.exit(1)
26
31
  }
27
32
 
28
33
  import { dump, load } from 'js-yaml'
29
34
 
35
+ import {
36
+ ACTIONS,
37
+ fingerprintOutput,
38
+ isRecording,
39
+ recordChange,
40
+ recordRemovalTree,
41
+ removeReviewedTree,
42
+ } from './plan.mjs'
43
+ import {
44
+ assertNoSymlinkAncestors,
45
+ assertPathWithin,
46
+ assertSafeRemoval,
47
+ verifyPathRemoved,
48
+ verifyRegularFile,
49
+ } from './verify.mjs'
50
+
30
51
  export const __dirname = dirname(fileURLToPath(import.meta.url))
31
52
  export const ROOT = join(__dirname, '..', '..')
32
53
  export const AGENTS_DIR = join(ROOT, 'src', 'agents')
@@ -119,7 +140,7 @@ export function parseArgs(argv) {
119
140
  args.help = true
120
141
  break
121
142
  default:
122
- console.warn(`⚠️ Unknown option: ${argv[i]}`)
143
+ console.warn(`[WARN] Unknown option: ${argv[i]}`)
123
144
  break
124
145
  }
125
146
  }
@@ -141,42 +162,15 @@ export function resolveTarget(target) {
141
162
  return join(process.cwd(), target)
142
163
  }
143
164
 
144
- export function createBackup(target) {
145
- const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
146
- const backupDir = join(target, '..', `.pantheon-bak-${basename(target)}-${timestamp}`)
147
-
148
- console.log(`\n 💾 Creating backup: ${backupDir}`)
149
- mkdirSync(backupDir, { recursive: true })
150
-
151
- // Copy only relevant Pantheon directories/files
152
- const items = ['agents', 'skills', 'commands', 'instructions', 'opencode.json', 'tui.json']
153
- let count = 0
154
- for (const item of items) {
155
- const src = join(target, item)
156
- try {
157
- cpSync(src, join(backupDir, item), {
158
- recursive: true,
159
- errorOnExist: false,
160
- })
161
- count++
162
- } catch {
163
- // File or directory doesn't exist in target — skip silently
164
- }
165
- }
166
-
167
- console.log(` ✅ Backed up ${count} items to: ${backupDir}`)
168
- return backupDir
169
- }
170
-
171
165
  export function detectAndReport(target) {
172
166
  const found = detectPlatforms(target).length > 0
173
167
 
174
- console.log(`\n 🔍 Pantheon Platform Detection`)
168
+ console.log(`\n Pantheon Platform Detection`)
175
169
  console.log(` Target: ${target}\n`)
176
170
 
177
171
  console.log(` ${'Platform'.padEnd(12)} ${'Detected?'.padEnd(12)} Config file`)
178
172
  console.log(` ${'─'.repeat(55)}`)
179
- const status = (found ? '✅ YES' : '❌ no').padEnd(12)
173
+ const status = (found ? '[OK] yes' : '[MISSING]').padEnd(12)
180
174
  console.log(` ${'OpenCode'.padEnd(12)} ${status} ${found ? 'opencode.json' : '(not found)'}`)
181
175
  console.log(`\n 📊 ${found ? 1 : 0} of 1 platforms detected.`)
182
176
  if (found) {
@@ -197,6 +191,7 @@ export function sourceDirValid(dir) {
197
191
  }
198
192
 
199
193
  export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = false) {
194
+ assertNoSymlinkAncestors(dstDir)
200
195
  const entries = readdirSync(srcDir)
201
196
  let created = 0
202
197
  let skipped = 0
@@ -212,6 +207,8 @@ export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = fals
212
207
  dstNames.add(dstName)
213
208
 
214
209
  const dstFile = join(dstDir, dstName)
210
+ assertPathWithin(dstDir, dstFile)
211
+ assertNoSymlinkAncestors(dstFile)
215
212
 
216
213
  if (statSync(srcFile).isDirectory()) continue
217
214
  const content = readFileSync(srcFile, 'utf8')
@@ -222,14 +219,10 @@ export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = fals
222
219
  skipped++
223
220
  continue
224
221
  }
225
- if (!dryRun) {
226
- writeFileSync(dstFile, content, 'utf8')
227
- }
222
+ writeIfChanged(dstFile, content, dryRun)
228
223
  created++
229
224
  } else {
230
- if (!dryRun) {
231
- writeFileSync(dstFile, content, 'utf8')
232
- }
225
+ writeIfChanged(dstFile, content, dryRun)
233
226
  created++
234
227
  }
235
228
  }
@@ -239,17 +232,21 @@ export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = fals
239
232
  // (lowercase name + .md/.mdc extension), regardless of AGENT_NAMES membership.
240
233
  // This handles deleted canonical agents (e.g., agora) whose source file is gone.
241
234
  if (clean && existsSync(dstDir)) {
235
+ assertNoSymlinkAncestors(dstDir)
242
236
  const dstEntries = readdirSync(dstDir)
243
237
  const agentPattern = /^[a-z-]+\.(md|mdc)$/
244
238
  for (const entry of dstEntries) {
245
239
  if (dstNames.has(entry)) continue // still in source
246
240
  const dstFile = join(dstDir, entry)
241
+ assertSafeRemoval(dstDir, dstFile)
247
242
  if (!statSync(dstFile).isFile()) continue
248
243
  // Safety: only remove files that match agent file naming pattern
249
244
  // (user custom files with different naming patterns are untouched)
250
245
  if (!agentPattern.test(entry)) continue
251
246
  if (!dryRun) {
247
+ assertSafeRemoval(dstDir, dstFile)
252
248
  rmSync(dstFile, { force: true })
249
+ verifyPathRemoved(dstFile)
253
250
  }
254
251
  created++
255
252
  }
@@ -302,35 +299,71 @@ function readFileOrNull(filePath) {
302
299
  * filesystem CAS: the final re-read and the rename are still two syscalls, so
303
300
  * a writer that lands between them is not prevented. What it does close is
304
301
  * the window the installer actually races with — a config the caller parsed
305
- * going stale during the same run — and it keeps the target and the `.bak`
306
- * consistent with the bytes that were checked.
302
+ * going stale during the same run — and it keeps the target consistent with
303
+ * the bytes that were checked.
307
304
  * @param {(existing: string|null) => void} [options.beforeRecheck] - runs after
308
305
  * the initial content check and before the last-moment re-read. Injection
309
306
  * point so tests can simulate a concurrent writer landing in the window;
310
307
  * production callers omit it (undefined is a no-op).
311
308
  * @param {(existing: string|null) => void} [options.beforeSwap] - runs after the
312
- * expected-content checks pass and immediately before the rename, so side
313
- * effects that must not fire on a conflict (e.g. the `.bak` copy) live here.
309
+ * expected-content checks pass and immediately before the rename, for side
310
+ * effects that must not fire on a conflict.
311
+ * @param {(change: object) => void} [options.recorder] - optional change
312
+ * recorder. When supplied, the outcome is recorded (path + action + byte
313
+ * size only) so `--dry-run` can print the real per-file plan. Defaults to
314
+ * the module-level no-op singleton, so an uninstrumented caller is
315
+ * byte-identical to before.
316
+ * @param {number} [options.mode] - mode for a newly created file; existing
317
+ * destination modes are preserved.
318
+ * @param {boolean} [options.scored] - set `false` when this write is not part
319
+ * of the install summary (e.g. stale-ref cleanup), so it is shown in the plan
320
+ * but excluded from the consistency guard.
314
321
  * @returns {'created'|'skipped'|'conflict'}
315
322
  */
316
323
  export function writeIfChanged(filePath, content, dryRun, options = {}) {
317
- const { expectedContent, beforeSwap, beforeRecheck } = options
324
+ const { expectedContent, beforeSwap, beforeRecheck, recorder, scored, mode } = options
318
325
 
319
- // Refuse to write through/over a symlink. A dangling symlink is invisible to
320
- // existsSync, and rename-over-link would replace the link rather than its
321
- // target — both are silent redirections the installer must not perform.
326
+ // A linked parent redirects both the atomic temp write and the eventual
327
+ // rename, so validate the full path rather than only its final component.
328
+ assertNoSymlinkAncestors(filePath)
322
329
  const stat = lstatOrNull(filePath)
323
330
  if (stat?.isSymbolicLink()) {
324
331
  throw new Error(`Refusing to write through symlink: ${filePath}`)
325
332
  }
333
+ // Preserve the destination's access mode across the atomic rename. A mode
334
+ // supplied by the caller is used only for a newly created destination.
335
+ const targetMode = stat === null ? mode : stat.mode & 0o777
326
336
 
327
337
  const existing = stat === null ? null : readFileOrNull(filePath)
338
+ const record = (outcome) => {
339
+ if (!isRecording(recorder)) return
340
+ const action =
341
+ outcome === 'conflict'
342
+ ? ACTIONS.CONFLICT
343
+ : outcome === 'skipped'
344
+ ? ACTIONS.UNCHANGED
345
+ : existing === null
346
+ ? ACTIONS.CREATE
347
+ : ACTIONS.UPDATE
348
+ recordChange(
349
+ {
350
+ path: filePath,
351
+ action,
352
+ bytes: Buffer.byteLength(content, 'utf8'),
353
+ outputFingerprint: fingerprintOutput(content),
354
+ scored,
355
+ },
356
+ recorder,
357
+ )
358
+ }
328
359
  if (existing === content) {
360
+ record('skipped')
329
361
  return 'skipped'
330
362
  }
331
363
  if (expectedContent !== undefined && existing !== expectedContent) {
332
364
  // The file changed since the caller read it (or appeared/disappeared).
333
365
  // Do not clobber the newer content; the caller decides how to react.
366
+ record('conflict')
334
367
  return 'conflict'
335
368
  }
336
369
  if (!dryRun) {
@@ -342,36 +375,71 @@ export function writeIfChanged(filePath, content, dryRun, options = {}) {
342
375
  // crash mid-write can never leave a truncated file behind (rename is
343
376
  // atomic within the same directory).
344
377
  const tmpPath = `${filePath}.tmp-${process.pid}`
345
- writeFileSync(tmpPath, content, 'utf8')
346
-
347
- // Last-moment re-read. The initial compare and this rename are separate
348
- // syscalls, so a concurrent writer can land in between; re-check the
349
- // expected bytes immediately before the swap. On a mismatch, drop the temp
350
- // and leave the target AND any existing `.bak` byte-identical.
351
- if (expectedContent !== undefined) {
352
- const current = readFileOrNull(filePath)
353
- if (current !== expectedContent) {
354
- rmSync(tmpPath, { force: true })
355
- return 'conflict'
378
+ assertNoSymlinkAncestors(tmpPath)
379
+ let fd
380
+ let createdTemporary = false
381
+ try {
382
+ // Exclusive creation establishes ownership. Cleanup below is limited to
383
+ // this exact path and only runs after this invocation opened it.
384
+ fd = openSync(tmpPath, 'wx', targetMode)
385
+ createdTemporary = true
386
+ writeFileSync(fd, content, { encoding: 'utf8' })
387
+ closeSync(fd)
388
+ fd = undefined
389
+ if (targetMode !== undefined) chmodSync(tmpPath, targetMode)
390
+
391
+ // Last-moment re-read. The initial compare and this rename are separate
392
+ // syscalls, so a concurrent writer can land in between; re-check the
393
+ // expected bytes immediately before the swap. On a mismatch, leave the
394
+ // target byte-identical; finally removes only the temp created above.
395
+ if (expectedContent !== undefined) {
396
+ const current = readFileOrNull(filePath)
397
+ if (current !== expectedContent) {
398
+ record('conflict')
399
+ return 'conflict'
400
+ }
356
401
  }
357
- }
358
402
 
359
- if (typeof beforeSwap === 'function') beforeSwap(existing)
360
- renameSync(tmpPath, filePath)
403
+ if (typeof beforeSwap === 'function') beforeSwap(existing)
404
+ assertNoSymlinkAncestors(filePath)
405
+ renameSync(tmpPath, filePath)
406
+ createdTemporary = false
407
+ verifyRegularFile(filePath, content)
408
+ } finally {
409
+ if (fd !== undefined) {
410
+ try {
411
+ closeSync(fd)
412
+ } catch {
413
+ // Preserve the write error; closing a failed descriptor is best-effort.
414
+ }
415
+ }
416
+ if (createdTemporary) {
417
+ try {
418
+ assertSafeRemoval(dirname(tmpPath), tmpPath)
419
+ rmSync(tmpPath, { force: true })
420
+ verifyPathRemoved(tmpPath)
421
+ } catch {
422
+ // Preserve the write error and never follow an unsafe temp path.
423
+ }
424
+ }
425
+ }
361
426
  }
427
+ record('created')
362
428
  return 'created'
363
429
  }
364
430
 
365
431
  /**
366
- * beta.5: write the user's opencode.json with a same-directory backup of the
367
- * previous content. The installer rewrites the whole config; a `.bak` gives
368
- * the user a one-step recovery if a merge ever goes wrong.
432
+ * Write a config file atomically, honoring the compare-before-write guard.
433
+ * This used to always keep a `<config>.bak` sidecar; the main `opencode.json`
434
+ * no longer does — the target-scoped exact backup set
435
+ * (scripts/install/backup.mjs) preserves it byte-for-byte and
436
+ * `pantheon-opencode restore` reverts it.
369
437
  *
370
- * The backup is created INSIDE the `beforeSwap` hook, so it fires only after
371
- * both expected-content checks pass (the initial compare and the last-moment
372
- * re-read before the rename). A conflict observed at either point leaves the
373
- * target AND any pre-existing `.bak` untouched, rather than overwriting the
374
- * user's last known-good backup with a stale copy on a no-op write.
438
+ * A caller may still supply `beforeSwap` for a file the exact set does NOT
439
+ * cover: the GLOBAL `opencode-vision.json` lives outside the config dir, so
440
+ * vision-prompt passes a `beforeSwap` that keeps its `<file>.bak` recovery.
441
+ * New config files default to mode `0600`; existing destination modes survive
442
+ * replacement.
375
443
  *
376
444
  * @param {string} filePath
377
445
  * @param {string} content
@@ -382,14 +450,10 @@ export function writeConfigWithBackup(filePath, content, dryRun, options = {}) {
382
450
  return writeIfChanged(filePath, content, dryRun, {
383
451
  expectedContent: options.expectedContent,
384
452
  beforeRecheck: options.beforeRecheck,
385
- beforeSwap: (existing) => {
386
- if (existing === null) return
387
- try {
388
- copyFileSync(filePath, `${filePath}.bak`)
389
- } catch {
390
- // Best-effort: a backup failure must not block the install.
391
- }
392
- },
453
+ beforeSwap: options.beforeSwap,
454
+ recorder: options.recorder,
455
+ scored: options.scored,
456
+ mode: options.mode ?? 0o600,
393
457
  })
394
458
  }
395
459
 
@@ -403,7 +467,10 @@ export function checkRuntimePrerequisites(env = process.env) {
403
467
  const problems = []
404
468
  const checks = [
405
469
  { cmd: 'python3', hint: 'install Python 3.10+ (https://www.python.org/downloads/)' },
406
- { cmd: 'npm', hint: 'install Node.js 22+ (https://nodejs.org) — npm ships with it' },
470
+ {
471
+ cmd: 'npm',
472
+ hint: `install Node.js >= ${MIN_SUPPORTED_NODE_VERSION} (https://nodejs.org) — npm ships with it`,
473
+ },
407
474
  ]
408
475
  for (const { cmd, hint } of checks) {
409
476
  const probe = spawnSync(cmd, ['--version'], { encoding: 'utf8', timeout: 10_000, env })
@@ -455,9 +522,27 @@ export function serializeFm(fm) {
455
522
  })
456
523
  }
457
524
 
458
- export function installSkills(skills, target, dryRun, subDir = '.opencode') {
525
+ function recordDirectoryOutcomes(srcDir, dstDir, recorder) {
526
+ recordChange({ path: dstDir, action: ACTIONS.UNCHANGED, bytes: 0, scored: false }, recorder)
527
+ for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
528
+ if (!entry.isDirectory()) continue
529
+ recordDirectoryOutcomes(join(srcDir, entry.name), join(dstDir, entry.name), recorder)
530
+ }
531
+ }
532
+
533
+ export function installSkills(
534
+ skills,
535
+ target,
536
+ dryRun,
537
+ subDir = '.opencode',
538
+ recorder = null,
539
+ reviewedRemovals = null,
540
+ reviewedSnapshots = null,
541
+ clean = false,
542
+ ) {
459
543
  const srcSkillsDir = join(ROOT, 'src', 'skills')
460
544
  const dstSkillsDir = join(target, subDir, 'skills')
545
+ assertNoSymlinkAncestors(dstSkillsDir)
461
546
 
462
547
  let created = 0
463
548
  let skipped = 0
@@ -466,7 +551,12 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
466
551
  const src = join(srcSkillsDir, skill)
467
552
  const dst = join(dstSkillsDir, skill)
468
553
 
469
- if (!dryRun) mkdirSync(dst, { recursive: true })
554
+ if (!dryRun) {
555
+ assertPathWithin(dstSkillsDir, dst)
556
+ assertNoSymlinkAncestors(dst)
557
+ mkdirSync(dst, { recursive: true })
558
+ assertNoSymlinkAncestors(dst)
559
+ }
470
560
 
471
561
  function copyDirRecursive(from, to) {
472
562
  const entries = readdirSync(from)
@@ -474,15 +564,47 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
474
564
  const srcPath = join(from, entry)
475
565
  const dstPath = join(to, entry)
476
566
  if (statSync(srcPath).isDirectory()) {
477
- if (!dryRun) mkdirSync(dstPath, { recursive: true })
567
+ if (!dryRun) {
568
+ assertPathWithin(dstSkillsDir, dstPath)
569
+ assertNoSymlinkAncestors(dstPath)
570
+ mkdirSync(dstPath, { recursive: true })
571
+ assertNoSymlinkAncestors(dstPath)
572
+ }
478
573
  copyDirRecursive(srcPath, dstPath)
479
574
  } else {
480
575
  const content = readFileSync(srcPath, 'utf8')
481
- const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
576
+ const dstStat = lstatOrNull(dstPath)
577
+ if (dstStat?.isSymbolicLink()) {
578
+ throw new Error(`Refusing to read through symlink: ${dstPath}`)
579
+ }
580
+ const existing = dstStat === null ? null : readFileSync(dstPath, 'utf8')
482
581
  if (existing === content) {
483
582
  skipped++
583
+ if (isRecording(recorder)) {
584
+ recordChange(
585
+ {
586
+ path: dstPath,
587
+ action: ACTIONS.UNCHANGED,
588
+ bytes: Buffer.byteLength(content, 'utf8'),
589
+ outputFingerprint: fingerprintOutput(content),
590
+ },
591
+ recorder,
592
+ )
593
+ }
484
594
  } else {
485
- if (!dryRun) writeFileSync(dstPath, content, 'utf8')
595
+ if (!dryRun) {
596
+ writeIfChanged(dstPath, content, false, { recorder })
597
+ } else if (isRecording(recorder)) {
598
+ recordChange(
599
+ {
600
+ path: dstPath,
601
+ action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
602
+ bytes: Buffer.byteLength(content, 'utf8'),
603
+ outputFingerprint: fingerprintOutput(content),
604
+ },
605
+ recorder,
606
+ )
607
+ }
486
608
  created++
487
609
  }
488
610
  }
@@ -490,20 +612,29 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
490
612
  }
491
613
 
492
614
  copyDirRecursive(src, dst)
615
+ if (clean && existsSync(dst)) recordDirectoryOutcomes(src, dst, recorder)
493
616
  }
494
617
 
495
618
  // Remove stale skills that exist in dst but not in skills list
496
619
  if (existsSync(dstSkillsDir)) {
620
+ assertNoSymlinkAncestors(dstSkillsDir)
497
621
  const dstEntries = readdirSync(dstSkillsDir)
498
622
  for (const entry of dstEntries) {
499
623
  const dstPath = join(dstSkillsDir, entry)
624
+ assertSafeRemoval(dstSkillsDir, dstPath)
500
625
  if (!statSync(dstPath).isDirectory()) continue
501
626
  if (!skills.includes(entry)) {
502
- if (!dryRun) {
503
- rmSync(dstPath, { recursive: true, force: true })
627
+ if (dryRun) {
628
+ recordRemovalTree(dstPath, recorder)
629
+ } else {
630
+ assertSafeRemoval(dstSkillsDir, dstPath)
631
+ removeReviewedTree(dstPath, reviewedRemovals, reviewedSnapshots)
504
632
  console.log(` 🗑️ Removed stale skill: ${entry}`)
505
633
  }
506
634
  created++
635
+ // A stale removal increments `created` (a change), so it must also be
636
+ // recorded or the preview would under-report on a non-fresh target.
637
+ recordChange({ path: dstPath, action: ACTIONS.REMOVE, bytes: 0 }, recorder)
507
638
  }
508
639
  }
509
640
  }
@@ -511,18 +642,35 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
511
642
  return { created, skipped }
512
643
  }
513
644
 
514
- export function syncDir(src, dst, dryRun, clean = false, filter = null) {
645
+ export function syncDir(
646
+ src,
647
+ dst,
648
+ dryRun,
649
+ clean = false,
650
+ filter = null,
651
+ recorder = null,
652
+ reviewedRemovals = null,
653
+ reviewedSnapshots = null,
654
+ ) {
515
655
  if (!existsSync(src)) return { created: 0, skipped: 0 }
516
656
  let created = 0
517
657
  let skipped = 0
658
+ const cleanTargetExisted = clean && existsSync(dst)
518
659
 
519
- if (clean && existsSync(dst)) {
520
- if (!dryRun) {
521
- rmSync(dst, { recursive: true, force: true })
660
+ if (cleanTargetExisted) {
661
+ if (dryRun) {
662
+ recordRemovalTree(dst, recorder)
663
+ } else {
664
+ assertSafeRemoval(dirname(dst), dst)
665
+ removeReviewedTree(dst, reviewedRemovals, reviewedSnapshots)
522
666
  }
523
667
  }
524
668
 
525
- if (!dryRun) mkdirSync(dst, { recursive: true })
669
+ if (!dryRun) {
670
+ assertNoSymlinkAncestors(dst)
671
+ mkdirSync(dst, { recursive: true })
672
+ assertNoSymlinkAncestors(dst)
673
+ }
526
674
 
527
675
  const entries = readdirSync(src)
528
676
  for (const entry of entries) {
@@ -530,20 +678,29 @@ export function syncDir(src, dst, dryRun, clean = false, filter = null) {
530
678
  const srcPath = join(src, entry)
531
679
  const dstPath = join(dst, entry)
532
680
  if (statSync(srcPath).isDirectory()) {
533
- const sub = syncDir(srcPath, dstPath, dryRun, false, filter)
681
+ const sub = syncDir(
682
+ srcPath,
683
+ dstPath,
684
+ dryRun,
685
+ false,
686
+ filter,
687
+ recorder,
688
+ reviewedRemovals,
689
+ reviewedSnapshots,
690
+ )
534
691
  created += sub.created
535
692
  skipped += sub.skipped
536
693
  } else {
537
694
  const content = readFileSync(srcPath, 'utf8')
538
- const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
539
- if (existing === content) {
695
+ const status = writeIfChanged(dstPath, content, dryRun, { recorder })
696
+ if (status === 'skipped') {
540
697
  skipped++
541
698
  } else {
542
- if (!dryRun) writeFileSync(dstPath, content, 'utf8')
543
699
  created++
544
700
  }
545
701
  }
546
702
  }
703
+ if (cleanTargetExisted) recordDirectoryOutcomes(src, dst, recorder)
547
704
  return { created, skipped }
548
705
  }
549
706
 
@@ -656,7 +813,7 @@ export function printSummary(target, platforms) {
656
813
  totalSkipped += stats.skipped
657
814
  totalErrors += stats.errors
658
815
 
659
- const status = stats.errors > 0 ? '⚠️' : '✅'
816
+ const status = stats.errors > 0 ? '[WARN]' : '[OK]'
660
817
  console.log(
661
818
  ` ${status} ${label}: ${stats.created} created, ${stats.skipped} skipped${stats.errors > 0 ? `, ${stats.errors} errors` : ''}`,
662
819
  )
@@ -668,7 +825,7 @@ export function printSummary(target, platforms) {
668
825
  )
669
826
 
670
827
  if (totalErrors > 0) {
671
- console.log(' ⚠️ Some platforms had errors — review warnings above.')
828
+ console.log(' [WARN] Some platforms had errors — review warnings above.')
672
829
  }
673
830
 
674
831
  console.log('')