devvami 1.0.0

package/src/services/clickup.js

@@ -0,0 +1,288 @@
+import http from 'node:http'
+import { openBrowser } from '../utils/open-browser.js'
+import { loadConfig } from './config.js'
+
+/** @import { ClickUpTask } from '../types.js' */
+
+const API_BASE = process.env.CLICKUP_API_BASE ?? 'https://api.clickup.com/api/v2'
+const TOKEN_KEY = 'clickup_token'
+
+/**
+ * Format a Date as a local YYYY-MM-DD string (avoids UTC offset issues).
+ * @param {Date} date
+ * @returns {string}
+ */
+function localDateString(date) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`
+}
+
+/**
+ * Get stored ClickUp OAuth token.
+ * Reads from (in order): CLICKUP_TOKEN env var, OS keychain, config file.
+ * @returns {Promise<string|null>}
+ */
+async function getToken() {
+  // Allow tests / CI to inject a token via environment variable
+  if (process.env.CLICKUP_TOKEN) return process.env.CLICKUP_TOKEN
+   try {
+     const { default: keytar } = await import('keytar')
+     return keytar.getPassword('devvami', TOKEN_KEY)
+   } catch {
+    // keytar not available (e.g. WSL2 without D-Bus) — fallback to config
+    const config = await loadConfig()
+    return config.clickup?.token ?? null
+  }
+}
+
+/**
+ * Store ClickUp token securely (works for both OAuth and Personal API Tokens).
+ * @param {string} token
+ * @returns {Promise<void>}
+ */
+export async function storeToken(token) {
+   try {
+     const { default: keytar } = await import('keytar')
+     await keytar.setPassword('devvami', TOKEN_KEY, token)
+   } catch {
+    // Fallback: store in config (less secure)
+    const config = await loadConfig()
+    await saveConfig({ ...config, clickup: { ...config.clickup, token } })
+  }
+}
+
+/**
+ * Run the ClickUp OAuth localhost redirect flow.
+ * @param {string} clientId
+ * @param {string} clientSecret
+ * @returns {Promise<string>} Access token
+ */
+export async function oauthFlow(clientId, clientSecret) {
+  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')
+      if (!code) return
+      res.end('Authorization successful! You can close this tab.')
+      server.close()
+      try {
+        const resp = await fetch(`${API_BASE}/oauth/token`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ client_id: clientId, client_secret: clientSecret, code }),
+        })
+        const data = /** @type {any} */ (await resp.json())
+        await storeToken(data.access_token)
+        resolve(data.access_token)
+      } catch (err) {
+        reject(err)
+      }
+    })
+    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)}`
+      await openBrowser(authUrl)
+    })
+    server.on('error', reject)
+  })
+}
+
+/**
+ * Make an authenticated request to the ClickUp API.
+ * @param {string} path
+ * @returns {Promise<unknown>}
+ */
+ async function clickupFetch(path) {
+   const token = await getToken()
+   if (!token) throw new Error('ClickUp not authenticated. Run `dvmi init` to authorize.')
+  const resp = await fetch(`${API_BASE}${path}`, {
+    headers: { Authorization: token },
+  })
+  if (resp.status === 429) {
+    const reset = Number(resp.headers.get('X-RateLimit-Reset') ?? Date.now() + 1000)
+    await new Promise((r) => setTimeout(r, Math.max(reset - Date.now(), 1000)))
+    return clickupFetch(path)
+  }
+  if (!resp.ok) {
+    const body = /** @type {any} */ (await resp.json().catch(() => ({})))
+    throw new Error(`ClickUp API ${resp.status}: ${body.err ?? resp.statusText}`)
+  }
+  return resp.json()
+}
+
+/**
+ * Get ClickUp user info (used to get user ID for filtering tasks).
+ * @returns {Promise<{ id: string, username: string }>}
+ */
+export async function getUser() {
+  const data = /** @type {any} */ (await clickupFetch('/user'))
+  return { id: String(data.user.id), username: data.user.username }
+}
+
+/**
+ * Map a raw ClickUp API task object to the normalized ClickUpTask shape.
+ * @param {any} t - Raw task object from the ClickUp API response
+ * @returns {ClickUpTask}
+ */
+function mapTask(t) {
+  const folderHidden = t.folder?.hidden === true
+  return {
+    id: t.id,
+    name: t.name,
+    status: t.status?.status ?? '',
+    statusType: t.status?.type ?? 'open',
+    priority: t.priority?.id ? Number(t.priority.id) : 3,
+    startDate: t.start_date ? localDateString(new Date(Number(t.start_date))) : null,
+    dueDate: t.due_date ? localDateString(new Date(Number(t.due_date))) : null,
+    url: t.url,
+    assignees: (t.assignees ?? []).map((a) => a.username),
+    listId: t.list?.id ?? null,
+    listName: t.list?.name ?? null,
+    folderId: folderHidden ? null : (t.folder?.id ?? null),
+    folderName: folderHidden ? null : (t.folder?.name ?? null),
+  }
+}
+
+/**
+ * Get tasks assigned to the current user, with automatic pagination.
+ * @param {string} teamId - ClickUp workspace/team ID
+ * @param {{ status?: string, due_date_lt?: number }} [filters]
+ * @param {((count: number) => void)} [onProgress] - Called after each page with cumulative task count
+ * @returns {Promise<ClickUpTask[]>}
+ */
+export async function getTasks(teamId, filters = {}, onProgress) {
+  let basePath = `/team/${teamId}/task?assignees[]=${(await getUser()).id}`
+  if (filters.status) basePath += `&statuses[]=${encodeURIComponent(filters.status)}`
+  if (filters.due_date_lt != null) basePath += `&due_date_lt=${filters.due_date_lt}`
+
+  let page = 0
+  /** @type {ClickUpTask[]} */
+  const allTasks = []
+  let hasMore = true
+
+  while (hasMore) {
+    const data = /** @type {any} */ (await clickupFetch(`${basePath}&page=${page}`))
+    allTasks.push(...data.tasks.map(mapTask))
+    hasMore = data.has_more ?? false
+    page++
+    if (onProgress) onProgress(allTasks.length)
+  }
+
+  return allTasks
+}
+
+/**
+ * Get tasks active today: runs two parallel requests (due today/overdue + in progress)
+ * and deduplicates by task ID. Excludes tasks whose status type is 'closed'.
+ * @param {string} teamId
+ * @returns {Promise<ClickUpTask[]>}
+ */
+export async function getTasksToday(teamId) {
+  const endOfTodayMs = new Date().setHours(23, 59, 59, 999)
+
+  const [overdueTasks, inProgressTasks] = await Promise.all([
+    getTasks(teamId, { due_date_lt: endOfTodayMs }),
+    getTasks(teamId, { status: 'in progress' }),
+  ])
+
+  // De-duplicate by task ID (a task may appear in both result sets)
+  /** @type {Map<string, ClickUpTask>} */
+  const seen = new Map()
+  for (const t of [...overdueTasks, ...inProgressTasks]) seen.set(t.id, t)
+  const merged = [...seen.values()]
+
+  const today = localDateString(new Date())
+
+  return merged.filter((t) => {
+    // Exclude tasks that ClickUp considers closed (done/completed regardless of language)
+    if (t.statusType === 'closed') return false
+
+    const start = t.startDate
+    const due = t.dueDate
+
+    // Always include overdue tasks (due date in the past, not closed)
+    if (due && due < today) return true
+
+    // today is within [startDate, dueDate]
+    if (start && due) return start <= today && today <= due
+    if (start && !due) return start <= today
+    // No startDate: include only if due today (overdue already handled above)
+    if (!start && due) return today === due
+
+    // No dates at all: fall back to in-progress status keyword
+    const status = t.status?.toLowerCase().replace(/_/g, ' ') ?? ''
+    return status.includes('in progress')
+  })
+}
+
+/**
+ * Get tasks from a specific ClickUp list, with automatic pagination.
+ * @param {string} listId - ClickUp list ID
+ * @param {{ status?: string }} [filters]
+ * @param {((count: number) => void)} [onProgress] - Called after each page with cumulative task count
+ * @returns {Promise<ClickUpTask[]>}
+ * @throws {Error} If the list is not found or not accessible (404)
+ */
+export async function getTasksByList(listId, filters = {}, onProgress) {
+  let basePath = `/list/${listId}/task?include_closed=false`
+  if (filters.status) basePath += `&statuses[]=${encodeURIComponent(filters.status)}`
+
+  let page = 0
+  /** @type {ClickUpTask[]} */
+  const allTasks = []
+  let hasMore = true
+
+  while (hasMore) {
+    let data
+    try {
+      data = /** @type {any} */ (await clickupFetch(`${basePath}&page=${page}`))
+    } catch (err) {
+      if (err instanceof Error && err.message.includes('404')) {
+        throw new Error("Lista non trovata o non accessibile. Verifica l'ID con l'URL della lista in ClickUp.")
+      }
+      throw err
+    }
+    allTasks.push(...data.tasks.map(mapTask))
+    hasMore = data.has_more ?? false
+    page++
+    if (onProgress) onProgress(allTasks.length)
+  }
+
+  return allTasks
+}
+
+/**
+ * Check if ClickUp is authenticated.
+ * @returns {Promise<boolean>}
+ */
+export async function isAuthenticated() {
+  const token = await getToken()
+  return Boolean(token)
+}
+
+/**
+ * Validate the stored ClickUp token by calling the /user endpoint.
+ * Returns { valid: true, user } on success, { valid: false } on 401.
+ * @returns {Promise<{ valid: boolean, user?: { id: number, username: string } }>}
+ */
+export async function validateToken() {
+  try {
+    const data = /** @type {any} */ (await clickupFetch('/user'))
+    return { valid: true, user: { id: data.user.id, username: data.user.username } }
+  } catch (err) {
+    // 401 or no token → not valid
+    if (err instanceof Error && (err.message.includes('401') || err.message.includes('not authenticated'))) {
+      return { valid: false }
+    }
+    throw err
+  }
+}
+
+/**
+ * Get the list of ClickUp teams/workspaces accessible with the stored token.
+ * @returns {Promise<Array<{ id: string, name: string }>>}
+ */
+export async function getTeams() {
+  const data = /** @type {any} */ (await clickupFetch('/team'))
+  return (data.teams ?? []).map((t) => ({ id: String(t.id), name: t.name }))
+}

package/src/services/config.js

@@ -0,0 +1,59 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+/** @import { CLIConfig } from '../types.js' */
+
+const CONFIG_DIR = process.env.XDG_CONFIG_HOME
+   ? join(process.env.XDG_CONFIG_HOME, 'dvmi')
+   : join(homedir(), '.config', 'dvmi')
+
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json')
+
+/** @type {CLIConfig} */
+const DEFAULTS = {
+  org: '',
+  awsProfile: '',
+  awsRegion: 'eu-west-1',
+  shell: '',
+  clickup: {},
+}
+
+/**
+ * Load CLI config from disk. Returns defaults if file doesn't exist.
+ * @param {string} [configPath] - Override config path (used in tests)
+ * @returns {Promise<CLIConfig>}
+ */
+export async function loadConfig(configPath = process.env.DVMI_CONFIG_PATH ?? CONFIG_PATH) {
+  if (!existsSync(configPath)) return { ...DEFAULTS }
+  try {
+    const raw = await readFile(configPath, 'utf8')
+    return { ...DEFAULTS, ...JSON.parse(raw) }
+  } catch {
+    return { ...DEFAULTS }
+  }
+}
+
+/**
+ * Save CLI config to disk, creating directory if needed.
+ * @param {CLIConfig} config
+ * @param {string} [configPath] - Override config path (used in tests)
+ * @returns {Promise<void>}
+ */
+export async function saveConfig(config, configPath = CONFIG_PATH) {
+  const dir = configPath.replace(/\/[^/]+$/, '')
+  if (!existsSync(dir)) {
+    await mkdir(dir, { recursive: true })
+  }
+  await writeFile(configPath, JSON.stringify(config, null, 2), 'utf8')
+}
+
+/**
+ * Check whether config exists on disk.
+ * @param {string} [configPath]
+ * @returns {boolean}
+ */
+export function configExists(configPath = CONFIG_PATH) {
+  return existsSync(configPath)
+}

package/src/services/docs.js

@@ -0,0 +1,210 @@
+import { createOctokit } from './github.js'
+import { exec } from './shell.js'
+import { isOpenApi, isAsyncApi } from '../formatters/openapi.js'
+import { load } from 'js-yaml'
+
+/** @import { DocumentEntry, RepoDocsIndex, SearchMatch, DetectedRepo } from '../types.js' */
+
+/**
+ * Detect GitHub owner and repo from git remote in the current working directory.
+ * @returns {Promise<DetectedRepo>}
+ */
+export async function detectCurrentRepo() {
+  const result = await exec('git', ['remote', 'get-url', 'origin'])
+  if (result.exitCode !== 0) {
+    throw new Error('Not in a git repository. Use --repo to specify a repository.')
+  }
+  const match = result.stdout.match(/github\.com[:/]([^/]+)\/([^/.]+?)(\.git)?$/)
+  if (!match) {
+    throw new Error('Could not detect GitHub repository from git remote. Use --repo to specify a repository.')
+  }
+  return { owner: match[1], repo: match[2] }
+}
+
+/**
+ * Classify a tree entry as a DocumentEntry, or null if it is not a doc file.
+ * @param {{ path: string, size: number }} entry
+ * @returns {DocumentEntry|null}
+ */
+function classifyEntry(entry) {
+  const { size } = entry
+  const path = entry.path
+  if (size === 0) return null
+  const name = path.split('/').pop() ?? path
+
+  if (/^readme\.(md|rst|txt)$/i.test(path)) {
+    return { name, path, type: 'readme', size }
+  }
+  if (/(openapi|swagger)\.(ya?ml|json)$/i.test(path)) {
+    return { name, path, type: 'swagger', size }
+  }
+  if (/asyncapi\.(ya?ml|json)$/i.test(path)) {
+    return { name, path, type: 'asyncapi', size }
+  }
+  if (path.startsWith('docs/') && /\.(md|rst|txt)$/.test(path)) {
+    return { name, path, type: 'doc', size }
+  }
+  return null
+}
+
+/**
+ * Sort DocumentEntry by type priority then path.
+ * @param {DocumentEntry} a
+ * @param {DocumentEntry} b
+ * @returns {number}
+ */
+function sortEntries(a, b) {
+  const order = { readme: 0, swagger: 1, asyncapi: 2, doc: 3 }
+  const diff = order[a.type] - order[b.type]
+  return diff !== 0 ? diff : a.path.localeCompare(b.path)
+}
+
+/**
+ * List documentation files in a repository using the GitHub Tree API.
+ * @param {string} owner
+ * @param {string} repo
+ * @returns {Promise<DocumentEntry[]>}
+ */
+export async function listDocs(owner, repo) {
+  const octokit = await createOctokit()
+
+  // 1. Get default branch
+  const { data: repoData } = await octokit.rest.repos.get({ owner, repo })
+  const defaultBranch = repoData.default_branch
+
+  // 2. Get HEAD SHA
+  const { data: ref } = await octokit.rest.git.getRef({
+    owner,
+    repo,
+    ref: `heads/${defaultBranch}`,
+  })
+
+  // 3. Fetch full recursive tree
+  const { data: tree } = await octokit.rest.git.getTree({
+    owner,
+    repo,
+    tree_sha: ref.object.sha,
+    recursive: '1',
+  })
+
+  /** @type {DocumentEntry[]} */
+  const entries = []
+  for (const e of tree.tree) {
+    if (e.type !== 'blob') continue
+    const entry = classifyEntry({ path: e.path ?? '', size: e.size ?? 0 })
+    if (entry) entries.push(entry)
+  }
+  return entries.sort(sortEntries)
+}
+
+/**
+ * Read a file's raw content from a repository via GitHub Contents API.
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} path
+ * @returns {Promise<string>}
+ */
+export async function readFile(owner, repo, path) {
+  const octokit = await createOctokit()
+  const { data } = await octokit.rest.repos.getContent({ owner, repo, path })
+  if (Array.isArray(data) || data.type !== 'file') {
+    throw new Error(`"${path}" is not a file.`)
+  }
+  return Buffer.from(data.content, 'base64').toString('utf8')
+}
+
+/**
+ * Search documentation files in a repository for a given term.
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} term
+ * @returns {Promise<SearchMatch[]>}
+ */
+export async function searchDocs(owner, repo, term) {
+  const entries = await listDocs(owner, repo)
+  const q = term.toLowerCase()
+
+  /** @type {SearchMatch[]} */
+  const allMatches = []
+
+  for (const entry of entries) {
+    let content
+    try {
+      content = await readFile(owner, repo, entry.path)
+    } catch {
+      continue
+    }
+    const lines = content.split('\n')
+    let occurrences = 0
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].toLowerCase().includes(q)) {
+        occurrences++
+        allMatches.push({
+          file: entry.path,
+          line: i + 1,
+          context: lines[i].trim(),
+          occurrences: 0, // filled below
+        })
+      }
+    }
+    // Back-fill occurrences count for all matches from this file
+    for (const m of allMatches) {
+      if (m.file === entry.path) m.occurrences = occurrences
+    }
+  }
+
+  return allMatches
+}
+
+/**
+ * Build a RepoDocsIndex for every repository in an org.
+ * @param {string} org
+ * @param {string[]} repoNames - List of repo names to scan
+ * @returns {Promise<RepoDocsIndex[]>}
+ */
+export async function listProjectsDocs(org, repoNames) {
+  /** @type {RepoDocsIndex[]} */
+  const indexes = []
+
+  for (const repoName of repoNames) {
+    let entries
+    try {
+      entries = await listDocs(org, repoName)
+    } catch {
+      entries = []
+    }
+    indexes.push({
+      repo: repoName,
+      hasReadme: entries.some((e) => e.type === 'readme'),
+      docsCount: entries.filter((e) => e.type === 'doc').length,
+      hasSwagger: entries.some((e) => e.type === 'swagger'),
+      hasAsyncApi: entries.some((e) => e.type === 'asyncapi'),
+      entries,
+    })
+  }
+
+  return indexes
+}
+
+/**
+ * Detect whether a file path is an API spec (swagger or asyncapi).
+ * Returns the type or null.
+ * @param {string} path
+ * @param {string} content
+ * @returns {'swagger'|'asyncapi'|null}
+ */
+export function detectApiSpecType(path, content) {
+  if (/(openapi|swagger)\.(ya?ml|json)$/i.test(path)) return 'swagger'
+  if (/asyncapi\.(ya?ml|json)$/i.test(path)) return 'asyncapi'
+  // Try to detect from content
+  try {
+    const doc = /^\s*\{/.test(content.trim())
+      ? JSON.parse(content)
+      : load(content)
+    if (doc && typeof doc === 'object') {
+      if (isOpenApi(/** @type {Record<string, unknown>} */ (doc))) return 'swagger'
+      if (isAsyncApi(/** @type {Record<string, unknown>} */ (doc))) return 'asyncapi'
+    }
+  } catch { /* ignore */ }
+  return null
+}