devvami 1.0.0 → 1.1.1

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/commands/upgrade.js

@@ -22,6 +22,11 @@ export default class Upgrade extends Command {
     const { hasUpdate, current, latest } = await checkForUpdate({ force: true })
     spinner?.stop()
 
+    // Guard against malformed version strings from the GitHub Releases API
+    if (latest && !/^v?\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/.test(latest)) {
+      this.error(`Invalid version received from releases API: "${latest}" — update aborted`)
+    }
+
     if (!hasUpdate) {
       const msg = `You're already on the latest version (${current})`
       if (isJson) return { currentVersion: current, latestVersion: latest, updated: false }

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 ─────────────────────────────────────────────────────────────

package/src/services/awesome-copilot.js

@@ -0,0 +1,123 @@
+import { createOctokit } from './github.js'
+import { DvmiError } from '../utils/errors.js'
+
+/** @import { AwesomeEntry } from '../types.js' */
+
+/**
+ * Supported categories in github/awesome-copilot.
+ * Each maps to `docs/README.<category>.md` in the repository.
+ * @type {string[]}
+ */
+export const AWESOME_CATEGORIES = ['agents', 'instructions', 'skills', 'plugins', 'hooks', 'workflows']
+
+const AWESOME_REPO = { owner: 'github', repo: 'awesome-copilot' }
+
+/**
+ * Parse a GitHub-flavoured markdown table into AwesomeEntry objects.
+ *
+ * Expects at least two columns: `| Name/Link | Description |`
+ * The first column may contain `[text](url)` markdown links; badge images
+ * (e.g. `[![foo](img)](url)`) are stripped so only the text survives.
+ *
+ * @param {string} md - Raw markdown content of the file
+ * @param {string} category - Category label attached to every returned entry
+ * @returns {AwesomeEntry[]}
+ */
+export function parseMarkdownTable(md, category) {
+  /** @type {AwesomeEntry[]} */
+  const entries = []
+
+  for (const line of md.split('\n')) {
+    // Only process table data rows (start + end with |, not separator rows)
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) continue
+    if (/^\|[\s\-:|]+\|/.test(trimmed)) continue // header separator
+
+    const cells = trimmed
+      .slice(1, -1) // remove leading and trailing |
+      .split('|')
+      .map((c) => c.trim())
+
+    if (cells.length < 2) continue
+
+    const rawName = cells[0]
+    const description = cells[1] ?? ''
+
+    // Skip header row (first column is literally "Name" or similar)
+    if (/^[\*_]?name[\*_]?$/i.test(rawName)) continue
+
+    // Strip badge images: [![alt](img)](url) → keep nothing; [![alt](img)] → keep nothing
+    const noBadge = rawName.replace(/\[!\[.*?\]\(.*?\)\]\(.*?\)/g, '').replace(/!\[.*?\]\(.*?\)/g, '').trim()
+
+    // Extract [text](url) link
+    const linkMatch = noBadge.match(/\[([^\]]+)\]\(([^)]+)\)/)
+    const name = linkMatch ? linkMatch[1].trim() : noBadge.replace(/\[|\]/g, '').trim()
+    const url = linkMatch ? linkMatch[2].trim() : ''
+
+    if (!name) continue
+
+    entries.push(
+      /** @type {AwesomeEntry} */ ({
+        name,
+        description: description.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1').trim(),
+        url,
+        category,
+        source: 'awesome-copilot',
+      }),
+    )
+  }
+
+  return entries
+}
+
+/**
+ * Fetch awesome-copilot entries for a given category from GitHub.
+ *
+ * Retrieves `docs/README.<category>.md` from the `github/awesome-copilot`
+ * repository and parses the markdown table into AwesomeEntry objects.
+ *
+ * @param {string} category - One of {@link AWESOME_CATEGORIES}
+ * @returns {Promise<AwesomeEntry[]>}
+ * @throws {DvmiError} when category is invalid, file not found, or auth is missing
+ */
+export async function fetchAwesomeEntries(category) {
+  if (!AWESOME_CATEGORIES.includes(category)) {
+    throw new DvmiError(
+      `Unknown awesome-copilot category: "${category}"`,
+      `Valid categories: ${AWESOME_CATEGORIES.join(', ')}`,
+    )
+  }
+
+  const octokit = await createOctokit()
+  const path = `docs/README.${category}.md`
+
+  let data
+  try {
+    const res = await octokit.rest.repos.getContent({
+      owner: AWESOME_REPO.owner,
+      repo: AWESOME_REPO.repo,
+      path,
+    })
+    data = res.data
+  } catch (err) {
+    const status = /** @type {{ status?: number }} */ (err).status
+    if (status === 404) {
+      throw new DvmiError(
+        `Category file not found: ${path}`,
+        `Check available categories: ${AWESOME_CATEGORIES.join(', ')}`,
+      )
+    }
+    throw err
+  }
+
+  const file = /** @type {{ content?: string, encoding?: string }} */ (data)
+  if (!file.content || file.encoding !== 'base64') {
+    throw new DvmiError(
+      `Unable to read awesome-copilot category: ${category}`,
+      'The file may be a directory or have an unsupported encoding',
+    )
+  }
+
+  const md = Buffer.from(file.content.replace(/\n/g, ''), 'base64').toString('utf8')
+  return parseMarkdownTable(md, category)
+}

package/src/services/clickup.js

@@ -1,4 +1,5 @@
 import http from 'node:http'
+import { randomBytes } from 'node:crypto'
 import { openBrowser } from '../utils/open-browser.js'
 import { loadConfig } from './config.js'
 
@@ -45,6 +46,10 @@ export async function storeToken(token) {
      await keytar.setPassword('devvami', TOKEN_KEY, token)
    } catch {
     // Fallback: store in config (less secure)
+    process.stderr.write(
+      'Warning: keytar unavailable. ClickUp token will be stored in plaintext.\n' +
+      'Run `dvmi auth logout` after this session on shared machines.\n',
+    )
     const config = await loadConfig()
     await saveConfig({ ...config, clickup: { ...config.clickup, token } })
   }
@@ -57,11 +62,20 @@ export async function storeToken(token) {
  * @returns {Promise<string>} Access token
  */
 export async function oauthFlow(clientId, clientSecret) {
+  const csrfState = randomBytes(16).toString('hex')
   return new Promise((resolve, reject) => {
     const server = http.createServer(async (req, res) => {
       const url = new URL(req.url ?? '/', 'http://localhost')
       const code = url.searchParams.get('code')
+      const returnedState = url.searchParams.get('state')
       if (!code) return
+      if (!returnedState || returnedState !== csrfState) {
+        res.writeHead(400)
+        res.end('State mismatch — possible CSRF attack.')
+        server.close()
+        reject(new Error('OAuth state mismatch — possible CSRF attack'))
+        return
+      }
       res.end('Authorization successful! You can close this tab.')
       server.close()
       try {
@@ -80,7 +94,7 @@ export async function oauthFlow(clientId, clientSecret) {
     server.listen(0, async () => {
       const addr = /** @type {import('node:net').AddressInfo} */ (server.address())
       const callbackUrl = `http://localhost:${addr.port}/callback`
-      const authUrl = `https://app.clickup.com/api?client_id=${clientId}&redirect_uri=${encodeURIComponent(callbackUrl)}`
+      const authUrl = `https://app.clickup.com/api?client_id=${clientId}&redirect_uri=${encodeURIComponent(callbackUrl)}&state=${csrfState}`
       await openBrowser(authUrl)
     })
     server.on('error', reject)

package/src/services/config.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
@@ -47,6 +47,7 @@ export async function saveConfig(config, configPath = CONFIG_PATH) {
     await mkdir(dir, { recursive: true })
   }
   await writeFile(configPath, JSON.stringify(config, null, 2), 'utf8')
+  await chmod(configPath, 0o600)
 }
 
 /**

package/src/services/github.js

@@ -20,7 +20,8 @@ async function getToken() {
  */
 export async function createOctokit() {
   const token = await getToken()
-  return new Octokit({ auth: token })
+  const baseUrl = process.env.GITHUB_API_URL ?? 'https://api.github.com'
+  return new Octokit({ auth: token, baseUrl })
 }
 
 /**