devvami 1.0.0 → 1.1.1

package/src/commands/prompts/browse.js

@@ -0,0 +1,164 @@
+import { Command, Args, Flags } from '@oclif/core'
+import ora from 'ora'
+import chalk from 'chalk'
+import { select } from '@inquirer/prompts'
+import { searchSkills } from '../../services/skills-sh.js'
+import { fetchAwesomeEntries, AWESOME_CATEGORIES } from '../../services/awesome-copilot.js'
+import { formatSkillTable, formatAwesomeTable } from '../../formatters/prompts.js'
+import { DvmiError } from '../../utils/errors.js'
+
+/** @import { Skill, AwesomeEntry } from '../../types.js' */
+
+const VALID_SOURCES = ['skills', 'awesome']
+
+export default class PromptsBrowse extends Command {
+  static description = 'Browse prompts and skills from external sources (skills.sh, awesome-copilot)'
+
+  static examples = [
+    '<%= config.bin %> prompts browse skills --query refactor',
+    '<%= config.bin %> prompts browse skills --query testing --json',
+    '<%= config.bin %> prompts browse awesome',
+    '<%= config.bin %> prompts browse awesome --category agents',
+    '<%= config.bin %> prompts browse awesome --category instructions --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static args = {
+    source: Args.string({
+      description: `Source to browse: ${VALID_SOURCES.join(' | ')}`,
+      required: true,
+      options: VALID_SOURCES,
+    }),
+  }
+
+  static flags = {
+    query: Flags.string({
+      char: 'q',
+      description: 'Search query (only applies to skills source)',
+    }),
+    category: Flags.string({
+      char: 'c',
+      description: `awesome-copilot category (${AWESOME_CATEGORIES.join(', ')})`,
+      default: 'instructions',
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(PromptsBrowse)
+    const isJson = flags.json
+    const source = args.source
+
+    if (!VALID_SOURCES.includes(source)) {
+      this.error(`Invalid source: "${source}". Must be one of: ${VALID_SOURCES.join(', ')}`, {
+        exit: 1,
+        suggestions: VALID_SOURCES.map((s) => `dvmi prompts browse ${s}`),
+      })
+    }
+
+    const spinner = isJson
+      ? null
+      : ora({
+          spinner: 'arc',
+          color: false,
+          text: chalk.hex('#FF6B2B')(
+            source === 'skills' ? 'Searching skills.sh...' : `Fetching awesome-copilot (${flags.category})...`,
+          ),
+        }).start()
+
+    if (source === 'skills') {
+      if (!flags.query || flags.query.length < 2) {
+        this.error('skills.sh requires a search query (min 2 characters)', {
+          exit: 1,
+          suggestions: ['dvmi prompts browse skills --query refactor'],
+        })
+      }
+
+      /** @type {Skill[]} */
+      let skills
+      try {
+        skills = await searchSkills(flags.query ?? '', 50)
+      } catch (err) {
+        spinner?.fail()
+        if (err instanceof DvmiError) {
+          this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+        }
+        throw err
+      }
+
+      spinner?.stop()
+
+      if (isJson) {
+        return { skills, total: skills.length }
+      }
+
+      this.log(
+        chalk.bold('\nSkills') +
+          (flags.query ? chalk.dim(`  —  query: "${flags.query}"`) : '') +
+          chalk.dim(`  (${skills.length})\n`),
+      )
+      this.log(formatSkillTable(skills))
+
+      return { skills, total: skills.length }
+    }
+
+    // source === 'awesome'
+    const category = flags.category
+
+    if (!AWESOME_CATEGORIES.includes(category)) {
+      this.error(`Invalid category: "${category}". Valid: ${AWESOME_CATEGORIES.join(', ')}`, {
+        exit: 1,
+      })
+    }
+
+    /** @type {AwesomeEntry[]} */
+    let entries
+    try {
+      entries = await fetchAwesomeEntries(category)
+    } catch (err) {
+      spinner?.fail()
+      if (err instanceof DvmiError) {
+        this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+      }
+      throw err
+    }
+
+    spinner?.stop()
+
+    if (isJson) {
+      return { entries, total: entries.length, category }
+    }
+
+    this.log(
+      chalk.bold('\nAwesome Copilot') +
+        chalk.dim(`  —  category: `) +
+        chalk.hex('#4A9EFF')(category) +
+        chalk.dim(`  (${entries.length})\n`),
+    )
+    this.log(formatAwesomeTable(entries, category))
+    this.log('')
+
+    if (entries.length > 0) {
+      try {
+        const choices = entries.map((e) => ({ name: `${e.name}  ${chalk.dim(e.url)}`, value: e }))
+        choices.push({ name: chalk.dim('← Exit'), value: /** @type {AwesomeEntry} */ (null) })
+
+        const selected = await select({
+          message: 'Select an entry to view its URL (or Exit):',
+          choices,
+        })
+
+        if (selected) {
+          this.log(`\n${chalk.bold(selected.name)}\n${chalk.hex('#4A9EFF')(selected.url)}\n`)
+          if (selected.description) {
+            this.log(chalk.white(selected.description) + '\n')
+          }
+        }
+      } catch {
+        // User pressed Ctrl+C — exit gracefully
+      }
+    }
+
+    return { entries, total: entries.length, category }
+  }
+}

package/src/commands/prompts/download.js

@@ -0,0 +1,154 @@
+import { Command, Args, Flags } from '@oclif/core'
+import ora from 'ora'
+import chalk from 'chalk'
+import { select, confirm } from '@inquirer/prompts'
+import { join } from 'node:path'
+import { listPrompts, downloadPrompt } from '../../services/prompts.js'
+import { loadConfig } from '../../services/config.js'
+import { DvmiError } from '../../utils/errors.js'
+
+/** @import { Prompt } from '../../types.js' */
+
+const DEFAULT_PROMPTS_DIR = '.prompts'
+
+export default class PromptsDownload extends Command {
+  static description = 'Download a prompt from your personal repository to .prompts/'
+
+  static examples = [
+    '<%= config.bin %> prompts download',
+    '<%= config.bin %> prompts download coding/refactor-prompt.md',
+    '<%= config.bin %> prompts download coding/refactor-prompt.md --overwrite',
+    '<%= config.bin %> prompts download --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static args = {
+    path: Args.string({
+      description: 'Relative path of the prompt in the repository (e.g. coding/refactor-prompt.md)',
+      required: false,
+    }),
+  }
+
+  static flags = {
+    overwrite: Flags.boolean({
+      description: 'Overwrite existing local file without prompting',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(PromptsDownload)
+    const isJson = flags.json
+
+    // Determine local prompts directory from config or default to cwd/.prompts
+    let config = {}
+    try {
+      config = await loadConfig()
+    } catch {
+      /* use defaults */
+    }
+    const localDir =
+      process.env.DVMI_PROMPTS_DIR ?? config.promptsDir ?? join(process.cwd(), DEFAULT_PROMPTS_DIR)
+
+    // Resolve path interactively if not provided (only in interactive mode)
+    let relativePath = args.path
+    if (!relativePath) {
+      if (isJson) {
+        this.error('Prompt path is required in --json mode', {
+          exit: 1,
+          suggestions: ['Run `dvmi prompts download <path> --json`'],
+        })
+      }
+
+      const spinner = ora({
+        spinner: 'arc',
+        color: false,
+        text: chalk.hex('#FF6B2B')('Fetching prompts...'),
+      }).start()
+
+      /** @type {Prompt[]} */
+      let prompts
+      try {
+        prompts = await listPrompts()
+      } catch (err) {
+        spinner.fail()
+        if (err instanceof DvmiError) {
+          this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+        }
+        throw err
+      }
+      spinner.stop()
+
+      if (prompts.length === 0) {
+        this.log(chalk.yellow('No prompts found in the repository.'))
+        return { downloaded: [], skipped: [] }
+      }
+
+      const choices = prompts.map((p) => ({
+        name: `${p.path}  ${chalk.dim(p.title)}`,
+        value: p.path,
+      }))
+      relativePath = await select({ message: 'Select a prompt to download:', choices })
+    }
+
+    // Attempt download (skips automatically if file exists and --overwrite not set)
+    const spinner = isJson
+      ? null
+      : ora({
+          spinner: 'arc',
+          color: false,
+          text: chalk.hex('#FF6B2B')(`Downloading ${relativePath}...`),
+        }).start()
+
+    let result
+    try {
+      result = await downloadPrompt(relativePath, localDir, { overwrite: flags.overwrite })
+    } catch (err) {
+      spinner?.fail()
+      if (err instanceof DvmiError) {
+        this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+      }
+      throw err
+    }
+
+    spinner?.stop()
+
+    // Conflict: file exists and user didn't pass --overwrite → ask interactively
+    if (result.skipped && !flags.overwrite && !isJson) {
+      const shouldOverwrite = await confirm({
+        message: chalk.yellow(`File already exists at ${result.path}. Overwrite?`),
+        default: false,
+      })
+      if (shouldOverwrite) {
+        try {
+          result = await downloadPrompt(relativePath, localDir, { overwrite: true })
+        } catch (err) {
+          if (err instanceof DvmiError) {
+            this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+          }
+          throw err
+        }
+      }
+    }
+
+    if (isJson) {
+      return {
+        downloaded: result.skipped ? [] : [result.path],
+        skipped: result.skipped ? [result.path] : [],
+      }
+    }
+
+    if (result.skipped) {
+      this.log(chalk.dim(`Skipped (already exists): ${result.path}`))
+      this.log(chalk.dim('  Run with --overwrite to replace it.'))
+    } else {
+      this.log(chalk.green(`✓ Downloaded: ${result.path}`))
+    }
+
+    return {
+      downloaded: result.skipped ? [] : [result.path],
+      skipped: result.skipped ? [result.path] : [],
+    }
+  }
+}

package/src/commands/prompts/install-speckit.js

@@ -0,0 +1,97 @@
+import { Command, Flags } from '@oclif/core'
+import ora from 'ora'
+import chalk from 'chalk'
+import { loadConfig } from '../../services/config.js'
+import { isUvInstalled, isSpecifyInstalled, installSpecifyCli, runSpecifyInit } from '../../services/speckit.js'
+import { DvmiError } from '../../utils/errors.js'
+
+/**
+ * Map from dvmi's `aiTool` config values to spec-kit's `--ai` flag values.
+ * @type {Record<string, string>}
+ */
+const AI_TOOL_MAP = {
+  opencode: 'opencode',
+  copilot: 'copilot',
+}
+
+export default class PromptsInstallSpeckit extends Command {
+  static description = 'Install spec-kit (specify-cli) and run `specify init` to set up Spec-Driven Development'
+
+  static examples = [
+    '<%= config.bin %> prompts install-speckit',
+    '<%= config.bin %> prompts install-speckit --ai opencode',
+    '<%= config.bin %> prompts install-speckit --force',
+    '<%= config.bin %> prompts install-speckit --reinstall',
+  ]
+
+  static flags = {
+    ai: Flags.string({
+      description:
+        'AI agent to pass to `specify init --ai` (defaults to the aiTool set in `dvmi init`)',
+      options: ['opencode', 'copilot', 'claude', 'gemini', 'cursor-agent', 'codex', 'windsurf', 'kiro-cli', 'amp'],
+    }),
+    force: Flags.boolean({
+      char: 'f',
+      description: 'Pass --force to `specify init` (safe to run in a non-empty directory)',
+      default: false,
+    }),
+    reinstall: Flags.boolean({
+      description: 'Reinstall specify-cli even if it is already installed',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(PromptsInstallSpeckit)
+
+    // ── 1. Require uv ────────────────────────────────────────────────────────
+    if (!(await isUvInstalled())) {
+      this.error('uv is not installed — spec-kit requires the uv Python package manager', {
+        exit: 1,
+        suggestions: ['Install uv: https://docs.astral.sh/uv/getting-started/installation/'],
+      })
+    }
+
+    // ── 2. Install specify-cli (skip if already present unless --reinstall) ──
+    const alreadyInstalled = await isSpecifyInstalled()
+
+    if (!alreadyInstalled || flags.reinstall) {
+      const label = alreadyInstalled ? 'Reinstalling specify-cli...' : 'Installing specify-cli...'
+      const spinner = ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')(label) }).start()
+
+      try {
+        await installSpecifyCli({ force: flags.reinstall })
+        spinner.succeed(chalk.green('specify-cli installed'))
+      } catch (err) {
+        spinner.fail()
+        if (err instanceof DvmiError) {
+          this.error(err.message, { exit: 1, suggestions: [err.hint] })
+        }
+        throw err
+      }
+    } else {
+      this.log(chalk.dim('specify-cli already installed'))
+    }
+
+    // ── 3. Resolve --ai flag (flag > config > let specify prompt) ────────────
+    let aiFlag = flags.ai
+    if (!aiFlag) {
+      const config = await loadConfig()
+      aiFlag = config.aiTool ? (AI_TOOL_MAP[config.aiTool] ?? undefined) : undefined
+    }
+
+    // ── 4. Run `specify init --here` (interactive — inherits stdio) ──────────
+    this.log('')
+    this.log(chalk.bold('Running specify init — follow the prompts to set up your project:'))
+    this.log('')
+
+    try {
+      await runSpecifyInit(process.cwd(), { ai: aiFlag, force: flags.force })
+    } catch (err) {
+      if (err instanceof DvmiError) {
+        this.error(err.message, { exit: 1, suggestions: [err.hint] })
+      }
+      throw err
+    }
+  }
+}

package/src/commands/prompts/list.js

@@ -0,0 +1,107 @@
+import { Command, Flags } from '@oclif/core'
+import ora from 'ora'
+import chalk from 'chalk'
+import { select } from '@inquirer/prompts'
+import { listPrompts } from '../../services/prompts.js'
+import { formatPromptTable, formatPromptBody } from '../../formatters/prompts.js'
+import { DvmiError } from '../../utils/errors.js'
+
+/** @import { Prompt } from '../../types.js' */
+
+export default class PromptsList extends Command {
+  static description = 'List prompts from your personal prompt repository'
+
+  static examples = [
+    '<%= config.bin %> prompts list',
+    '<%= config.bin %> prompts list --filter refactor',
+    '<%= config.bin %> prompts list --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static flags = {
+    filter: Flags.string({
+      char: 'f',
+      description: 'Filter prompts by title, category, description, or tag (case-insensitive)',
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(PromptsList)
+    const isJson = flags.json
+
+    const spinner = isJson
+      ? null
+      : ora({
+          spinner: 'arc',
+          color: false,
+          text: chalk.hex('#FF6B2B')('Fetching prompts...'),
+        }).start()
+
+    /** @type {Prompt[]} */
+    let prompts
+    try {
+      prompts = await listPrompts()
+    } catch (err) {
+      spinner?.fail()
+      if (err instanceof DvmiError) {
+        this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+      }
+      throw err
+    }
+
+    spinner?.stop()
+
+    // Apply filter
+    const query = flags.filter?.toLowerCase()
+    const filtered = query
+      ? prompts.filter(
+          (p) =>
+            p.title.toLowerCase().includes(query) ||
+            p.category?.toLowerCase().includes(query) ||
+            p.description?.toLowerCase().includes(query) ||
+            p.tags?.some((t) => t.toLowerCase().includes(query)),
+        )
+      : prompts
+
+    if (isJson) {
+      return { prompts: filtered, total: filtered.length }
+    }
+
+    if (filtered.length === 0) {
+      const msg = query
+        ? chalk.dim(`No prompts matching "${flags.filter}".`)
+        : chalk.yellow('No prompts found in the repository.')
+      this.log(msg)
+      return { prompts: [], total: 0 }
+    }
+
+    const filterInfo = query ? chalk.dim(`  —  filter: ${chalk.white(`"${flags.filter}"`)}`) : ''
+    this.log(
+      chalk.bold(`\nPrompts`) +
+        filterInfo +
+        chalk.dim(`  (${filtered.length}${filtered.length < prompts.length ? `/${prompts.length}` : ''})\n`),
+    )
+    this.log(formatPromptTable(filtered))
+    this.log('')
+
+    // Interactive selection to view full prompt content
+    try {
+      const choices = filtered.map((p) => ({ name: p.title, value: p }))
+      choices.push({ name: chalk.dim('← Exit'), value: /** @type {Prompt} */ (null) })
+
+      const selected = await select({
+        message: 'Select a prompt to view its content (or Exit):',
+        choices,
+      })
+
+      if (selected) {
+        this.log('\n' + formatPromptBody(selected) + '\n')
+      }
+    } catch {
+      // User pressed Ctrl+C — exit gracefully
+    }
+
+    return { prompts: filtered, total: filtered.length }
+  }
+}