opencode-onboard 0.2.7 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-onboard",
-  "version": "0.2.7",
+  "version": "0.2.13",
   "description": "Prepare any brownfield codebase for AI agent workflows using OpenCode, OpenSpec, and ensemble orchestration.",
   "keywords": [
     "opencode",

package/src/index.js

@@ -1,26 +1,173 @@
 #!/usr/bin/env node
-import chalk from 'chalk'
-import { createRequire } from 'node:module'
-import { checkEnv } from './steps/check-env.js'
-import { checkPlatform } from './steps/check-platform.js'
-import { checkRtk } from './steps/check-rtk.js'
+import chalk from 'chalk'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import fse from 'fs-extra'
+import { checkEnv } from './steps/check-env.js'
+import { checkPlatform } from './steps/check-platform.js'
+import { checkRtk } from './steps/check-rtk.js'
 import { chooseModels } from './steps/choose-models.js'
 import { choosePlatform } from './steps/choose-platform.js'
 import { chooseSourceScope } from './steps/choose-source-scope.js'
 import { chooseSkillsProvider } from './steps/choose-skills-provider.js'
 import { cleanAiFiles } from './steps/clean-ai-files.js'
 import { copyContentStep } from './steps/copy-content.js'
-import { initOpenspec } from './steps/init-openspec.js'
+import { initOpenspec } from './steps/init-openspec.js'
 import { patchAgentsMd } from './steps/patch-agents-md.js'
+import { installQuota } from './steps/install-quota.js'
+import { installCaveman } from './steps/install-caveman.js'
+import { enableCavemanGuidance } from './steps/enable-caveman-guidance.js'
 import { installBrowser } from './steps/install-browser.js'
 import { writeOnboardConfig } from './steps/write-onboard-config.js'
-
-if (process.stdout.isTTY) console.clear()
-console.log()
-const require = createRequire(import.meta.url)
-const { version } = require('../package.json')
-const logo = chalk.hex('#fe3d57')
-const bannerLines = [
+import { loading } from './utils/exec.js'
+import { tokenOptimizationStep } from './steps/token-optimization.js'
+
+function printHelp(version) {
+  console.log(`opencode-onboard v${version}`)
+  console.log()
+  console.log('Usage:')
+  console.log('  npx opencode-onboard                Run full onboarding wizard')
+  console.log('  npx opencode-onboard <command>      Run a single step command')
+  console.log()
+  console.log('Commands:')
+  console.log('  clean           Run AI files cleanup step')
+  console.log('  platform        Run platform selection step')
+  console.log('  copy            Run content copy step')
+  console.log('  openspec        Run OpenSpec initialization step')
+  console.log('  skills          Run skills install step')
+  console.log('  models          Run models selection step')
+  console.log('  optimization    Run token optimization tools step')
+  console.log('  quota           Run opencode-quota installer step')
+  console.log('  rtk             Run rtk check step')
+  console.log('  caveman         Run caveman install + guidance steps')
+  console.log('  browser         Run opencode-browser installer step')
+  console.log('  metadata        Write onboarding metadata step')
+  console.log()
+  console.log('Options:')
+  console.log('  -h, --help      Show this help message')
+}
+
+async function readOnboardConfig() {
+  const cfgPath = path.join(process.cwd(), '.opencode', 'opencode-onboard.json')
+  if (!await fse.pathExists(cfgPath)) return null
+  try {
+    return await fse.readJson(cfgPath)
+  } catch {
+    return null
+  }
+}
+
+async function runSingleCommand(command) {
+  const saved = await readOnboardConfig()
+  const savedWizard = saved?.wizard ?? {}
+  const ctx = {
+    hasDesign: !!savedWizard?.preserved?.design,
+    hasArchitecture: !!savedWizard?.preserved?.architecture,
+    hasOpenspec: !!savedWizard?.preserved?.openspec,
+    sourceMode: savedWizard?.sourceMode ?? 'current',
+    sourceRoots: Array.isArray(savedWizard?.sourceRoots) ? savedWizard.sourceRoots : [],
+  }
+  const platform = savedWizard?.platform
+  const resolvedPlatform = platform === 'azure' || platform === 'github' ? platform : 'github'
+
+  if (command === 'clean') {
+    await cleanAiFiles()
+    return true
+  }
+
+  if (command === 'platform') {
+    await choosePlatform()
+    return true
+  }
+
+  if (command === 'copy') {
+    await copyContentStep(resolvedPlatform, ctx)
+    await patchAgentsMd(ctx)
+    return true
+  }
+
+  if (command === 'openspec') {
+    await initOpenspec()
+    return true
+  }
+
+  if (command === 'skills') {
+    await chooseSkillsProvider()
+    return true
+  }
+
+  if (command === 'models') {
+    await chooseModels()
+    return true
+  }
+
+  if (command === 'optimization') {
+    await tokenOptimizationStep({ skillsProvider: savedWizard?.additionalSkillsProvider })
+    return true
+  }
+
+  if (command === 'quota') {
+    await installQuota()
+    return true
+  }
+
+  if (command === 'rtk') {
+    await checkRtk()
+    return true
+  }
+
+  if (command === 'caveman') {
+    const caveman = await installCaveman({ skillsProvider: savedWizard?.additionalSkillsProvider })
+    await enableCavemanGuidance(caveman)
+    return true
+  }
+
+  if (command === 'browser') {
+    await installBrowser()
+    return true
+  }
+
+  if (command === 'metadata') {
+    await writeOnboardConfig({
+      ...ctx,
+      platform: resolvedPlatform,
+      additionalSkillsProvider: savedWizard?.additionalSkillsProvider ?? 'none',
+      planModel: savedWizard?.models?.plan ?? null,
+      buildModel: savedWizard?.models?.build ?? null,
+      fastModel: savedWizard?.models?.fast ?? null,
+      optionalTools: savedWizard?.optionalTools ?? null,
+      cavemanGuidance: savedWizard?.cavemanGuidance ?? null,
+    })
+    return true
+  }
+
+  return false
+}
+
+if (process.stdout.isTTY) console.clear()
+console.log()
+const require = createRequire(import.meta.url)
+const { version } = require('../package.json')
+const args = process.argv.slice(2)
+
+if (args.includes('-h') || args.includes('--help')) {
+  printHelp(version)
+  process.exit(0)
+}
+
+if (args.length > 0) {
+  const ok = await runSingleCommand(args[0])
+  if (!ok) {
+    console.log(chalk.red(`Unknown command: ${args[0]}`))
+    console.log()
+    printHelp(version)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
+const logo = chalk.hex('#fe3d57')
+const bannerLines = [
   logo('                             '),
   logo('        ▒▒▒▒▒▒▒▒▒▒▒▒▒        '),
   logo('        ▒▒▓       ▓▒▓        '),
@@ -58,42 +205,55 @@ if (process.stdin.isTTY) {
 }
 
 try {
-  // 1. Check Node + pnpm
-  await checkEnv()
-
+  // 1. Check Node + pnpm
+  await checkEnv()
+  loading('preparing next step...')
+
   // 2. Choose source code scope for init analysis
   const scope = await chooseSourceScope()
+  loading('preparing next step...')
 
   // 3. Clean existing AI config files, detect preserved state
   const preserve = await cleanAiFiles()
   const ctx = { ...preserve, ...scope }
+  loading('preparing next step...')
 
   // 4. Choose platform
   const platform = await choosePlatform()
+  loading('preparing next step...')
 
   // 5. Check platform CLI (az or gh)
   await checkPlatform(platform)
+  loading('preparing next step...')
 
   // 6. Copy content
   await copyContentStep(platform, ctx)
+  loading('preparing next step...')
 
   // 6b. Patch AGENTS.md to skip steps for already-existing files
   await patchAgentsMd(ctx)
+  loading('preparing next step...')
 
   // 7. Init OpenSpec
   await initOpenspec()
+  loading('preparing next step...')
 
   // 8. Install skills
   const skillsSelection = await chooseSkillsProvider()
+  loading('preparing next step...')
 
   // 9. Choose models
   const selectedModels = await chooseModels()
+  loading('preparing next step...')
 
-  // 10. Check RTK
-  await checkRtk()
+  // 10. Token optimization tools
+  const tokenOpt = await tokenOptimizationStep({ skillsProvider: skillsSelection.additionalSkillsProvider })
+  const { rtk, quota, caveman, cavemanGuidance } = tokenOpt
+  loading('preparing next step...')
 
   // 11. Install opencode-browser
   await installBrowser()
+  loading('preparing next step...')
 
   // 12. Write onboarding metadata
   await writeOnboardConfig({
@@ -101,6 +261,8 @@ try {
     platform,
     ...skillsSelection,
     ...selectedModels,
+    optionalTools: { rtk, quota, caveman },
+    cavemanGuidance,
   })
 
   // Done

package/src/steps/__tests__/check-rtk.test.js

@@ -3,6 +3,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 vi.mock('../../utils/exec.js', () => ({
   commandExists: vi.fn(),
   header: vi.fn(),
+  loading: vi.fn(),
   success: vi.fn(),
   warn: vi.fn(),
   info: vi.fn(),
@@ -20,7 +21,7 @@ describe('checkRtk()', () => {
   it('prints success when rtk is available', async () => {
     commandExists.mockResolvedValue(true)
 
-    await checkRtk()
+    await checkRtk({ skipPrompt: true })
 
     expect(success).toHaveBeenCalledWith('rtk is available')
     expect(warn).not.toHaveBeenCalled()
@@ -29,7 +30,7 @@ describe('checkRtk()', () => {
   it('prints warning with install instructions when rtk is not found', async () => {
     commandExists.mockResolvedValue(false)
 
-    await checkRtk()
+    await checkRtk({ skipPrompt: true })
 
     expect(warn).toHaveBeenCalledWith('rtk not found on PATH.')
     expect(success).not.toHaveBeenCalled()

package/src/steps/__tests__/clean-ai-files.test.js

@@ -39,7 +39,7 @@ describe('cleanAiFiles()', () => {
 
     await cleanAiFiles()
 
-    expect(success).toHaveBeenCalledWith('No existing AI config files found')
+    expect(success).toHaveBeenCalledWith('No existing AI config files to remove')
   })
 
   it('removes found AI files after Enter', async () => {

package/src/steps/__tests__/copy-content.test.js

@@ -34,7 +34,8 @@ describe('copyContentStep()', () => {
     expect(copyContent).toHaveBeenCalledWith(
       expect.stringContaining('content'),
       process.cwd(),
-      'github'
+      'github',
+      {}
     )
     expect(success).toHaveBeenCalledWith('Files copied to project root')
   })
@@ -47,7 +48,8 @@ describe('copyContentStep()', () => {
     expect(copyContent).toHaveBeenCalledWith(
       expect.stringContaining('content'),
       process.cwd(),
-      'azure'
+      'azure',
+      {}
     )
   })
 

package/src/steps/__tests__/token-optimization.test.js

@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@inquirer/prompts', () => ({
+  checkbox: vi.fn(),
+}))
+
+vi.mock('../../utils/exec.js', () => ({
+  header: vi.fn(),
+  info: vi.fn(),
+  loading: vi.fn(),
+  success: vi.fn(),
+  warn: vi.fn(),
+}))
+
+vi.mock('../check-rtk.js', () => ({
+  checkRtk: vi.fn(),
+}))
+
+vi.mock('../install-quota.js', () => ({
+  installQuota: vi.fn(),
+}))
+
+vi.mock('../install-caveman.js', () => ({
+  installCaveman: vi.fn(),
+}))
+
+vi.mock('../enable-caveman-guidance.js', () => ({
+  enableCavemanGuidance: vi.fn(),
+}))
+
+import { checkbox } from '@inquirer/prompts'
+import { warn } from '../../utils/exec.js'
+import { checkRtk } from '../check-rtk.js'
+import { installQuota } from '../install-quota.js'
+import { installCaveman } from '../install-caveman.js'
+import { enableCavemanGuidance } from '../enable-caveman-guidance.js'
+import { tokenOptimizationStep } from '../token-optimization.js'
+
+describe('tokenOptimizationStep()', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('runs all optimizations by default selection', async () => {
+    checkbox.mockResolvedValue(['rtk', 'quota', 'caveman'])
+    checkRtk.mockResolvedValue({ optedIn: true, checked: true, available: true })
+    installQuota.mockResolvedValue({ optedIn: true, installed: true })
+    installCaveman.mockResolvedValue({ optedIn: true, installed: true })
+    enableCavemanGuidance.mockResolvedValue({ enabled: true })
+
+    const result = await tokenOptimizationStep()
+
+    expect(checkRtk).toHaveBeenCalledWith({ skipHeader: true, skipPrompt: true })
+    expect(installQuota).toHaveBeenCalledWith({ skipHeader: true, skipPrompt: true })
+    expect(installCaveman).toHaveBeenCalledWith({ skipHeader: true, skipPrompt: true })
+    expect(enableCavemanGuidance).toHaveBeenCalledWith({ optedIn: true, installed: true })
+    expect(result.rtk.available).toBe(true)
+    expect(result.quota.installed).toBe(true)
+    expect(result.caveman.installed).toBe(true)
+    expect(result.cavemanGuidance.enabled).toBe(true)
+  })
+
+  it('skips all tools when nothing is selected', async () => {
+    checkbox.mockResolvedValue([])
+
+    const result = await tokenOptimizationStep()
+
+    expect(checkRtk).not.toHaveBeenCalled()
+    expect(installQuota).not.toHaveBeenCalled()
+    expect(installCaveman).not.toHaveBeenCalled()
+    expect(enableCavemanGuidance).not.toHaveBeenCalled()
+    expect(warn).toHaveBeenCalledWith('No token optimization tools selected')
+    expect(result.rtk.optedIn).toBe(false)
+    expect(result.quota.optedIn).toBe(false)
+    expect(result.caveman.optedIn).toBe(false)
+    expect(result.cavemanGuidance.enabled).toBe(false)
+  })
+})

package/src/steps/check-rtk.js

@@ -1,13 +1,30 @@
-import { code, commandExists, header, info, success, warn } from '../utils/exec.js'
+import { confirm } from '@inquirer/prompts'
+import { code, commandExists, header, info, loading, success, warn } from '../utils/exec.js'
 
-export async function checkRtk() {
-  header('Step 10, Checking rtk')
+export async function checkRtk(options = {}) {
+  if (!options.skipHeader) header('Checking rtk')
+
+  let shouldCheck = true
+  if (!options.skipPrompt) {
+    info('Recommended: install and verify rtk for safer agent CLI command execution.')
+    shouldCheck = await confirm({
+      message: 'Check rtk now?',
+      default: true,
+    })
+  }
+
+  if (!shouldCheck) {
+    warn('Skipped rtk check (you can install it later)')
+    return { optedIn: false, checked: false, available: false }
+  }
+
+  loading('checking rtk...')
 
   const available = await commandExists('rtk')
 
   if (available) {
     success('rtk is available')
-    return
+    return { optedIn: true, checked: true, available: true }
   }
 
   warn('rtk not found on PATH.')
@@ -17,4 +34,5 @@ export async function checkRtk() {
   console.log()
   info('After installing, verify with:')
   code(['rtk --version'])
+  return { optedIn: true, checked: true, available: false }
 }

package/src/steps/choose-source-scope.js

@@ -65,7 +65,7 @@ export async function chooseSourceScope() {
     choices: parentFolders.map(d => ({
       name: `../${d.name}`,
       value: d.abs,
-      checked: false,
+      checked: true,
     })),
     required: true,
   })

package/src/steps/enable-caveman-guidance.js

@@ -0,0 +1,93 @@
+import path from 'node:path'
+import fse from 'fs-extra'
+import { info, success, warn } from '../utils/exec.js'
+
+const MARKER_START = '<!-- CAVEMAN-GUIDANCE-START -->'
+const MARKER_END = '<!-- CAVEMAN-GUIDANCE-END -->'
+
+const AGENTS_BLOCK = `${MARKER_START}
+## Caveman Mode (Optional)
+
+If caveman is installed, prefer concise responses by default to reduce token usage while keeping full technical accuracy.
+
+Treat any of these as a direct trigger to enable concise style:
+- "talk like caveman"
+- "caveman mode"
+- "less tokens please"
+
+When enabled:
+- Keep explanations short and direct
+- Prioritize exact commands, paths, and outcomes
+- Avoid filler, greetings, and repeated context
+
+The user can disable it with phrases like: "normal mode" or "stop caveman".
+${MARKER_END}`
+
+const OPSX_BLOCK = `${MARKER_START}
+## Caveman Output Style
+
+If the user requests "talk like caveman", "caveman mode", or "less tokens please", keep all status updates concise:
+- Report only key actions, blockers, and next commands
+- Keep completion updates brief and factual
+- Preserve technical precision; compress wording only
+${MARKER_END}`
+
+async function appendBlockIfMissing(filePath, block) {
+  if (!await fse.pathExists(filePath)) return { ok: false, reason: 'missing-file' }
+
+  const current = await fse.readFile(filePath, 'utf-8')
+  if (current.includes(MARKER_START)) return { ok: true, changed: false }
+
+  const next = `${current.replace(/\s*$/, '')}\n\n${block}\n`
+  await fse.writeFile(filePath, next, 'utf-8')
+  return { ok: true, changed: true }
+}
+
+export async function enableCavemanGuidance(cavemanResult) {
+  if (!cavemanResult?.installed) {
+    info('Caveman guidance skipped (caveman not installed)')
+    return { enabled: false }
+  }
+
+  const targets = [
+    { rel: 'AGENTS.md', block: AGENTS_BLOCK },
+  ]
+
+  const commandsDir = path.join(process.cwd(), '.opencode', 'commands')
+  if (await fse.pathExists(commandsDir)) {
+    const entries = await fse.readdir(commandsDir)
+    for (const name of entries) {
+      if (!/^opsx-.*\.md$/i.test(name)) continue
+      targets.push({ rel: path.join('.opencode', 'commands', name), block: OPSX_BLOCK })
+    }
+  }
+
+  const skillsDir = path.join(process.cwd(), '.opencode', 'skills')
+  if (await fse.pathExists(skillsDir)) {
+    const skillEntries = await fse.readdir(skillsDir)
+    for (const dirName of skillEntries) {
+      if (!/^openspec-/i.test(dirName)) continue
+      targets.push({ rel: path.join('.opencode', 'skills', dirName, 'SKILL.md'), block: OPSX_BLOCK })
+    }
+  }
+
+  let changedCount = 0
+  for (const target of targets) {
+    const abs = path.join(process.cwd(), target.rel)
+    try {
+      const res = await appendBlockIfMissing(abs, target.block)
+      if (!res.ok) {
+        warn(`Could not apply caveman guidance to ${target.rel} (${res.reason})`)
+      } else if (res.changed) {
+        changedCount++
+      }
+    } catch (err) {
+      warn(`Could not apply caveman guidance to ${target.rel}: ${err.message}`)
+    }
+  }
+
+  if (changedCount > 0) success('Caveman guidance enabled in AGENTS/OpenSpec prompts')
+  else info('Caveman guidance already present')
+
+  return { enabled: true, patchedFiles: changedCount }
+}

package/src/steps/install-caveman.js

@@ -0,0 +1,43 @@
+import { execa } from 'execa'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { header, success, warn, error, loading, info } from '../utils/exec.js'
+
+const SKILLS_LOCK_CANDIDATES = [
+  'skills-lock.json',
+  '.skills-lock.json',
+  '.skills/skills-lock.json',
+]
+
+export async function installCaveman(options = {}) {
+  if (!options.skipHeader) header('Installing caveman')
+
+  loading('installing caveman...')
+
+  try {
+    info('Installing caveman via npx skills')
+    const result = await execa('npx', ['skills', 'add', 'JuliusBrussee/caveman/caveman', '-a', 'opencode', '--yes'], {
+      reject: false,
+      timeout: 600000,
+      stdio: 'pipe',
+    })
+
+    if (result.exitCode === 0) {
+      if (options.skillsProvider !== 'npx-skills') {
+        for (const rel of SKILLS_LOCK_CANDIDATES) {
+          const abs = path.join(process.cwd(), rel)
+          if (await fse.pathExists(abs)) await fse.remove(abs)
+        }
+      }
+      success('caveman installed')
+      return { optedIn: true, installed: true }
+    } else {
+      if (result.stderr?.trim()) warn(result.stderr.trim().split('\n').slice(-3).join('\n'))
+      warn('caveman install exited with non-zero code')
+      return { optedIn: true, installed: false }
+    }
+  } catch (err) {
+    error(`Failed to install caveman: ${err.message}`)
+    return { optedIn: true, installed: false }
+  }
+}

package/src/steps/install-quota.js

@@ -0,0 +1,82 @@
+import { confirm } from '@inquirer/prompts'
+import fse from 'fs-extra'
+import path from 'node:path'
+import { header, success, warn, error, loading, info } from '../utils/exec.js'
+
+const PLUGIN = '@slkiser/opencode-quota'
+
+function ensurePlugin(config) {
+  if (!Array.isArray(config.plugin)) config.plugin = []
+  if (!config.plugin.includes(PLUGIN)) config.plugin.push(PLUGIN)
+}
+
+function addIfMissing(target, key, value) {
+  if (!(key in target)) target[key] = value
+}
+
+export async function installQuota(options = {}) {
+  if (!options.skipHeader) header('Installing opencode-quota')
+
+  let shouldInstall = true
+  if (!options.skipPrompt && process.stdin.isTTY) {
+    const timeoutMs = 20000
+    const choice = await Promise.race([
+      confirm({
+        message: 'Install opencode-quota with recommended defaults?',
+        default: true,
+      }),
+      new Promise(resolve => setTimeout(() => resolve(true), timeoutMs)),
+    ])
+    shouldInstall = choice !== false
+  }
+
+  if (!shouldInstall) {
+    warn('Skipped opencode-quota installation')
+    return { optedIn: false, installed: false }
+  }
+
+  loading('configuring opencode-quota...')
+
+  try {
+    const opencodeDir = path.join(process.cwd(), '.opencode')
+    const opencodePath = path.join(opencodeDir, 'opencode.json')
+    const tuiPath = path.join(opencodeDir, 'tui.json')
+    const quotaDir = path.join(opencodeDir, 'opencode-quota')
+    const quotaPath = path.join(quotaDir, 'quota-toast.json')
+
+    const opencode = await fse.pathExists(opencodePath)
+      ? await fse.readJson(opencodePath)
+      : { $schema: 'https://opencode.ai/config.json' }
+
+    const tui = await fse.pathExists(tuiPath)
+      ? await fse.readJson(tuiPath)
+      : { $schema: 'https://opencode.ai/tui.json' }
+
+    ensurePlugin(opencode)
+    ensurePlugin(tui)
+
+    await fse.ensureDir(opencodeDir)
+    await fse.writeJson(opencodePath, opencode, { spaces: 2 })
+    await fse.writeJson(tuiPath, tui, { spaces: 2 })
+
+    const quotaConfig = await fse.pathExists(quotaPath)
+      ? await fse.readJson(quotaPath)
+      : {}
+
+    // Keep installer semantics append-only: add defaults only when missing.
+    addIfMissing(quotaConfig, 'enabledProviders', 'auto')
+    addIfMissing(quotaConfig, 'formatStyle', 'singleWindow')
+    addIfMissing(quotaConfig, 'percentDisplayMode', 'used')
+    addIfMissing(quotaConfig, 'showSessionTokens', true)
+
+    await fse.ensureDir(quotaDir)
+    await fse.writeJson(quotaPath, quotaConfig, { spaces: 2 })
+
+    success('opencode-quota configured (manual setup)')
+    info('Restart OpenCode and run /quota to verify')
+    return { optedIn: true, installed: true }
+  } catch (err) {
+    error(`Failed to configure opencode-quota: ${err.message}`)
+    return { optedIn: true, installed: false }
+  }
+}