devvami 1.0.0

package/src/commands/docs/list.js

@@ -0,0 +1,110 @@
+import { Command, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import { loadConfig } from '../../services/config.js'
+import { listDocs, detectCurrentRepo } from '../../services/docs.js'
+import { renderTable } from '../../formatters/table.js'
+
+/**
+ * @param {string} type
+ * @returns {string}
+ */
+function typeColor(type) {
+  if (type === 'readme')   return chalk.cyan(type)
+  if (type === 'swagger')  return chalk.yellow(type)
+  if (type === 'asyncapi') return chalk.green(type)
+  return chalk.dim(type)
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatSize(bytes) {
+  if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)}KB`
+  return `${bytes}B`
+}
+
+export default class DocsList extends Command {
+  static description = 'Lista i file di documentazione del repository'
+
+  static examples = [
+    '<%= config.bin %> docs list',
+    '<%= config.bin %> docs list --repo my-service',
+    '<%= config.bin %> docs list --search "arch"',
+    '<%= config.bin %> docs list --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static flags = {
+    repo:   Flags.string({ char: 'r', description: 'Nome del repository (default: repo nella directory corrente)' }),
+    search: Flags.string({ char: 's', description: 'Filtra per nome o percorso (case-insensitive)' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(DocsList)
+    const isJson = flags.json
+    const config = await loadConfig()
+
+    // Resolve owner/repo
+    let owner, repo
+    if (flags.repo) {
+      owner = config.org
+      if (!owner) this.error('GitHub org not configured. Run `dvmi init` to set up your environment.')
+      repo = flags.repo
+    } else {
+      try {
+        ;({ owner, repo } = await detectCurrentRepo())
+      } catch (err) {
+        this.error(/** @type {Error} */ (err).message)
+      }
+    }
+
+    const spinner = isJson ? null : ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')('Fetching documentation...') }).start()
+    let entries
+    try {
+      entries = await listDocs(owner, repo)
+    } catch (err) {
+      spinner?.stop()
+      this.error(/** @type {Error} */ (err).message)
+    }
+    spinner?.stop()
+
+    // Search filter
+    const q = flags.search?.toLowerCase()
+    const filtered = q
+      ? entries.filter((e) => e.name.toLowerCase().includes(q) || e.path.toLowerCase().includes(q))
+      : entries
+
+    if (isJson) return { repo, owner, entries: filtered, total: filtered.length }
+
+    if (entries.length === 0) {
+      this.log(chalk.dim(`No documentation found in ${owner}/${repo}.`))
+      return { repo, owner, entries: [], total: 0 }
+    }
+
+    if (filtered.length === 0) {
+      this.log(chalk.dim(`No documentation matching "${flags.search}" in ${owner}/${repo}.`))
+      return { repo, owner, entries: [], total: 0 }
+    }
+
+    const filterInfo = q ? chalk.dim(`  —  search: ${chalk.white(`"${flags.search}"`)}`): ''
+    this.log(
+      chalk.bold(`\nDocumentation in ${owner}/${repo}`) +
+      filterInfo +
+      chalk.dim(`  (${filtered.length}${filtered.length < entries.length ? `/${entries.length}` : ''})`) +
+      '\n',
+    )
+
+    this.log(renderTable(filtered, [
+      { header: 'Type', key: 'type', width: 10, colorize: typeColor },
+      { header: 'Name', key: 'name', width: 30 },
+      { header: 'Path', key: 'path', width: 50 },
+      { header: 'Size', key: 'size', width: 8, format: (v) => formatSize(Number(v)) },
+    ]))
+    this.log('')
+
+    return { repo, owner, entries: filtered, total: filtered.length }
+  }
+}

package/src/commands/docs/projects.js

@@ -0,0 +1,92 @@
+import { Command, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import { loadConfig } from '../../services/config.js'
+import { listRepos } from '../../services/github.js'
+import { listProjectsDocs } from '../../services/docs.js'
+import { renderTable } from '../../formatters/table.js'
+
+export default class DocsProjects extends Command {
+  static description = 'Mostra la documentazione disponibile per ogni repository dell\'organizzazione'
+
+  static examples = [
+    '<%= config.bin %> docs projects',
+    '<%= config.bin %> docs projects --search "service"',
+    '<%= config.bin %> docs projects --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static flags = {
+    search: Flags.string({ char: 's', description: 'Filtra per nome repository (case-insensitive)' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(DocsProjects)
+    const isJson = flags.json
+    const config = await loadConfig()
+
+    if (!config.org) {
+      this.error('GitHub org not configured. Run `dvmi init` to set up your environment.')
+    }
+
+    // 1. Fetch all repos
+    const repoSpinner = isJson ? null : ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')('Fetching repositories...') }).start()
+    let repos
+    try {
+      repos = await listRepos(config.org)
+    } catch (err) {
+      repoSpinner?.stop()
+      this.error(/** @type {Error} */ (err).message)
+    }
+    repoSpinner?.stop()
+
+    if (repos.length === 0) {
+      this.log(chalk.dim(`No repositories found in organization "${config.org}".`))
+      return { org: config.org, projects: [], total: 0 }
+    }
+
+    // 2. Filter by search
+    const q = flags.search?.toLowerCase()
+    const filteredRepos = q ? repos.filter((r) => r.name.toLowerCase().includes(q)) : repos
+
+    if (filteredRepos.length === 0) {
+      this.log(chalk.dim(`No repositories matching "${flags.search}" in ${config.org}.`))
+      return { org: config.org, projects: [], total: 0 }
+    }
+
+    // 3. Scan each repo for docs
+    const scanSpinner = isJson ? null : ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')(`Scanning docs in ${filteredRepos.length} repositories...`) }).start()
+
+    const repoNames = filteredRepos.map((r) => r.name)
+    let projects
+    try {
+      projects = await listProjectsDocs(config.org, repoNames)
+    } catch (err) {
+      scanSpinner?.stop()
+      this.error(/** @type {Error} */ (err).message)
+    }
+    scanSpinner?.stop()
+
+    if (isJson) return { org: config.org, projects, total: projects.length }
+
+    const filterInfo = q ? chalk.dim(`  —  search: ${chalk.white(`"${flags.search}"`)}`) : ''
+    this.log(
+      chalk.bold(`\nDocumentation overview for ${config.org}`) +
+      filterInfo +
+      chalk.dim(`  (${projects.length}${projects.length < repos.length ? `/${repos.length}` : ''})`) +
+      '\n',
+    )
+
+    this.log(renderTable(projects, [
+      { header: 'Repository', key: 'repo',       width: 40 },
+      { header: 'README',     key: 'hasReadme',   width: 8,  format: (v) => v ? '✓' : '—', colorize: (v) => v === '✓' ? chalk.green(v) : chalk.dim(v) },
+      { header: 'Docs',       key: 'docsCount',   width: 6,  format: (v) => Number(v) > 0 ? String(v) : '—', colorize: (v) => v !== '—' ? chalk.cyan(v) : chalk.dim(v) },
+      { header: 'Swagger',    key: 'hasSwagger',  width: 9,  format: (v) => v ? '✓' : '—', colorize: (v) => v === '✓' ? chalk.yellow(v) : chalk.dim(v) },
+      { header: 'AsyncAPI',   key: 'hasAsyncApi', width: 10, format: (v) => v ? '✓' : '—', colorize: (v) => v === '✓' ? chalk.green(v) : chalk.dim(v) },
+    ]))
+    this.log('')
+
+    return { org: config.org, projects, total: projects.length }
+  }
+}

package/src/commands/docs/read.js

@@ -0,0 +1,172 @@
+import { Command, Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import { loadConfig } from '../../services/config.js'
+import { listDocs, readFile, detectCurrentRepo, detectApiSpecType } from '../../services/docs.js'
+import { renderMarkdown, extractMermaidBlocks, toMermaidLiveUrl } from '../../formatters/markdown.js'
+import { parseOpenApi, parseAsyncApi } from '../../formatters/openapi.js'
+import { renderTable } from '../../formatters/table.js'
+import { openBrowser } from '../../utils/open-browser.js'
+
+/**
+ * @param {string} method
+ * @returns {string}
+ */
+function methodColor(method) {
+  const colors = {
+    GET: chalk.cyan,
+    POST: chalk.green,
+    PUT: chalk.yellow,
+    PATCH: chalk.magenta,
+    DELETE: chalk.red,
+    HEAD: chalk.dim,
+    OPTIONS: chalk.dim,
+  }
+  const fn = colors[method]
+  return fn ? fn(method) : method
+}
+
+/**
+ * @param {string} op
+ * @returns {string}
+ */
+function opColor(op) {
+  if (op === 'publish' || op === 'send') return chalk.green(op)
+  if (op === 'subscribe' || op === 'receive') return chalk.cyan(op)
+  return chalk.dim(op)
+}
+
+export default class DocsRead extends Command {
+  static description = 'Leggi un file di documentazione del repository nel terminale'
+
+  static examples = [
+    '<%= config.bin %> docs read',
+    '<%= config.bin %> docs read --repo my-service',
+    '<%= config.bin %> docs read docs/architecture.md',
+    '<%= config.bin %> docs read openapi.yaml',
+    '<%= config.bin %> docs read openapi.yaml --raw',
+    '<%= config.bin %> docs read --render',
+    '<%= config.bin %> docs read --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static args = {
+    file: Args.string({ description: 'Percorso del file da leggere (default: README)', required: false }),
+  }
+
+  static flags = {
+    repo:   Flags.string({ char: 'r', description: 'Nome del repository (default: repo nella directory corrente)' }),
+    raw:    Flags.boolean({ description: 'Mostra contenuto grezzo senza parsing speciale', default: false }),
+    render: Flags.boolean({ description: 'Apri i diagrammi Mermaid nel browser via mermaid.live', default: false }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DocsRead)
+    const isJson = flags.json
+    const config = await loadConfig()
+
+    // Resolve owner/repo
+    let owner, repo
+    if (flags.repo) {
+      owner = config.org
+      if (!owner) this.error('GitHub org not configured. Run `dvmi init` to set up your environment.')
+      repo = flags.repo
+    } else {
+      try {
+        ;({ owner, repo } = await detectCurrentRepo())
+      } catch (err) {
+        this.error(/** @type {Error} */ (err).message)
+      }
+    }
+
+    // Resolve file path
+    let filePath = args.file
+    if (!filePath) {
+      const spinner = isJson ? null : ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')('Looking for README...') }).start()
+      let entries
+      try {
+        entries = await listDocs(owner, repo)
+      } catch (err) {
+        spinner?.stop()
+        this.error(/** @type {Error} */ (err).message)
+      }
+      spinner?.stop()
+      const readme = entries.find((e) => e.type === 'readme')
+      if (!readme) {
+        this.log(chalk.dim(`No README found in ${owner}/${repo}.`))
+        return { repo, owner, path: null, type: null, content: null, size: 0 }
+      }
+      filePath = readme.path
+    }
+
+    // Fetch content
+    const spinner2 = isJson ? null : ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')(`Reading ${filePath}...`) }).start()
+     let content
+     try {
+       content = await readFile(owner, repo, filePath)
+     } catch {
+       spinner2?.stop()
+       this.error(`File "${filePath}" not found in ${owner}/${repo}. Run \`dvmi docs list\` to see available documentation.`)
+     }
+    spinner2?.stop()
+
+    if (isJson) {
+      return { repo, owner, path: filePath, type: detectApiSpecType(filePath, content) ?? 'doc', content, size: content.length }
+    }
+
+    // Handle --render (Mermaid)
+    if (flags.render) {
+      const blocks = extractMermaidBlocks(content)
+      if (blocks.length === 0) {
+        this.log(chalk.dim('No Mermaid diagrams found in this document.'))
+      } else {
+        for (const block of blocks) {
+          const url = toMermaidLiveUrl(block)
+          await openBrowser(url)
+          this.log(chalk.green('✓') + ` Opened Mermaid diagram in browser: ${url}`)
+        }
+      }
+    }
+
+    const specType = detectApiSpecType(filePath, content)
+
+    // Render
+    if (!flags.raw && specType === 'swagger') {
+      const { endpoints, error } = parseOpenApi(content)
+      if (error || endpoints.length === 0) {
+        this.log(chalk.yellow(`⚠ Could not parse "${filePath}" as OpenAPI spec (showing raw content). ${error ?? ''}`))
+        this.log(content)
+      } else {
+        this.log(chalk.bold(`\nAPI Endpoints — ${filePath}\n`))
+        this.log(renderTable(endpoints, [
+          { header: 'Method',     key: 'method',     width: 8,  colorize: methodColor },
+          { header: 'Path',       key: 'path',       width: 45 },
+          { header: 'Summary',    key: 'summary',    width: 40 },
+          { header: 'Parameters', key: 'parameters', width: 30, format: (v) => v || '—' },
+        ]))
+        this.log('')
+      }
+    } else if (!flags.raw && specType === 'asyncapi') {
+      const { channels, error } = parseAsyncApi(content)
+      if (error || channels.length === 0) {
+        this.log(chalk.yellow(`⚠ Could not parse "${filePath}" as AsyncAPI spec (showing raw content). ${error ?? ''}`))
+        this.log(content)
+      } else {
+        this.log(chalk.bold(`\nAsyncAPI Channels — ${filePath}\n`))
+        this.log(renderTable(channels, [
+          { header: 'Channel',   key: 'channel',   width: 35 },
+          { header: 'Operation', key: 'operation', width: 12, colorize: opColor },
+          { header: 'Summary',   key: 'summary',   width: 40 },
+          { header: 'Message',   key: 'message',   width: 25, format: (v) => v || '—' },
+        ]))
+        this.log('')
+      }
+    } else {
+      // Markdown or raw
+      this.log(renderMarkdown(content))
+    }
+
+    return { repo, owner, path: filePath, type: specType ?? 'doc', content, size: content.length }
+  }
+}

package/src/commands/docs/search.js

@@ -0,0 +1,103 @@
+import { Command, Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import { loadConfig } from '../../services/config.js'
+import { searchDocs, detectCurrentRepo } from '../../services/docs.js'
+import { renderTable } from '../../formatters/table.js'
+
+const MAX_MATCHES_PER_FILE = 3
+
+export default class DocsSearch extends Command {
+  static description = 'Cerca testo nella documentazione del repository'
+
+  static examples = [
+    '<%= config.bin %> docs search "authentication"',
+    '<%= config.bin %> docs search "deploy" --repo my-service',
+    '<%= config.bin %> docs search "endpoint" --json',
+  ]
+
+  static enableJsonFlag = true
+
+  static args = {
+    term: Args.string({ description: 'Termine di ricerca (case-insensitive)', required: true }),
+  }
+
+  static flags = {
+    repo: Flags.string({ char: 'r', description: 'Nome del repository (default: repo nella directory corrente)' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DocsSearch)
+    const isJson = flags.json
+    const config = await loadConfig()
+
+    // Resolve owner/repo
+    let owner, repo
+    if (flags.repo) {
+      owner = config.org
+      if (!owner) this.error('GitHub org not configured. Run `dvmi init` to set up your environment.')
+      repo = flags.repo
+    } else {
+      try {
+        ;({ owner, repo } = await detectCurrentRepo())
+      } catch (err) {
+        this.error(/** @type {Error} */ (err).message)
+      }
+    }
+
+    const spinner = isJson ? null : ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')(`Searching "${args.term}" in docs...`) }).start()
+    let matches
+    try {
+      matches = await searchDocs(owner, repo, args.term)
+    } catch (err) {
+      spinner?.stop()
+      this.error(/** @type {Error} */ (err).message)
+    }
+    spinner?.stop()
+
+    if (isJson) return { repo, owner, term: args.term, matches, total: matches.length }
+
+    if (matches.length === 0) {
+      this.log(chalk.dim(`No matches found for "${args.term}" in ${owner}/${repo} documentation.`))
+      return { repo, owner, term: args.term, matches: [], total: 0 }
+    }
+
+    this.log(chalk.bold(`\nSearch results for "${args.term}" in ${owner}/${repo}`) + chalk.dim(` (${matches.length} match${matches.length === 1 ? '' : 'es'})\n`))
+
+    // Group by file and limit rows
+    /** @type {Map<string, import('../../types.js').SearchMatch[]>} */
+    const byFile = new Map()
+    for (const m of matches) {
+      const list = byFile.get(m.file) ?? []
+      list.push(m)
+      byFile.set(m.file, list)
+    }
+
+    /** @type {Array<import('../../types.js').SearchMatch & { _extra?: string }>} */
+    const rows = []
+    for (const [, fileMatches] of byFile) {
+      const shown = fileMatches.slice(0, MAX_MATCHES_PER_FILE)
+      rows.push(...shown)
+      const extra = fileMatches.length - shown.length
+      if (extra > 0) {
+        rows.push({ file: '', line: 0, context: chalk.dim(`(+${extra} more in this file)`), occurrences: 0 })
+      }
+    }
+
+    const q = args.term.toLowerCase()
+    this.log(renderTable(rows, [
+      { header: 'File',    key: 'file',        width: 35 },
+      { header: 'Line',    key: 'line',         width: 5,  format: (v) => Number(v) === 0 ? '' : String(v) },
+      { header: 'Context', key: 'context',      width: 65, format: (v) => {
+        const s = String(v)
+        // highlight term
+        const re = new RegExp(q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi')
+        return s.replace(re, (m) => chalk.yellow.bold(m))
+      }},
+      { header: 'Matches', key: 'occurrences',  width: 8,  format: (v) => Number(v) === 0 ? '' : `${v}` },
+    ]))
+    this.log('')
+
+    return { repo, owner, term: args.term, matches, total: matches.length }
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,115 @@
+import { Command, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import { typewriterLine } from '../utils/typewriter.js'
+import { which, exec } from '../services/shell.js'
+import { checkGitHubAuth, checkAWSAuth } from '../services/auth.js'
+import { formatDoctorCheck, formatDoctorSummary } from '../formatters/status.js'
+
+/** @import { DoctorCheck } from '../types.js' */
+
+export default class Doctor extends Command {
+  static description = 'Diagnostica ambiente di sviluppo'
+
+  static examples = [
+    '<%= config.bin %> doctor',
+    '<%= config.bin %> doctor --json',
+    '<%= config.bin %> doctor --verbose',
+  ]
+
+  static enableJsonFlag = true
+
+  static flags = {
+    verbose: Flags.boolean({ description: 'Mostra dettagli aggiuntivi', default: false }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(Doctor)
+    const isJson = flags.json
+
+    const spinner = isJson ? null : ora({ spinner: 'arc', color: false, text: chalk.hex('#FF6B2B')('Running diagnostics...') }).start()
+
+    /** @type {DoctorCheck[]} */
+    const checks = []
+
+    // Software checks
+    const softwareChecks = [
+      { name: 'Node.js', cmd: 'node', args: ['--version'], required: '>=24' },
+      { name: 'nvm', cmd: 'nvm', args: ['--version'], required: null },
+      { name: 'npm', cmd: 'npm', args: ['--version'], required: null },
+      { name: 'Git', cmd: 'git', args: ['--version'], required: null },
+      { name: 'gh CLI', cmd: 'gh', args: ['--version'], required: null },
+      { name: 'Docker', cmd: 'docker', args: ['--version'], required: null },
+      { name: 'AWS CLI', cmd: 'aws', args: ['--version'], required: null },
+      { name: 'aws-vault', cmd: 'aws-vault', args: ['--version'], required: null },
+    ]
+
+    for (const check of softwareChecks) {
+      const path = await which(check.cmd)
+      if (!path) {
+        checks.push({
+          name: check.name,
+          status: check.required ? 'fail' : 'warn',
+          version: null,
+          required: check.required,
+          hint: `Install ${check.name}`,
+        })
+        continue
+      }
+      const result = await exec(check.cmd, check.args)
+      const version = result.stdout.replace(/\n.*/s, '').trim()
+      checks.push({
+        name: check.name,
+        status: 'ok',
+        version,
+        required: check.required,
+        hint: null,
+      })
+    }
+
+    // Auth checks
+     const ghAuth = await checkGitHubAuth()
+     checks.push({
+       name: 'GitHub auth',
+       status: ghAuth.authenticated ? 'ok' : 'fail',
+       version: ghAuth.authenticated ? ghAuth.username ?? null : null,
+       required: null,
+       hint: ghAuth.authenticated ? null : 'Run `dvmi auth login`',
+     })
+
+     const awsAuth = await checkAWSAuth()
+     checks.push({
+       name: 'AWS auth',
+       status: awsAuth.authenticated ? 'ok' : 'warn',
+       version: awsAuth.authenticated ? awsAuth.account ?? null : null,
+       required: null,
+       hint: awsAuth.authenticated ? null : 'Run `dvmi auth login --aws`',
+     })
+
+    spinner?.stop()
+
+    const summary = {
+      ok: checks.filter((c) => c.status === 'ok').length,
+      warn: checks.filter((c) => c.status === 'warn').length,
+      fail: checks.filter((c) => c.status === 'fail').length,
+    }
+
+    if (isJson) return { checks, summary }
+
+    await typewriterLine('Environment Diagnostics')
+    for (const check of checks) {
+      this.log('  ' + formatDoctorCheck(check))
+    }
+    this.log('\n' + formatDoctorSummary(summary))
+
+    const issues = checks.filter((c) => c.status !== 'ok')
+    if (issues.length > 0) {
+      this.log('\n' + chalk.yellow('Issues found:'))
+      for (const issue of issues) {
+        if (issue.hint) this.log(`  → ${issue.hint}`)
+      }
+    }
+
+    return { checks, summary }
+  }
+}