pantheon-opencode 1.5.2 → 1.6.0-beta.10

package/scripts/doctor.mjs

@@ -29,6 +29,8 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { listV2UnsupportedFeatures } from '../src/pantheon/v2-unsupported.mjs'
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -88,15 +90,25 @@ function parseArgs(argv) {
     args.target = process.cwd()
   }
 
-  if (args.profile === 'auto') {
-    args.profile = args.target.includes('pantheon-sandbox') ? 'sandbox' : 'global'
-  }
-
   // Resolve to absolute
   if (!args.target.startsWith('/')) {
     args.target = join(process.cwd(), args.target)
   }
 
+  if (args.profile === 'auto') {
+    const target = resolve(args.target)
+    // A checkout is not a managed OpenCode installation: its repository
+    // config intentionally contains only development MCPs. Use the lite
+    // policy for `npm run doctor` so a fresh checkout does not require a
+    // user's global MCP registry or pre-existing venv.
+    args.profile =
+      target === resolve(ROOT)
+        ? 'lite'
+        : args.target.includes('pantheon-sandbox')
+          ? 'sandbox'
+          : 'global'
+  }
+
   return args
 }
 
@@ -159,7 +171,7 @@ function showHelp() {
    C. Permission Checks    — frontmatter validation
    D. OpenCode Status      — OpenCode artifact layout
    E. Git Status           — uncommitted changes
-   F. Runtime Layer        — venv python + pinned pip dependencies
+    F. Runtime Layer        — runtime Python + pinned pip dependencies
    H3. Plugin Drift        — registered plugin version vs this package
    K. Node Runtime         — node:sqlite availability for pantheon_cost
 
@@ -818,12 +830,14 @@ function checkGitStatus(args) {
 }
 
 // ---------------------------------------------------------------------------
-// Check F: Runtime Layer — Venv, Python & pinned dependencies
+// Check F: Runtime Layer — Runtime Python & pinned dependencies
 // ---------------------------------------------------------------------------
 // The MCP servers run on the venv Python under ~/.config/opencode/.venv
-// (same resolution as scripts/install-mcp.mjs). This layer verifies the venv
-// exists, the interpreter responds, and the installed packages satisfy the
-// EXACT pins in src/mcp/requirements-mcp.txt and requirements-vision.txt
+// (same resolution as scripts/install-mcp.mjs) after installation. A
+// repository checkout/CI job is not an installed target, however, so it may
+// intentionally have no venv. In that case the doctor uses PANTHEON_PYTHON or
+// python3 and still validates the exact pins. Missing or mismatched packages
+// remain blocking errors; the fallback never makes the runtime check advisory
 // (issue #18 / #21).
 
 /** Parse `pip freeze` output into a normalized name → version map. */
@@ -906,31 +920,53 @@ function checkRequirementLine(line, installed) {
   }
 }
 
+/** Classify whether a required runtime file is available to the doctor. */
+export function classifyRequiredRuntimeFile(exists) {
+  return exists ? 'present' : 'error'
+}
+
+/** Validate a required runtime requirements file without downgrading absence. */
+export function validateRequiredRuntimeFile(filePath) {
+  const present = classifyRequiredRuntimeFile(existsSync(filePath)) === 'present'
+  return {
+    ok: present,
+    message: present
+      ? `requirements file present: ${filePath}`
+      : `requirements file not found: ${filePath}`,
+  }
+}
+
 function checkVenvLayer(args) {
-  section('F. Runtime Layer — Venv, Python & Dependencies')
+  section('F. Runtime Layer — Runtime Python & Dependencies')
 
-  const venvPython = resolveRuntimePython(args)
+  const runtimePython = resolveRuntimePython(args)
 
-  if (!existsSync(venvPython)) {
-    if (args.profile === 'lite') {
-      info(`Venv python not found — runtime layer skipped for lite profile`)
+  if (!isAbsolute(runtimePython) || !existsSync(runtimePython)) {
+    if (runtimePython === 'python3') {
+      info('No dedicated .venv found — validating the Python interpreter on PATH')
     } else {
-      error(`Venv python not found: ${venvPython} (run \`pantheon-opencode init\` to create it)`)
+      error(
+        `Runtime Python not found: ${runtimePython} (set PANTHEON_PYTHON or run \`pantheon-opencode init\` to create a .venv)`,
+      )
+      return
     }
-    return
   }
-  pass(`Venv python exists: ${venvPython}`)
+  if (isAbsolute(runtimePython) && existsSync(runtimePython)) {
+    pass(`Runtime Python exists: ${runtimePython}`)
+  }
 
-  const probe = spawn(venvPython, ['-c', 'import sys; print(sys.version.split()[0])'])
+  const probe = spawn(runtimePython, ['-c', 'import sys; print(sys.version.split()[0])'])
   if (probe.status !== 0) {
-    error(`Venv python does not respond (exit ${probe.status}): ${probe.stderr}`)
+    error(
+      `Runtime Python does not respond (exit ${probe.status}): ${probe.stderr || 'interpreter is unavailable'}`,
+    )
     return
   }
-  pass(`Venv python responds (Python ${probe.stdout})`)
+  pass(`Runtime Python responds (Python ${probe.stdout})`)
 
-  const freeze = spawn(venvPython, ['-m', 'pip', 'freeze'])
+  const freeze = spawn(runtimePython, ['-m', 'pip', 'freeze'])
   if (freeze.status !== 0) {
-    warn(`pip freeze failed (exit ${freeze.status}) — cannot verify pinned versions`)
+    error(`pip freeze failed (exit ${freeze.status}) — cannot verify pinned versions`)
     return
   }
   const installed = parsePipFreeze(freeze.stdout)
@@ -940,8 +976,9 @@ function checkVenvLayer(args) {
     join(ROOT, 'src', 'mcp', 'requirements-vision.txt'),
   ]
   for (const reqFile of reqFiles) {
-    if (!existsSync(reqFile)) {
-      warn(`requirements file not found: ${reqFile}`)
+    const requirement = validateRequiredRuntimeFile(reqFile)
+    if (!requirement.ok) {
+      error(requirement.message)
       continue
     }
     const base = basename(reqFile)
@@ -965,7 +1002,7 @@ function checkVenvLayer(args) {
 /**
  * Return whether *dir* contains an executable code-mode target.
  *
- * Mirrors `_has_usable_scripts` in `scripts/code_mode_server.py`: a directory
+ * Mirrors `_has_usable_scripts` in `scripts/code_mode.py`: a directory
  * is only a valid resolver candidate when it is a real (non-symlink) directory
  * containing a regular `.py`/`.sh` direct child. This prevents an empty project
  * overlay from masking a lower-priority installation that actually ships
@@ -1073,7 +1110,9 @@ export function validateCodeModeManifest(codeModeDir) {
 
   const actualScripts = readdirSync(codeModeDir).filter(
     (name) =>
-      (name.endsWith('.py') || name.endsWith('.sh')) && statSync(join(codeModeDir, name)).isFile(),
+      !name.startsWith('eval-') &&
+      (name.endsWith('.py') || name.endsWith('.sh')) &&
+      statSync(join(codeModeDir, name)).isFile(),
   )
   const missing = listed.filter((name) => !existsSync(join(codeModeDir, name)))
   const extra = actualScripts.filter((name) => !Object.hasOwn(data.scripts, name))
@@ -1104,12 +1143,32 @@ export function checkCodeModeManifest(args) {
   pass(`✅ Code-mode manifest valid: ${result.count}/${result.total} scripts verified`)
 }
 
-/** Resolve the venv created by init for either a project or global install. */
+/**
+ * Resolve the Python used by the runtime checks.
+ *
+ * Installed targets use the venv created by init. A checkout in CI does not
+ * have that installation state, however, so the explicit PANTHEON_PYTHON
+ * override and the PATH fallback make the contract reproducible without
+ * silently skipping dependency validation.
+ */
 export function resolveRuntimePython(args) {
+  const env = args.env ?? process.env
+  if (typeof env.PANTHEON_PYTHON === 'string' && env.PANTHEON_PYTHON.trim() !== '') {
+    return env.PANTHEON_PYTHON.trim()
+  }
+
   const target = resolve(args.target)
   const isProject = existsSync(join(target, '.opencode'))
-  const runtimeRoot = isProject ? target : resolveOpenCodeConfigDir(args.env ?? process.env)
-  return join(runtimeRoot, '.venv', 'bin', 'python3')
+  const runtimeRoot = isProject ? target : resolveOpenCodeConfigDir(env)
+  const venvCandidates =
+    process.platform === 'win32'
+      ? [
+          join(runtimeRoot, '.venv', 'Scripts', 'python.exe'),
+          join(runtimeRoot, '.venv', 'Scripts', 'python'),
+        ]
+      : [join(runtimeRoot, '.venv', 'bin', 'python3'), join(runtimeRoot, '.venv', 'bin', 'python')]
+  const existing = venvCandidates.find((candidate) => existsSync(candidate))
+  return existing ?? 'python3'
 }
 
 /** Return relative script arguments as absolute paths using an MCP entry cwd. */
@@ -1373,6 +1432,153 @@ export function checkPluginVersionDrift(args) {
   return 'sync'
 }
 
+// ---------------------------------------------------------------------------
+// Check H4: V2 feature reduction (the surface a migrating user loses)
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether an opencode.json registers the V2 generation of the Pantheon plugin.
+ *
+ * The V2 contract is the PLURAL `plugins` key; V1 is the singular `plugin` key.
+ * So the key alone is not the test — a config can legitimately carry a
+ * third-party entry in `plugins`. What identifies the generation is a Pantheon
+ * V2 entry inside it. Matched on the `plugin-v2` marker so all three real
+ * spellings are recognised: the canonical DIRECTORY (`src/plugin-v2`), an
+ * absolute path to it, and the package export (`pantheon-opencode/plugin-v2`).
+ *
+ * @param {unknown} ref
+ * @returns {boolean}
+ */
+function isV2PluginRef(ref) {
+  const candidate =
+    typeof ref === 'string'
+      ? ref
+      : ref && typeof ref === 'object'
+        ? (ref.path ?? ref.source ?? ref.id ?? ref.name)
+        : undefined
+  return typeof candidate === 'string' && candidate.includes('plugin-v2')
+}
+
+/**
+ * Whether any reachable config registers the V2 generation of the Pantheon
+ * plugin. Split out of {@link collectV2UnsupportedFeatures} because "is the V2
+ * generation registered" and "does the seed list anything" are TWO facts: the
+ * first is about the user's config, the second about this repository's seed. A
+ * single `features.length === 0` cannot tell them apart, and conflating them
+ * let an emptied seed print "no V2 generation registered — nothing reduced".
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {boolean}
+ */
+export function isV2GenerationRegistered(configs) {
+  return configs.some((cfg) => {
+    const list = cfg.data?.plugins
+    return Array.isArray(list) && list.some(isV2PluginRef)
+  })
+}
+
+/**
+ * The V2 feature-reduction markers to report for a set of collected configs.
+ *
+ * Returns the shared seed verbatim when ANY reachable config registers the V2
+ * generation, and an empty list otherwise. The strings come from
+ * `src/pantheon/v2-unsupported.mjs` — the same seed `getUnsupportedFeatures()`
+ * is built from — so doctor cannot report a reduction the plugin does not, or
+ * miss one it does. Nothing is reworded here.
+ *
+ * An empty result is ambiguous on its own and deliberately not interpreted
+ * here: ask {@link isV2GenerationRegistered} for the registration fact, or
+ * {@link describeV2Reduction} to get both at once.
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {string[]}
+ */
+export function collectV2UnsupportedFeatures(configs) {
+  return isV2GenerationRegistered(configs) ? listV2UnsupportedFeatures() : []
+}
+
+/**
+ * Decide what H4 prints, from the two distinct facts rather than from one list
+ * length.
+ *
+ * Three cases, and the middle one used to be silently reported as the first:
+ *
+ *   - not registered → info. A V1 install is a supported configuration with
+ *     nothing to reduce, and saying so plainly is correct.
+ *   - registered, seed EMPTY → warn. This is a packaging fault in THIS repo,
+ *     not an absence of reduction: the V2 surface really is reduced and the
+ *     report is missing. It must never claim "nothing reduced".
+ *   - registered, seed populated → warn, listing every marker.
+ *
+ * Pure and exported so the empty-seed branch is testable without stubbing the
+ * frozen seed module. `status` is returned alongside the text so a caller never
+ * has to recover the case by matching on the message.
+ *
+ * @param {{registered:boolean, features:string[]}} input
+ * @returns {{status:'reported'|'empty-seed'|'no-v2-generation', level:'info'|'warn', message:string}}
+ */
+export function describeV2Reduction({ registered, features }) {
+  if (!registered) {
+    return {
+      status: 'no-v2-generation',
+      level: 'info',
+      message: 'No V2 plugin generation registered — nothing reduced',
+    }
+  }
+  if (features.length === 0) {
+    return {
+      status: 'empty-seed',
+      level: 'warn',
+      message:
+        'Pantheon IS registered on the V2 plugin generation, but the shared ' +
+        'unsupported-feature seed is empty, so the reduction cannot be reported. ' +
+        "That is a fault in this installation's reporting, not an absence of " +
+        'reduction: the V2 surface still drops the 3 goal tools and the ' +
+        'caller/target delegation matrix.',
+    }
+  }
+  return {
+    status: 'reported',
+    level: 'warn',
+    message:
+      'Pantheon is registered on the V2 plugin generation, which registers 3 tools ' +
+      "(hashline_edit, pantheon_cost, pantheon_model) instead of the V1 surface's 6 plus " +
+      `the BackgroundJobBoard and the caller/target delegation matrix. Unsupported: ${features.join(', ')}`,
+  }
+}
+
+/**
+ * Report the V2 feature reduction through doctor's own output shape
+ * (section + warn/info), so it lands in the health summary like every other
+ * finding and never changes the exit code: a V2 install is a supported
+ * configuration, not a broken one.
+ *
+ * @param {{target:string, env?:object}} args
+ * @returns {'reported'|'empty-seed'|'no-v2-generation'|'no-config'}
+ */
+export function checkV2UnsupportedFeatures(args) {
+  section('H4. V2 Feature Reduction')
+
+  const configs = collectMcpConfigs(args)
+  if (configs.length === 0) {
+    info('No opencode.json was found — V2 feature reduction check skipped')
+    return 'no-config'
+  }
+
+  // Branch on REGISTRATION, not on the marker count: an empty seed on a
+  // registered V2 generation is a reporting fault and must not be reported as
+  // the reassuring "nothing reduced".
+  const registered = isV2GenerationRegistered(configs)
+  const verdict = describeV2Reduction({
+    registered,
+    features: collectV2UnsupportedFeatures(configs),
+  })
+  if (verdict.level === 'info') info(verdict.message)
+  else warn(verdict.message)
+
+  return verdict.status
+}
+
 // ---------------------------------------------------------------------------
 // Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
@@ -1745,6 +1951,7 @@ async function main() {
   checkAgentsMdFreshness(args)
   checkSubagentDepthPlacement(args)
   checkPermissionTaskPresence(args)
+  checkV2UnsupportedFeatures(args)
 
   printSummary(args.target)
 

package/scripts/install/agents-md.mjs

@@ -2,7 +2,7 @@
 /**
  * agents-md.mjs — Dynamic AGENTS.md generator from canonical agent frontmatter
  *
- * Reads all agents/*.agent.md files, extracts name + description from frontmatter,
+ * Reads all canonical src/agents/*.md files, extracts name + description from frontmatter,
  * and generates AGENTS.md content dynamically. Eliminates hardcoded agent tables
  * in platform installers (claude.mjs, cursor.mjs, windsurf.mjs, cline.mjs, etc.).
  *
@@ -21,7 +21,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import yaml from 'js-yaml'
+import { load } from 'js-yaml'
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -47,7 +47,7 @@ function parseAgentFrontmatter(content) {
   if (!match) return null
 
   try {
-    const fm = yaml.load(match[1])
+    const fm = load(match[1])
     if (!fm || typeof fm !== 'object' || !fm.name) return null
     return {
       name: String(fm.name),
@@ -64,7 +64,7 @@ function parseAgentFrontmatter(content) {
 // ---------------------------------------------------------------------------
 
 /**
- * Read all canonical agents/*.agent.md files, parse frontmatter,
+ * Read all canonical src/agents/*.md files, parse frontmatter,
  * and return an array of agent metadata objects sorted alphabetically by name.
  *
  * Skips files that don't match the `*.agent.md` pattern, files without

package/scripts/install/cli-ui.mjs

@@ -159,7 +159,7 @@ export function spinner(message) {
   }
 }
 
-export function printSummary(target, platforms, stats) {
+export function printSummary(target, _platforms, stats) {
   if (_quiet) return
 
   const S = strings()