devvami 1.0.0 → 1.1.0

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 }
+  }
+}

package/src/commands/prompts/run.js

@@ -0,0 +1,189 @@
+import { Command, Args, Flags } from '@oclif/core'
+import ora from 'ora'
+import chalk from 'chalk'
+import { select } from '@inquirer/prompts'
+import { join } from 'node:path'
+import { readdir } from 'node:fs/promises'
+import { resolveLocalPrompt, invokeTool, SUPPORTED_TOOLS } from '../../services/prompts.js'
+import { loadConfig } from '../../services/config.js'
+import { DvmiError } from '../../utils/errors.js'
+
+/** @import { AITool } from '../../types.js' */
+
+const DEFAULT_PROMPTS_DIR = '.prompts'
+
+/**
+ * Walk a directory recursively and collect `.md` file paths relative to `base`.
+ * @param {string} dir
+ * @param {string} base
+ * @returns {Promise<string[]>}
+ */
+async function walkPrompts(dir, base) {
+  /** @type {string[]} */
+  const results = []
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return results
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      const sub = await walkPrompts(full, base)
+      results.push(...sub)
+    } else if (entry.name.endsWith('.md')) {
+      results.push(full.replace(base + '/', ''))
+    }
+  }
+  return results
+}
+
+export default class PromptsRun extends Command {
+  static description = 'Execute a local prompt with a configured AI tool'
+
+  static examples = [
+    '<%= config.bin %> prompts run',
+    '<%= config.bin %> prompts run coding/refactor-prompt.md',
+    '<%= config.bin %> prompts run coding/refactor-prompt.md --tool opencode',
+    '<%= config.bin %> prompts run coding/refactor-prompt.md --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static args = {
+    path: Args.string({
+      description: 'Relative path of the local prompt (e.g. coding/refactor-prompt.md)',
+      required: false,
+    }),
+  }
+
+  static flags = {
+    tool: Flags.string({
+      char: 't',
+      description: `AI tool to use (${Object.keys(SUPPORTED_TOOLS).join(', ')})`,
+      options: Object.keys(SUPPORTED_TOOLS),
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(PromptsRun)
+    const isJson = flags.json
+
+    // Load config
+    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 tool: --tool flag > config.aiTool
+    const toolName = /** @type {AITool | undefined} */ (flags.tool ?? config.aiTool)
+
+    // In --json mode, output the invocation plan without spawning
+    if (isJson) {
+      if (!args.path) {
+        this.error('Prompt path is required in --json mode', {
+          exit: 1,
+          suggestions: ['Run `dvmi prompts run <path> --json`'],
+        })
+      }
+
+      if (!toolName) {
+        this.error('No AI tool configured', {
+          exit: 1,
+          suggestions: ['Run `dvmi init` to configure your preferred AI tool, or pass --tool <name>'],
+        })
+      }
+
+      if (!SUPPORTED_TOOLS[toolName]) {
+        this.error(`Unknown tool: "${toolName}". Supported: ${Object.keys(SUPPORTED_TOOLS).join(', ')}`, {
+          exit: 1,
+        })
+      }
+
+      let prompt
+      try {
+        prompt = await resolveLocalPrompt(args.path, localDir)
+      } catch (err) {
+        if (err instanceof DvmiError) {
+          this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+        }
+        throw err
+      }
+
+      const tool = SUPPORTED_TOOLS[toolName]
+      const invocation = [tool.bin.join(' '), tool.promptFlag, '<prompt content>'].join(' ')
+      return {
+        tool: toolName,
+        promptPath: args.path,
+        invocation,
+        preview: prompt.body.slice(0, 200),
+      }
+    }
+
+    // --- Interactive mode ---
+
+    // Resolve path interactively if not provided
+    let relativePath = args.path
+    if (!relativePath) {
+      const localPaths = await walkPrompts(localDir, localDir)
+
+      if (localPaths.length === 0) {
+        this.error('No local prompts found', {
+          exit: 1,
+          suggestions: [`Run \`dvmi prompts download\` to download prompts to ${localDir}`],
+        })
+      }
+
+      relativePath = await select({
+        message: 'Select a local prompt to run:',
+        choices: localPaths.map((p) => ({ name: p, value: p })),
+      })
+    }
+
+    // Verify tool is configured
+    if (!toolName) {
+      this.error('No AI tool configured', {
+        exit: 1,
+        suggestions: ['Run `dvmi init` to configure your preferred AI tool, or pass --tool <name>'],
+      })
+    }
+
+    // Load prompt
+    const spinner = ora({
+      spinner: 'arc',
+      color: false,
+      text: chalk.hex('#FF6B2B')('Loading prompt...'),
+    }).start()
+
+    let prompt
+    try {
+      prompt = await resolveLocalPrompt(relativePath, localDir)
+      spinner.stop()
+    } catch (err) {
+      spinner.fail()
+      if (err instanceof DvmiError) {
+        this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+      }
+      throw err
+    }
+
+    this.log(chalk.bold(`\nRunning: ${chalk.hex('#FF9A5C')(prompt.title)}`))
+    this.log(chalk.dim(`  Tool: ${toolName}`) + '\n')
+
+    // Invoke tool
+    try {
+      await invokeTool(toolName, prompt.body)
+    } catch (err) {
+      if (err instanceof DvmiError) {
+        this.error(err.message, { exit: err.exitCode, suggestions: [err.hint] })
+      }
+      throw err
+    }
+  }
+}

package/src/formatters/prompts.js

@@ -0,0 +1,159 @@
+import chalk from 'chalk'
+import { marked } from 'marked'
+import { renderTable } from './table.js'
+
+/** @import { Prompt, Skill, AwesomeEntry } from '../types.js' */
+
+/**
+ * Format a list of prompts as a terminal table.
+ * Columns: title, category, description.
+ *
+ * @param {Prompt[]} prompts
+ * @returns {string}
+ */
+export function formatPromptTable(prompts) {
+  if (prompts.length === 0) {
+    return chalk.dim('No prompts found.')
+  }
+
+  return renderTable(
+    /** @type {Record<string, unknown>[]} */ (prompts),
+    [
+      {
+        header: 'Title',
+        key: 'title',
+        width: 36,
+        colorize: (v) => chalk.hex('#FF9A5C')(v),
+      },
+      {
+        header: 'Category',
+        key: 'category',
+        width: 16,
+        format: (v) => v ?? '—',
+        colorize: (v) => chalk.hex('#4A9EFF')(v),
+      },
+      {
+        header: 'Description',
+        key: 'description',
+        width: 60,
+        format: (v) => v ?? '—',
+        colorize: (v) => chalk.white(v),
+      },
+    ],
+  )
+}
+
+/**
+ * Format a single prompt's full content for display in the terminal.
+ * Renders the title as a header and the body as plain text (markdown stripped).
+ *
+ * @param {Prompt} prompt
+ * @returns {string}
+ */
+export function formatPromptBody(prompt) {
+  const titleLine = chalk.bold.hex('#FF6B2B')(prompt.title)
+  const divider = chalk.dim('─'.repeat(60))
+
+  const meta = [
+    prompt.category ? chalk.dim(`Category: `) + chalk.hex('#4A9EFF')(prompt.category) : null,
+    prompt.description ? chalk.dim(`Description: `) + chalk.white(prompt.description) : null,
+    prompt.tags?.length ? chalk.dim(`Tags: `) + chalk.hex('#4A9EFF')(prompt.tags.join(', ')) : null,
+  ]
+    .filter(Boolean)
+    .join('\n')
+
+  // Render markdown to plain terminal text by stripping HTML tags from marked output
+  const rendered = marked(prompt.body, { async: false })
+  const plain = String(rendered)
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .trim()
+
+  const parts = [titleLine, divider]
+  if (meta) parts.push(meta, divider)
+  parts.push(plain)
+
+  return parts.join('\n')
+}
+
+/**
+ * Format a list of skills.sh skills as a terminal table.
+ * Columns: name, installs, description.
+ *
+ * @param {Skill[]} skills
+ * @returns {string}
+ */
+export function formatSkillTable(skills) {
+  if (skills.length === 0) {
+    return chalk.dim('No skills found.')
+  }
+
+  return renderTable(
+    /** @type {Record<string, unknown>[]} */ (skills),
+    [
+      {
+        header: 'Name',
+        key: 'name',
+        width: 36,
+        colorize: (v) => chalk.hex('#FF9A5C')(v),
+      },
+      {
+        header: 'Installs',
+        key: 'installs',
+        width: 10,
+        format: (v) => (v != null ? String(v) : '—'),
+        colorize: (v) => chalk.hex('#4A9EFF')(v),
+      },
+      {
+        header: 'Description',
+        key: 'description',
+        width: 60,
+        format: (v) => v ?? '—',
+        colorize: (v) => chalk.white(v),
+      },
+    ],
+  )
+}
+
+/**
+ * Format a list of awesome-copilot entries as a terminal table.
+ * Columns: name, category, description.
+ *
+ * @param {AwesomeEntry[]} entries
+ * @param {string} [category] - Active category label shown in the header
+ * @returns {string}
+ */
+export function formatAwesomeTable(entries, category) {
+  if (entries.length === 0) {
+    return chalk.dim(category ? `No entries found for category "${category}".` : 'No entries found.')
+  }
+
+  return renderTable(
+    /** @type {Record<string, unknown>[]} */ (entries),
+    [
+      {
+        header: 'Name',
+        key: 'name',
+        width: 36,
+        colorize: (v) => chalk.hex('#FF9A5C')(v),
+      },
+      {
+        header: 'Category',
+        key: 'category',
+        width: 14,
+        format: (v) => v ?? '—',
+        colorize: (v) => chalk.hex('#4A9EFF')(v),
+      },
+      {
+        header: 'Description',
+        key: 'description',
+        width: 58,
+        format: (v) => v ?? '—',
+        colorize: (v) => chalk.white(v),
+      },
+    ],
+  )
+}

package/src/help.js

@@ -68,6 +68,16 @@ const CATEGORIES = [
       { id: 'costs:get', hint: '[--period] [--profile]' },
     ],
   },
+  {
+    title: 'AI Prompts',
+    cmds: [
+      { id: 'prompts:list',           hint: '[--filter]' },
+      { id: 'prompts:download',       hint: '<PATH> [--overwrite]' },
+      { id: 'prompts:browse',         hint: '[--source] [--query] [--category]' },
+      { id: 'prompts:install-speckit', hint: '[--force]' },
+      { id: 'prompts:run',            hint: '[PATH] [--tool]' },
+    ],
+  },
   {
     title: 'Setup & Ambiente',
     cmds: [
@@ -82,14 +92,19 @@ const CATEGORIES = [
 
 // ─── Example commands shown at bottom of root help ──────────────────────────
 const EXAMPLES = [
-   { cmd: 'dvmi docs read',                    note: 'Leggi il README del repo corrente' },
-   { cmd: 'dvmi docs read openapi.yaml',       note: 'Tabella endpoints OpenAPI nel terminale' },
-   { cmd: 'dvmi docs search "authentication"', note: 'Cerca nei docs del repo corrente' },
-   { cmd: 'dvmi repo list --search "api"',     note: 'Filtra repository per nome' },
-   { cmd: 'dvmi pr status',                    note: 'PR aperte e review in attesa' },
-   { cmd: 'dvmi pipeline status',              note: 'Ultimi workflow CI/CD' },
-   { cmd: 'dvmi tasks list --search "bug"',    note: 'Cerca task ClickUp' },
-   { cmd: 'dvmi costs get --json',             note: 'Costi AWS in formato JSON' },
+   { cmd: 'dvmi prompts list',                                    note: 'Sfoglia prompt AI dal tuo repository' },
+   { cmd: 'dvmi prompts list --filter refactor',                  note: 'Filtra prompt per parola chiave' },
+   { cmd: 'dvmi prompts download coding/refactor-prompt.md',      note: 'Scarica un prompt localmente' },
+   { cmd: 'dvmi prompts browse skills --query refactor',          note: 'Cerca skill su skills.sh' },
+   { cmd: 'dvmi prompts browse awesome --category agents',        note: 'Sfoglia awesome-copilot agents' },
+   { cmd: 'dvmi prompts run coding/refactor-prompt.md --tool opencode', note: 'Esegui un prompt con opencode' },
+   { cmd: 'dvmi docs read',                                       note: 'Leggi il README del repo corrente' },
+   { cmd: 'dvmi docs search "authentication"',                    note: 'Cerca nei docs del repo corrente' },
+   { cmd: 'dvmi repo list --search "api"',                        note: 'Filtra repository per nome' },
+   { cmd: 'dvmi pr status',                                       note: 'PR aperte e review in attesa' },
+   { cmd: 'dvmi pipeline status',                                 note: 'Ultimi workflow CI/CD' },
+   { cmd: 'dvmi tasks list --search "bug"',                       note: 'Cerca task ClickUp' },
+   { cmd: 'dvmi costs get --json',                                note: 'Costi AWS in formato JSON' },
  ]
 
 // ─── Help class ─────────────────────────────────────────────────────────────