@plainconceptsplatform/agent-harness 2.0.0

package/src/steps/platform/index.js

@@ -0,0 +1,109 @@
+import { select } from '@inquirer/prompts'
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { code, commandExists, header, info, success, warn } from '../../utils/exec.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const PLATFORMS_PRESET_PATH = path.resolve(__dirname, '../../presets/platforms.json')
+const platformsPreset = await fse.readJson(PLATFORMS_PRESET_PATH)
+
+
+export async function checkPlatform(platform) {
+  const preset = platformsPreset.find(p => p.value === platform) || platformsPreset[0]
+  if (!preset.cli) {
+    header(`Step 4, Checking ${preset.name} CLI`)
+    info('No platform integration selected, skipping CLI checks.')
+    success(`Platform: ${preset.name}`)
+    return
+  }
+  await checkPlatformCli(preset)
+}
+
+export async function choosePlatform() {
+  header('Step 3, Version control platform')
+
+  const backlogChoices = platformsPreset.filter(p => !p.repoOnly)
+  const backlogPlatform = await select({
+    message: 'Where is your backlog (work items / issues)?',
+    choices: backlogChoices.map(p => ({ name: p.name, value: p.value })),
+  })
+
+  const backlogPreset = platformsPreset.find(p => p.value === backlogPlatform)
+  success(`Backlog platform: ${backlogPreset?.name || backlogPlatform}`)
+
+  let repoPlatform = backlogPlatform
+  if (backlogPlatform !== 'none') {
+    // Exclude backlog-only platforms (e.g. Jira) from repo choices
+    const repoChoices = platformsPreset.filter(p => !p.backlogOnly)
+    repoPlatform = await select({
+      message: 'Where is your code repository (PRs / code reviews)?',
+      choices: repoChoices.map(p => ({ name: p.name, value: p.value })),
+      default: backlogPreset.backlogOnly ? 'github' : backlogPlatform,
+    })
+    const repoPreset = platformsPreset.find(p => p.value === repoPlatform)
+    success(`Repo platform: ${repoPreset?.name || repoPlatform}`)
+  }
+
+  // Check CLIs for both platforms (deduped)
+  const platformsToCheck = [...new Set([backlogPlatform, repoPlatform])].filter(p => p !== 'none')
+  for (const p of platformsToCheck) {
+    const preset = platformsPreset.find(x => x.value === p)
+    if (preset?.cli) await checkPlatformCli(preset)
+  }
+
+  return { backlogPlatform, repoPlatform }
+}
+
+async function checkPlatformCli(platformPreset) {
+  const { cli } = platformPreset
+  header(`Step 4, Checking ${platformPreset.name} CLI`)
+
+  const hasCli = await commandExists(cli.command)
+  if (!hasCli) {
+    warn(`${cli.displayName} not found.`)
+    info(`Install from: ${cli.installUrl}`)
+    if (cli.authCheck?.commands?.length) {
+      console.log()
+      info('After installing, authenticate with:')
+      code(cli.authCheck.commands)
+    }
+    return
+  }
+  success(`${cli.displayName} available`)
+
+  if (cli.authCheck) await runAuthCheck(cli)
+  if (cli.extensionCheck) await runExtensionCheck(cli)
+}
+
+async function runAuthCheck(cli) {
+  try {
+    const result = await execa(cli.command, cli.authCheck.args, { reject: false })
+    if (result.exitCode === 0) {
+      success(`${cli.displayName} authenticated`)
+    } else {
+      warn(cli.authCheck.notAuthenticatedMessage)
+      code(cli.authCheck.commands)
+    }
+  } catch {
+    warn(`Could not check ${cli.command} auth status.`)
+  }
+}
+
+async function runExtensionCheck(cli) {
+  try {
+    const result = await execa(cli.command, cli.extensionCheck.args, { reject: false })
+    const hasExtension = result.stdout && result.stdout.includes(cli.extensionCheck.expectedOutput)
+
+    if (hasExtension) {
+      success(`${cli.extensionCheck.expectedOutput} extension installed`)
+    } else {
+      warn(cli.extensionCheck.missingMessage)
+      code(cli.extensionCheck.commands)
+    }
+  } catch {
+    warn(cli.extensionCheck.errorMessage)
+    code(cli.extensionCheck.commands)
+  }
+}

package/src/steps/source/index.js

@@ -0,0 +1,123 @@
+import { checkbox, select } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { header, info, success, warn } from '../../utils/exec.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const SOURCE_PRESET_PATH = path.resolve(__dirname, '../../presets/source.json')
+const sourcePreset = await fse.readJson(SOURCE_PRESET_PATH)
+
+async function listChildFolders(cwd) {
+  const entries = await fse.readdir(cwd)
+  const dirs = []
+
+  for (const name of entries) {
+    if (name.startsWith('.')) continue
+    const abs = path.join(cwd, name)
+    try {
+      const stat = await fse.stat(abs)
+      if (!stat.isDirectory()) continue
+      dirs.push({ name, abs })
+    } catch {
+      // ignore invalid entries
+    }
+  }
+
+  dirs.sort((a, b) => a.name.localeCompare(b.name))
+  return dirs
+}
+
+async function listParentFolders(cwd) {
+  const parent = path.resolve(cwd, '..')
+  const entries = await fse.readdir(parent)
+  const dirs = []
+
+  for (const name of entries) {
+    if (name.startsWith('.')) continue
+    const abs = path.join(parent, name)
+    try {
+      const stat = await fse.stat(abs)
+      if (!stat.isDirectory()) continue
+      if (path.resolve(abs) === path.resolve(cwd)) continue
+      dirs.push({ name, abs })
+    } catch {
+      // ignore invalid entries
+    }
+  }
+
+  dirs.sort((a, b) => a.name.localeCompare(b.name))
+  return dirs
+}
+
+export async function chooseSourceScope() {
+  header('Step 1, Source code scope')
+
+  const cwd = process.cwd()
+  info('Choose where agents should read source code from during init analysis.')
+
+  const mode = await select({
+    message: sourcePreset.message,
+    default: sourcePreset.default,
+    choices: sourcePreset.choices,
+  })
+
+  if (mode === 'current') {
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  if (mode === 'children') {
+    const childFolders = await listChildFolders(cwd)
+    if (childFolders.length === 0) {
+      warn('No child folders found in current directory. Falling back to current folder.')
+      success(`Source scope: ${cwd}`)
+      return { sourceMode: 'current', sourceRoots: [cwd] }
+    }
+
+    const selected = await checkbox({
+      message: sourcePreset.childrenSelectionMessage,
+      choices: childFolders.map(d => ({
+        name: `./${d.name}`,
+        value: d.abs,
+        checked: true,
+      })),
+      required: true,
+    })
+
+    if (!selected || selected.length === 0) {
+      warn('No folders selected. Falling back to current folder.')
+      success(`Source scope: ${cwd}`)
+      return { sourceMode: 'current', sourceRoots: [cwd] }
+    }
+
+    success(`Source scope: ${selected.map(p => path.basename(p)).join(', ')}`)
+    return { sourceMode: 'children-selected', sourceRoots: selected }
+  }
+
+  const parentFolders = await listParentFolders(cwd)
+  if (parentFolders.length === 0) {
+    warn('No sibling folders found in parent directory. Falling back to current folder.')
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  const selected = await checkbox({
+    message: sourcePreset.parentSelectionMessage,
+    choices: parentFolders.map(d => ({
+      name: `../${d.name}`,
+      value: d.abs,
+      checked: true,
+    })),
+    required: true,
+  })
+
+  if (!selected || selected.length === 0) {
+    warn('No folders selected. Falling back to current folder.')
+    success(`Source scope: ${cwd}`)
+    return { sourceMode: 'current', sourceRoots: [cwd] }
+  }
+
+  success(`Source scope: ${selected.map(p => path.basename(p)).join(', ')}`)
+  return { sourceMode: 'parent-selected', sourceRoots: selected }
+}

package/src/utils/copy.js

@@ -0,0 +1,108 @@
+import fse from 'fs-extra'
+import path from 'path'
+import { canUpdateManagedFile, hashFile, readUpdateManifest, recordManagedFile, writeUpdateManifest } from './update-manifest.js'
+
+// Folders never copied (skills handled separately by installSkills, .bootstrap is internal tooling)
+const ALWAYS_EXCLUDE = ['.bootstrap', 'skills', 'node_modules']
+
+// Files never overwritten even with forceOverwrite: user owns these.
+// The CLI ships templates, but init / the wizard / the user populate them
+// with project-specific content. Overwriting on update would destroy user work.
+const NEVER_OVERWRITE = [
+  `openspec${path.sep}config.yaml`,
+  'opencode.jsonc',
+]
+
+const MARKER_COMMANDS = new Set(['.opencode/commands/ops-review.md', '.opencode/commands/ops-backlog.md'])
+
+function isTemplateTest(relativePath) {
+  return relativePath.split(path.sep).join('/').startsWith('.opencode/plugins/') && relativePath.endsWith('.test.js')
+}
+
+export function isManagedContentPath(relativePath) {
+  const normalized = relativePath.split(path.sep).join('/')
+  if (normalized.startsWith('.opencode/plugins/')) return true
+  if (normalized === '.opencode/tui/pc-subagents.tsx') return true
+  if (normalized.startsWith('.opencode/commands/') && !MARKER_COMMANDS.has(normalized)) return true
+  return normalized === 'openspec/specs/.gitkeep' || normalized === 'openspec/changes/archive/.gitkeep'
+}
+
+/**
+ * Copy content/ directory to destination.
+ * Excludes:
+ *   - .agents/skills and .opencode/skills (handled separately)
+ *   - .bootstrap (internal tooling)
+ *   - node_modules
+ *   - DESIGN.md and ARCHITECTURE.md if ctx says they already exist (preserve user's files)
+ * @param {string} contentDir - absolute path to content/
+ * @param {string} destDir - absolute path to destination (project root)
+ * @param {'azure'|'github'} platform
+ * @param {{ hasDesign?: boolean, hasArchitecture?: boolean, updateMode?: boolean }} ctx
+ */
+export async function copyContent(contentDir, destDir, platform, ctx = {}) {
+  const manifest = ctx.updateMode ? await readUpdateManifest(destDir) : null
+  await fse.copy(contentDir, destDir, {
+    overwrite: ctx.updateMode || ctx.forceOverwrite || false,
+    filter: async (src) => {
+      const rel = path.relative(contentDir, src)
+      const parts = rel.split(path.sep)
+      if (parts.some(part => ALWAYS_EXCLUDE.includes(part))) return false
+      if (isTemplateTest(rel)) return false
+      if (ctx.hasDesign && rel === 'DESIGN.md') return false
+      if (ctx.hasArchitecture && rel === 'ARCHITECTURE.md') return false
+      // User-owned config files are never overwritten, even with forceOverwrite.
+      // The update command calls writeModelsToConfigs separately to set the
+      // model field in opencode.jsonc without destroying user additions.
+      if (NEVER_OVERWRITE.includes(rel)) return false
+      if (!ctx.updateMode) return true
+
+      const stat = await fse.stat(src)
+      if (stat.isDirectory()) return true
+      if (!isManagedContentPath(rel)) {
+        return !(await fse.pathExists(path.join(destDir, rel)))
+      }
+      return canUpdateManagedFile(rel, destDir, manifest)
+    },
+  })
+}
+
+export async function recordManagedContent(contentDir, destDir, { updateMode = false } = {}) {
+  const manifest = await readUpdateManifest(destDir)
+
+  async function walk(directory) {
+    for (const entry of await fse.readdir(directory, { withFileTypes: true })) {
+      const sourcePath = path.join(directory, entry.name)
+      const relativePath = path.relative(contentDir, sourcePath)
+      if (entry.isDirectory()) {
+        await walk(sourcePath)
+        continue
+      }
+      if (isTemplateTest(relativePath)) continue
+      if (!isManagedContentPath(relativePath)) continue
+
+      const destinationPath = path.join(destDir, relativePath)
+      if (!await fse.pathExists(destinationPath)) continue
+      const sourceHash = await hashFile(sourcePath)
+      const destinationHash = await hashFile(destinationPath)
+      const manifestPath = relativePath.split(path.sep).join('/')
+      const previousHash = manifest.files?.[manifestPath]
+      if (!updateMode || destinationHash === sourceHash || destinationHash === previousHash) {
+        await recordManagedFile(manifest, relativePath, sourcePath)
+      }
+    }
+  }
+
+  await walk(contentDir)
+  await writeUpdateManifest(manifest, destDir)
+}
+
+export async function findAiFiles(dir, files) {
+  const found = []
+  for (const file of files) {
+    const fullPath = path.join(dir, file)
+    if (await fse.pathExists(fullPath)) {
+      found.push(fullPath)
+    }
+  }
+  return found
+}

package/src/utils/exec-spinner.js

@@ -0,0 +1,47 @@
+import chalk from 'chalk'
+import ora from 'ora'
+
+// ── Screen / step state ──────────────────────────────────────────────────────
+
+const previousSteps = [];    // up to 2 completed steps, each is an array of lines
+let currentStepLines = [];   // lines accumulated in the current step
+let stepSpinner = null;      // ora spinner shown while step is working
+
+export function appendLine(line) {
+  currentStepLines.push(line);
+}
+
+export function stopSpinner() {
+  if (stepSpinner) {
+    stepSpinner.stop();
+    stepSpinner = null;
+  }
+}
+
+export function startSpinner(text = 'working...') {
+  stopSpinner();
+  stepSpinner = ora({ text: chalk.dim(text), color: 'red' }).start();
+}
+
+export function redraw() {
+  if (process.stdout.isTTY) console.clear();
+
+  // Show up to 2 previous steps dimmed
+  for (const stepLines of previousSteps) {
+    for (const line of stepLines) {
+      process.stdout.write(`${chalk.dim(line)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Current step output
+  for (const line of currentStepLines) {
+    process.stdout.write(`${line}\n`);
+  }
+}
+
+export function rotateStep() {
+  previousSteps.push(currentStepLines);
+  if (previousSteps.length > 2) previousSteps.shift();
+  currentStepLines = [];
+}

package/src/utils/exec.js

@@ -0,0 +1,134 @@
+import chalk from 'chalk'
+import { execa } from 'execa'
+import ora from 'ora'
+import { appendLine, redraw, rotateStep, startSpinner, stopSpinner } from './exec-spinner.js'
+import { MARKERS } from './terminal.js';
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Run a shell command with a spinner.
+ * Returns { success, stdout, stderr }
+ */
+export async function run(command, args = [], { label, cwd = process.cwd() } = {}) {
+  const spinner = ora(label ?? `${command} ${args.join(' ')}`).start();
+  try {
+    const result = await execa(command, args, { cwd, reject: false });
+    if (result.exitCode === 0) {
+      spinner.succeed();
+    } else {
+      spinner.fail();
+    }
+    return { success: result.exitCode === 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (err) {
+    spinner.fail();
+    return { success: false, stdout: '', stderr: err.message };
+  }
+}
+
+/**
+ * Check if a command is available on PATH.
+ * Returns true/false.
+ */
+export async function commandExists(command) {
+  try {
+    const result = await execa(command, ['--version'], { reject: false });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Print a section header, clears screen, shows previous step dimmed, starts new step.
+ */
+export function header(text) {
+  rotateStep();
+
+  const line1 = '';
+  const line2 = chalk.bold.hex('#fe3d57')(`━━ ${text}`);
+  const line3 = '';
+
+  appendLine(line1);
+  appendLine(line2);
+  appendLine(line3);
+
+  redraw();
+
+  startSpinner('working...');
+}
+
+/**
+ * Restart the step spinner after prompts or logs.
+ */
+export function loading(text = 'working...') {
+  startSpinner(text);
+}
+
+/**
+ * Print a success line.
+ */
+export function success(text) {
+  stopSpinner();
+  const line = chalk.green(`${MARKERS.OK_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print a warning line.
+ */
+export function warn(text) {
+  stopSpinner();
+  const line = chalk.yellow(`${MARKERS.WARN_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an error line.
+ */
+export function error(text) {
+  stopSpinner();
+  const line = chalk.red(`${MARKERS.ERROR_PREFIX}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an info line.
+ */
+export function info(text) {
+  stopSpinner();
+  const line = chalk.dim(`${MARKERS.EMPTY}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print an action prompt line (white bold, requires user interaction).
+ */
+export function prompt(text) {
+  stopSpinner();
+  const line = chalk.bold(`${MARKERS.EMPTY}${text}`);
+  appendLine(line);
+  console.log(line);
+}
+
+/**
+ * Print a code block.
+ */
+export function code(lines) {
+  stopSpinner();
+  appendLine('');
+  console.log();
+  for (const line of lines) {
+    const formatted = chalk.bgGray.white(
+      `${MARKERS.EMPTY}${line}${MARKERS.EMPTY}`,
+    );
+    appendLine(formatted);
+    console.log(formatted);
+  }
+  appendLine('');
+  console.log();
+}

package/src/utils/legacy-check.js

@@ -0,0 +1,30 @@
+import fse from 'fs-extra'
+import path from 'node:path'
+import { CONFIG_FILE, LEGACY_CONFIG_FILES, OPENCODE_DIR } from './paths.js'
+
+/**
+ * Detect a repo onboarded by opencode-onboard v1.x.
+ *
+ * v2 renamed both the state files and the `ob-` skill prefix, and it does not
+ * migrate: see the rename plan. Running against a v1 repo would otherwise fail
+ * silently in two places, because `patchFile` returns without logging when its
+ * markers are absent and the skill sync only removes stale directories under
+ * `forceOverwrite && !updateMode`. The result is a half-patched harness that
+ * still reports success, so refuse the run instead.
+ */
+export async function findLegacyInstall(cwd = process.cwd()) {
+  const opencodeDir = path.join(cwd, OPENCODE_DIR)
+  if (await fse.pathExists(path.join(opencodeDir, CONFIG_FILE))) return null
+
+  const found = []
+  for (const file of LEGACY_CONFIG_FILES) {
+    if (await fse.pathExists(path.join(opencodeDir, file))) found.push(`${OPENCODE_DIR}/${file}`)
+  }
+
+  const skillsDir = path.join(cwd, '.agents', 'skills')
+  const legacySkills = (await fse.readdir(skillsDir).catch(() => []))
+    .filter(entry => entry.startsWith('ob-'))
+
+  if (found.length === 0 && legacySkills.length === 0) return null
+  return { files: found, skills: legacySkills }
+}

package/src/utils/models-cache.js

@@ -0,0 +1,58 @@
+import fse from 'fs-extra'
+import path from 'path'
+import { parseModels } from './models-pricing.js'
+import { modelsCacheDir } from './paths.js'
+
+const CACHE_DIR = modelsCacheDir();
+const CACHE_FILE = path.join(CACHE_DIR, 'models-cache.json');
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const MODELS_URL = 'https://models.dev/api.json';
+
+async function loadCache() {
+  try {
+    if (!await fse.pathExists(CACHE_FILE)) return null;
+    const cache = await fse.readJson(CACHE_FILE);
+    if (!cache.timestamp || !cache.models) return null;
+    const age = Date.now() - cache.timestamp;
+    if (age > CACHE_TTL_MS) return null; // expired
+    return cache.models;
+  } catch {
+    return null;
+  }
+}
+
+async function saveCache(models) {
+  try {
+    await fse.ensureDir(CACHE_DIR);
+    await fse.writeJson(CACHE_FILE, { timestamp: Date.now(), models });
+  } catch {
+    // cache write failure is non-fatal
+  }
+}
+
+export async function fetchModels() {
+  // 1. Try cache first (fresh)
+  const cached = await loadCache();
+  if (cached) return { models: cached, source: 'cache' };
+
+  // 2. Try network
+  try {
+    const res = await fetch(MODELS_URL, { signal: AbortSignal.timeout(8000) });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json();
+    const models = parseModels(data);
+    await saveCache(models);
+    return { models, source: 'network' };
+  } catch {
+    // 3. Network failed, fall back to stale cache if available
+    try {
+      if (await fse.pathExists(CACHE_FILE)) {
+        const cache = await fse.readJson(CACHE_FILE);
+        if (cache.models?.length) return { models: cache.models, source: 'stale-cache' };
+      }
+    } catch {
+      // ignore
+    }
+    return { models: null, source: 'unavailable' };
+  }
+}

package/src/utils/models-pricing.js

@@ -0,0 +1,42 @@
+// Providers considered "canonical" for reference pricing, in priority order.
+// When a model's own provider has no cost (e.g. github-copilot shows $0),
+// we look up the same model name in these providers and attach canonicalCost.
+export const CANONICAL_PROVIDERS = ['anthropic', 'openai', 'google', 'mistral', 'meta', 'cohere'];
+
+export function parseModels(data) {
+  // Build name → canonical cost lookup from authoritative providers first
+  const canonicalCostByName = new Map();
+  for (const providerId of CANONICAL_PROVIDERS) {
+    const provider = data[providerId];
+    if (!provider?.models) continue;
+    for (const model of Object.values(provider.models)) {
+      if (!model.tool_call) continue;
+      const name = model.name;
+      if (name && model.cost?.input !== undefined && !canonicalCostByName.has(name)) {
+        canonicalCostByName.set(name, model.cost.input);
+      }
+    }
+  }
+
+  const models = [];
+  for (const [providerId, provider] of Object.entries(data)) {
+    if (!provider.models) continue;
+    for (const [modelId, model] of Object.entries(provider.models)) {
+      if (!model.tool_call) continue;
+      const name = model.name || modelId;
+      const cost = model.cost?.input;
+      const canonicalCost = canonicalCostByName.get(name);
+      models.push({
+        id: `${providerId}/${modelId}`,
+        name,
+        cost,
+        // canonicalCost: cost from the authoritative provider for this model name.
+        // Defined when cost !== canonicalCost (different provider, reseller, or $0 subscription).
+        canonicalCost: canonicalCost !== undefined && canonicalCost !== cost ? canonicalCost : undefined,
+        context: model.limit?.context,
+      });
+    }
+  }
+  models.sort((a, b) => (a.cost ?? Infinity) - (b.cost ?? Infinity));
+  return models;
+}