devvami 1.0.0

package/src/types.js

@@ -0,0 +1,228 @@
+/**
+ * @module types
+ * Shared JSDoc typedefs for the devvami CLI.
+ */
+
+/**
+ * @typedef {Object} CLIConfig
+ * @property {string} org - GitHub org name (e.g. "devvami")
+ * @property {string} awsProfile - Default aws-vault profile name
+ * @property {string} [awsRegion] - Default AWS region (fallback: eu-west-1)
+ * @property {string} [shell] - Detected shell: bash | zsh | fish
+ * @property {{ teamId?: string, teamName?: string, authMethod?: 'oauth' | 'personal_token' }} [clickup] - ClickUp workspace config
+ * @property {string} [lastVersionCheck] - ISO8601 timestamp of last version check
+ * @property {string} [latestVersion] - Latest known CLI version
+ */
+
+/**
+ * @typedef {'ok'|'warn'|'fail'} CheckStatus
+ */
+
+/**
+ * @typedef {Object} DoctorCheck
+ * @property {string} name - Component name (e.g. "Node.js")
+ * @property {CheckStatus} status - Check result
+ * @property {string|null} version - Found version (if applicable)
+ * @property {string|null} required - Minimum required version (if applicable)
+ * @property {string|null} hint - Actionable hint to fix the issue
+ */
+
+/**
+ * @typedef {Object} BranchName
+ * @property {'feature'|'fix'|'chore'|'hotfix'} type - Branch type
+ * @property {string} description - kebab-case description
+ * @property {string} full - Full branch name: `{type}/{description}`
+ */
+
+/**
+ * @typedef {Object} Developer
+ * @property {string} githubUsername
+ * @property {string} githubName
+ * @property {string[]} githubOrgs
+ * @property {string[]} githubTeams
+ * @property {string} [awsAccountId]
+ * @property {string} [awsArn]
+ * @property {string} [awsRegion]
+ * @property {string} cliVersion
+ */
+
+/**
+ * @typedef {Object} Template
+ * @property {string} name
+ * @property {string} description
+ * @property {string} language
+ * @property {string} htmlUrl
+ * @property {string} updatedAt
+ */
+
+/**
+ * @typedef {Object} Repository
+ * @property {string} name
+ * @property {string} description
+ * @property {string} language
+ * @property {string} htmlUrl
+ * @property {string} pushedAt
+ * @property {string[]} topics
+ * @property {boolean} isPrivate
+ */
+
+/**
+ * @typedef {'pass'|'fail'|'pending'} CIStatus
+ * @typedef {'approved'|'changes_requested'|'pending'} ReviewStatus
+ */
+
+/**
+ * @typedef {Object} PullRequest
+ * @property {number} number
+ * @property {string} title
+ * @property {string} state
+ * @property {string} htmlUrl
+ * @property {string} headBranch
+ * @property {string} baseBranch
+ * @property {boolean} isDraft
+ * @property {CIStatus} ciStatus
+ * @property {ReviewStatus} reviewStatus
+ * @property {boolean} mergeable
+ * @property {string} author
+ * @property {string[]} reviewers
+ */
+
+/**
+ * @typedef {Object} PRComment
+ * @property {number} id
+ * @property {string} author - GitHub login dell'autore
+ * @property {string} body - Corpo del commento in markdown
+ * @property {string} createdAt - ISO8601 timestamp
+ * @property {'issue'|'review'} type - Sorgente del commento
+ */
+
+/**
+ * @typedef {Object} QAStep
+ * @property {string} text - Testo dello step
+ * @property {boolean} checked - true se completato (`[x]`)
+ */
+
+/**
+ * @typedef {Object} PRDetail
+ * @property {number} number
+ * @property {string} title
+ * @property {string} state
+ * @property {string} htmlUrl
+ * @property {string} author
+ * @property {string} headBranch
+ * @property {string} baseBranch
+ * @property {boolean} isDraft
+ * @property {string[]} labels
+ * @property {string[]} reviewers
+ * @property {PRComment[]} qaComments - Commenti identificati come QA
+ * @property {QAStep[]} qaSteps - Step QA estratti dai commenti
+ */
+
+/**
+ * @typedef {'completed'|'in_progress'|'queued'} RunStatus
+ * @typedef {'success'|'failure'|'cancelled'|null} RunConclusion
+ */
+
+/**
+ * @typedef {Object} PipelineRun
+ * @property {number} id
+ * @property {string} name
+ * @property {RunStatus} status
+ * @property {RunConclusion} conclusion
+ * @property {string} branch
+ * @property {number} duration - seconds
+ * @property {string} actor
+ * @property {string} createdAt
+ * @property {string} htmlUrl
+ */
+
+/**
+ * @typedef {Object} ClickUpTask
+ * @property {string} id
+ * @property {string} name
+ * @property {string} status
+ * @property {string} statusType - ClickUp internal status type: 'open' | 'in_progress' | 'review' | 'custom' | 'closed'
+ * @property {number} priority - 1=urgent, 2=high, 3=normal, 4=low
+ * @property {string|null} startDate - YYYY-MM-DD local date, null if not set
+ * @property {string|null} dueDate - YYYY-MM-DD local date, null if not set
+ * @property {string} url
+ * @property {string[]} assignees
+ * @property {string|null} listId - ClickUp list ID the task belongs to
+ * @property {string|null} listName - ClickUp list name the task belongs to
+ * @property {string|null} folderId - ClickUp folder ID, null if list is at root level
+ * @property {string|null} folderName - ClickUp folder name, null if list is at root level
+ */
+
+/**
+ * @typedef {Object} AWSCostEntry
+ * @property {string} serviceName
+ * @property {number} amount
+ * @property {string} unit
+ * @property {{ start: string, end: string }} period
+ */
+
+/**
+ * @typedef {Object} ExecResult
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {number} exitCode
+ */
+
+/**
+ * @typedef {'macos'|'wsl2'|'linux'} Platform
+ */
+
+/**
+ * @typedef {Object} PlatformInfo
+ * @property {Platform} platform
+ * @property {string} openCommand - Command to open browser
+ * @property {string} credentialHelper - Git credential helper
+ */
+
+/**
+ * @typedef {Object} DocumentEntry
+ * @property {string} name - File name (e.g. "README.md")
+ * @property {string} path - Relative path in repo (e.g. "docs/architecture.md")
+ * @property {'readme'|'doc'|'swagger'|'asyncapi'} type - Classified doc type
+ * @property {number} size - File size in bytes
+ */
+
+/**
+ * @typedef {Object} RepoDocsIndex
+ * @property {string} repo - Repository name
+ * @property {boolean} hasReadme - Has at least one README file
+ * @property {number} docsCount - Number of files in docs/ folder
+ * @property {boolean} hasSwagger - Has at least one OpenAPI/Swagger file
+ * @property {boolean} hasAsyncApi - Has at least one AsyncAPI file
+ * @property {DocumentEntry[]} entries - Full list of DocumentEntry found
+ */
+
+/**
+ * @typedef {Object} SearchMatch
+ * @property {string} file - File path (e.g. "docs/deploy.md")
+ * @property {number} line - Line number (1-based)
+ * @property {string} context - Line text containing the match
+ * @property {number} occurrences - Total number of occurrences in the file
+ */
+
+/**
+ * @typedef {Object} APIEndpoint
+ * @property {string} method - HTTP method (GET, POST, PUT, PATCH, DELETE…)
+ * @property {string} path - Endpoint path (e.g. "/users/{id}")
+ * @property {string} summary - Operation summary
+ * @property {string} parameters - Comma-separated params; required ones marked with *
+ */
+
+/**
+ * @typedef {Object} AsyncChannel
+ * @property {string} channel - Channel name (e.g. "user/created")
+ * @property {string} operation - publish | subscribe | send | receive
+ * @property {string} summary - Operation summary
+ * @property {string} message - Message name/title or "—"
+ */
+
+/**
+ * @typedef {Object} DetectedRepo
+ * @property {string} owner - GitHub owner (org or user)
+ * @property {string} repo - Repository name
+ */

package/src/utils/banner.js

@@ -0,0 +1,48 @@
+import figlet from 'figlet'
+import chalk from 'chalk'
+import { BRAND_GRADIENT, animateGradientBanner, isColorEnabled } from './gradient.js'
+
+// Brand colors
+export const ORANGE = '#FF6B2B'
+export const BLUE = '#4A9EFF'
+
+/**
+ * Render figlet text as a Promise.
+ * @param {string} text
+ * @param {figlet.Options} opts
+ * @returns {Promise<string>}
+ */
+function figletAsync(text, opts) {
+  return new Promise((resolve, reject) =>
+    figlet.text(text, opts, (err, result) => (err ? reject(err) : resolve(result ?? ''))),
+  )
+}
+
+/**
+ * Print the devvami welcome banner con gradient animato ciano→blu→indaco.
+ * In ambienti non-TTY (CI, pipe, --json) stampa un banner statico senza ANSI.
+ * @returns {Promise<void>}
+ */
+export async function printBanner() {
+   const art = await figletAsync('DVMI', { font: 'ANSI Shadow' })
+   const artLines = art.split('\n').filter((l) => l.trim() !== '')
+   const width = Math.max(...artLines.map((l) => l.length)) + 4
+
+   const tagline = isColorEnabled
+     ? chalk.hex(BLUE).bold('  Devvami Developer CLI')
+     : '  Devvami Developer CLI'
+
+  const separator = isColorEnabled
+    ? chalk.hex(BLUE).dim('─'.repeat(Math.min(width, 60)))
+    : '─'.repeat(Math.min(width, 60))
+
+  process.stdout.write('\n')
+
+  // Anima ogni riga dell'ASCII art con gradient brand
+  await animateGradientBanner(artLines, BRAND_GRADIENT)
+
+  process.stdout.write(separator + '\n')
+  process.stdout.write(tagline + '\n')
+  process.stdout.write(separator + '\n')
+  process.stdout.write('\n')
+}

package/src/utils/errors.js

@@ -0,0 +1,61 @@
+/**
+ * Base CLI error with an actionable hint for the user.
+ */
+export class DvmiError extends Error {
+   /**
+    * @param {string} message - Human-readable error message
+    * @param {string} hint - Actionable suggestion to resolve the error
+    * @param {number} [exitCode] - Process exit code (default: 1)
+    */
+   constructor(message, hint, exitCode = 1) {
+     super(message)
+     this.name = 'DvmiError'
+    /** @type {string} */
+    this.hint = hint
+    /** @type {number} */
+    this.exitCode = exitCode
+  }
+}
+
+/**
+ * Validation error for invalid user input (exit code 2).
+ */
+export class ValidationError extends DvmiError {
+   /**
+    * @param {string} message
+    * @param {string} hint
+    */
+   constructor(message, hint) {
+     super(message, hint, 2)
+     this.name = 'ValidationError'
+   }
+ }
+
+ /**
+  * Auth error for missing or expired authentication.
+  */
+ export class AuthError extends DvmiError {
+   /**
+    * @param {string} service - Service name (e.g. "GitHub", "AWS")
+    */
+   constructor(service) {
+     super(
+       `${service} authentication required`,
+       `Run \`dvmi auth login\` to authenticate`,
+       1,
+     )
+     this.name = 'AuthError'
+   }
+ }
+
+ /**
+  * Format an error for display in the terminal.
+  * @param {Error} err
+  * @returns {string}
+  */
+ export function formatError(err) {
+   if (err instanceof DvmiError) {
+     return `Error: ${err.message}\nHint: ${err.hint}`
+   }
+   return `Error: ${err.message}`
+ }

package/src/utils/gradient.js

@@ -0,0 +1,130 @@
+import chalk from 'chalk'
+import readline from 'node:readline'
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Brand gradient: ciano → blu vivido → indaco
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {[number, number, number]} GradientStop
+ * RGB tuple: [red 0-255, green 0-255, blue 0-255]
+ */
+
+/** @type {GradientStop[]} */
+export const BRAND_GRADIENT = [
+  [0,   212, 255],  // #00D4FF — ciano elettrico
+  [0,   100, 255],  // #0064FF — blu vivido
+  [100,   0, 220],  // #6400DC — indaco profondo
+]
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Terminal capability flags
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** @type {boolean} true se chalk ha colori E NO_COLOR non è impostato */
+export const isColorEnabled = chalk.level > 0 && process.env.NO_COLOR === undefined
+
+/** @type {boolean} true se isTTY E isColorEnabled */
+export const isAnimationEnabled = process.stdout.isTTY === true && isColorEnabled
+
+// ──────────────────────────────────────────────────────────────────────────────
+// gradientText
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Colora ogni carattere del testo con un gradient RGB interpolato.
+ * Se chalk.level === 0 o NO_COLOR impostato, ritorna `text` invariato.
+ * Gli spazi non vengono colorati per evitare artefatti.
+ *
+ * @param {string}        text         - Testo da colorare
+ * @param {GradientStop[]} stops       - Almeno 2 color stops RGB
+ * @param {number}        [phase=0]    - Offset 0.0–1.0 per shift animato
+ * @returns {string}                   - Stringa ANSI-colorata, o text invariato se no-color
+ */
+export function gradientText(text, stops, phase = 0) {
+  if (!isColorEnabled) return text
+  if (stops.length < 2) throw new Error('At least 2 gradient stops required')
+
+  const chars = [...text]
+  const len = chars.length
+  if (len === 0) return ''
+
+  const segments = stops.length - 1
+
+  return chars.map((char, i) => {
+    if (char === ' ') return char
+
+    // Normalise t in [0, 1] with phase shift
+    const t = ((i / Math.max(len - 1, 1)) + phase) % 1
+
+    const seg = Math.min(Math.floor(t * segments), segments - 1)
+    const localT = t * segments - seg
+
+    const [r1, g1, b1] = stops[seg]
+    const [r2, g2, b2] = stops[seg + 1]
+
+    const r = Math.round(r1 + (r2 - r1) * localT)
+    const g = Math.round(g1 + (g2 - g1) * localT)
+    const b = Math.round(b1 + (b2 - b1) * localT)
+
+    return chalk.rgb(r, g, b)(char)
+  }).join('')
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// animateGradientBanner
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Anima un banner multi-riga con gradient in scrolling, poi si ferma.
+ * Se !isTTY o no-color, stampa le righe statiche con gradient e ritorna subito.
+ * Nasconde il cursore durante l'animazione e lo ripristina sempre.
+ *
+ * @param {string[]}      lines        - Righe del banner (output figlet)
+ * @param {GradientStop[]} stops       - Color stops
+ * @param {number}        [durationMs=1500] - Durata animazione in ms
+ * @returns {Promise<void>}
+ */
+export async function animateGradientBanner(lines, stops, durationMs = 1500) {
+  // Stampa sempre il banner statico prima (per terminali che non supportano animazione)
+  const printStatic = (phase = 0) => {
+    for (const line of lines) {
+      process.stdout.write(gradientText(line, stops, phase) + '\n')
+    }
+  }
+
+  if (!isAnimationEnabled) {
+    printStatic()
+    return
+  }
+
+  // Stampa il banner iniziale e prendi nota di quante righe occupa
+  printStatic()
+  process.stdout.write('\x1B[?25l') // nascondi cursore
+
+  let phase = 0
+  const intervalMs = 80
+  const frames = Math.ceil(durationMs / intervalMs)
+  let frameCount = 0
+
+  await new Promise((resolve) => {
+    const id = setInterval(() => {
+      frameCount++
+      phase = (phase + 0.03) % 1
+
+      // Risali di `lines.length` righe e ridisegna
+      readline.moveCursor(process.stdout, 0, -lines.length)
+      for (const line of lines) {
+        readline.clearLine(process.stdout, 0)
+        process.stdout.write(gradientText(line, stops, phase) + '\n')
+      }
+
+      if (frameCount >= frames) {
+        clearInterval(id)
+        resolve(undefined)
+      }
+    }, intervalMs)
+  })
+
+  process.stdout.write('\x1B[?25h') // ripristina cursore
+}

package/src/utils/open-browser.js

@@ -0,0 +1,29 @@
+import open from 'open'
+import { detectPlatform } from '../services/platform.js'
+import { exec } from '../services/shell.js'
+
+/**
+ * Open a URL in the default browser, using the platform-appropriate command.
+ * @param {string} url
+ * @returns {Promise<void>}
+ */
+export async function openBrowser(url) {
+  const { platform, openCommand } = await detectPlatform()
+
+  if (platform === 'macos') {
+    await open(url)
+    return
+  }
+
+  // WSL2: try wslview first, fallback to xdg-open
+  if (platform === 'wsl2') {
+    const wslview = await exec('wslview', [url])
+    if (wslview.exitCode === 0) return
+  }
+
+  // Linux / fallback
+  const result = await exec(openCommand, [url])
+  if (result.exitCode !== 0) {
+    await open(url) // final fallback via open package
+  }
+}

package/src/utils/typewriter.js

@@ -0,0 +1,48 @@
+import readline from 'node:readline'
+import { isAnimationEnabled, BRAND_GRADIENT, gradientText } from './gradient.js'
+
+/**
+ * Stampa testo con effetto typewriter (lettera per lettera).
+ * Se !isTTY o no-color, stampa tutto in una volta.
+ *
+ * @param {string}  text               - Testo da stampare
+ * @param {Object}  [opts]
+ * @param {number}  [opts.interval=30] - Ms per carattere
+ * @param {import('./gradient.js').GradientStop[]} [opts.gradient] - Se fornito, applica gradient
+ * @returns {Promise<void>}
+ */
+export async function typewriter(text, opts = {}) {
+  const { interval = 30, gradient } = opts
+
+  if (!isAnimationEnabled) {
+    const out = gradient ? gradientText(text, gradient) : text
+    process.stdout.write(out + '\n')
+    return
+  }
+
+  const chars = [...text]
+
+  for (let i = 0; i <= chars.length; i++) {
+    const partial = chars.slice(0, i).join('')
+    const colored = gradient ? gradientText(partial, gradient) : partial
+
+    readline.cursorTo(process.stdout, 0)
+    readline.clearLine(process.stdout, 0)
+    process.stdout.write(colored)
+
+    await new Promise((r) => setTimeout(r, interval))
+  }
+
+  process.stdout.write('\n')
+}
+
+/**
+ * Wrapper sintetico per typewriter con BRAND_GRADIENT di default.
+ *
+ * @param {string}  text               - Messaggio di completamento
+ * @param {import('./gradient.js').GradientStop[]} [gradient=BRAND_GRADIENT]
+ * @returns {Promise<void>}
+ */
+export async function typewriterLine(text, gradient = BRAND_GRADIENT) {
+  return typewriter(text, { gradient, interval: 25 })
+}

package/src/validators/repo-name.js

@@ -0,0 +1,42 @@
+const REPO_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const MAX_LENGTH = 100
+
+/**
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid
+ * @property {string} [error]
+ * @property {string} [suggestion]
+ */
+
+/**
+ * Validate a GitHub repository name.
+ * @param {string} name
+ * @returns {ValidationResult}
+ */
+export function validateRepoName(name) {
+  if (!name || name.length === 0) {
+    return { valid: false, error: 'Repository name cannot be empty' }
+  }
+
+  if (name.length > MAX_LENGTH) {
+    return {
+      valid: false,
+      error: `Repository name too long (${name.length} chars, max ${MAX_LENGTH})`,
+    }
+  }
+
+  if (!REPO_NAME_RE.test(name)) {
+    const suggested = name
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+    return {
+      valid: false,
+      error: `Repository name must be lowercase kebab-case. Got "${name}"`,
+      suggestion: suggested,
+    }
+  }
+
+  return { valid: true }
+}