devvami 1.2.0 → 1.3.0

package/src/services/aws-costs.js

@@ -1,6 +1,6 @@
 import { CostExplorerClient, GetCostAndUsageCommand } from '@aws-sdk/client-cost-explorer'
 
-/** @import { AWSCostEntry } from '../types.js' */
+/** @import { AWSCostEntry, CostGroupMode, CostTrendSeries } from '../types.js' */
 
 /**
  * Get the date range for a cost period.
@@ -28,14 +28,62 @@ function getPeriodDates(period) {
   return { start: fmt(start), end: fmt(now) }
 }
 
+/**
+ * Get the rolling 2-month date range for trend queries.
+ * @returns {{ start: string, end: string }}
+ */
+export function getTwoMonthPeriod() {
+  const now = new Date()
+  const fmt = (d) => d.toISOString().split('T')[0]
+  const start = new Date(now.getFullYear(), now.getMonth() - 2, 1)
+  return { start: fmt(start), end: fmt(now) }
+}
+
+/**
+ * Strip the "tagkey$" prefix from an AWS tag group key response.
+ * AWS returns tag values as "<tagKey>$<value>" — strip the prefix.
+ * An empty stripped value is displayed as "(untagged)".
+ * @param {string} rawKey - Raw key from AWS response (e.g. "env$prod" or "env$")
+ * @returns {string}
+ */
+function stripTagPrefix(rawKey) {
+  const dollarIdx = rawKey.indexOf('$')
+  if (dollarIdx === -1) return rawKey
+  const stripped = rawKey.slice(dollarIdx + 1)
+  return stripped === '' ? '(untagged)' : stripped
+}
+
+/**
+ * Build the GroupBy array for Cost Explorer based on the grouping mode.
+ * AWS limits GroupBy to max 2 entries.
+ * @param {CostGroupMode} groupBy
+ * @param {string} [tagKey]
+ * @returns {Array<{Type: string, Key: string}>}
+ */
+function buildGroupBy(groupBy, tagKey) {
+  if (groupBy === 'service') {
+    return [{ Type: 'DIMENSION', Key: 'SERVICE' }]
+  }
+  if (groupBy === 'tag') {
+    return [{ Type: 'TAG', Key: tagKey ?? '' }]
+  }
+  // both
+  return [
+    { Type: 'DIMENSION', Key: 'SERVICE' },
+    { Type: 'TAG', Key: tagKey ?? '' },
+  ]
+}
+
 /**
  * Query AWS Cost Explorer for costs filtered by project tags.
  * @param {string} serviceName - Tag value for filtering
  * @param {Record<string, string>} tags - Project tags (key-value pairs)
  * @param {'last-month'|'last-week'|'mtd'} [period]
+ * @param {CostGroupMode} [groupBy]
+ * @param {string} [tagKey]
  * @returns {Promise<{ entries: AWSCostEntry[], period: { start: string, end: string } }>}
  */
-export async function getServiceCosts(serviceName, tags, period = 'last-month') {
+export async function getServiceCosts(serviceName, tags, period = 'last-month', groupBy = 'service', tagKey) {
   // Cost Explorer always uses us-east-1
   const client = new CostExplorerClient({ region: 'us-east-1' })
   const { start, end } = getPeriodDates(period)
@@ -56,7 +104,7 @@ export async function getServiceCosts(serviceName, tags, period = 'last-month')
     Granularity: 'MONTHLY',
     Metrics: ['UnblendedCost'],
     Filter: filter,
-    GroupBy: [{ Type: 'DIMENSION', Key: 'SERVICE' }],
+    GroupBy: buildGroupBy(groupBy, tagKey),
   })
 
   const result = await client.send(command)
@@ -66,15 +114,91 @@ export async function getServiceCosts(serviceName, tags, period = 'last-month')
     for (const group of timeResult.Groups ?? []) {
       const amount = Number(group.Metrics?.UnblendedCost?.Amount ?? 0)
       if (amount > 0) {
-        entries.push({
-          serviceName: group.Keys?.[0] ?? 'Unknown',
+        const keys = group.Keys ?? []
+        /** @type {AWSCostEntry} */
+        const entry = {
+          serviceName: groupBy === 'tag' ? stripTagPrefix(keys[0] ?? '') : (keys[0] ?? 'Unknown'),
           amount,
           unit: group.Metrics?.UnblendedCost?.Unit ?? 'USD',
           period: { start, end },
-        })
+        }
+        if (groupBy === 'both') {
+          entry.tagValue = stripTagPrefix(keys[1] ?? '')
+        } else if (groupBy === 'tag') {
+          entry.tagValue = entry.serviceName
+        }
+        entries.push(entry)
       }
     }
   }
 
   return { entries, period: { start, end } }
 }
+
+/**
+ * Query AWS Cost Explorer for daily costs over the last 2 months, grouped by the given mode.
+ * Handles NextPageToken pagination internally.
+ * @param {CostGroupMode} groupBy
+ * @param {string} [tagKey]
+ * @returns {Promise<CostTrendSeries[]>}
+ */
+export async function getTrendCosts(groupBy = 'service', tagKey) {
+  const client = new CostExplorerClient({ region: 'us-east-1' })
+  const { start, end } = getTwoMonthPeriod()
+
+  /** @type {Map<string, Map<string, number>>} seriesName → date → amount */
+  const seriesMap = new Map()
+
+  let nextPageToken = undefined
+  do {
+    const command = new GetCostAndUsageCommand({
+      TimePeriod: { Start: start, End: end },
+      Granularity: 'DAILY',
+      Metrics: ['UnblendedCost'],
+      GroupBy: buildGroupBy(groupBy, tagKey),
+      ...(nextPageToken ? { NextPageToken: nextPageToken } : {}),
+    })
+
+    const result = await client.send(command)
+    nextPageToken = result.NextPageToken
+
+    for (const timeResult of result.ResultsByTime ?? []) {
+      const date = timeResult.TimePeriod?.Start ?? ''
+      for (const group of timeResult.Groups ?? []) {
+        const amount = Number(group.Metrics?.UnblendedCost?.Amount ?? 0)
+        const keys = group.Keys ?? []
+
+        let seriesName
+        if (groupBy === 'service') {
+          seriesName = keys[0] ?? 'Unknown'
+        } else if (groupBy === 'tag') {
+          seriesName = stripTagPrefix(keys[0] ?? '')
+        } else {
+          // both: "ServiceName / tagValue"
+          const svc = keys[0] ?? 'Unknown'
+          const tag = stripTagPrefix(keys[1] ?? '')
+          seriesName = `${svc} / ${tag}`
+        }
+
+        if (!seriesMap.has(seriesName)) {
+          seriesMap.set(seriesName, new Map())
+        }
+        const dateMap = seriesMap.get(seriesName)
+        dateMap.set(date, (dateMap.get(date) ?? 0) + amount)
+      }
+    }
+  } while (nextPageToken)
+
+  /** @type {CostTrendSeries[]} */
+  const series = []
+  for (const [name, dateMap] of seriesMap) {
+    const points = Array.from(dateMap.entries())
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([date, amount]) => ({ date, amount }))
+    if (points.some((p) => p.amount > 0)) {
+      series.push({ name, points })
+    }
+  }
+
+  return series
+}

package/src/services/cloudwatch-logs.js

@@ -0,0 +1,92 @@
+import {
+  CloudWatchLogsClient,
+  paginateDescribeLogGroups,
+  FilterLogEventsCommand,
+} from '@aws-sdk/client-cloudwatch-logs'
+
+/** @import { LogGroup, LogEvent, LogFilterResult } from '../types.js' */
+
+/**
+ * Convert a human-readable "since" string to epoch millisecond timestamps.
+ * @param {'1h'|'24h'|'7d'} since
+ * @returns {{ startTime: number, endTime: number }}
+ */
+export function sinceToEpochMs(since) {
+  const now = Date.now()
+  const MS = {
+    '1h': 60 * 60 * 1000,
+    '24h': 24 * 60 * 60 * 1000,
+    '7d': 7 * 24 * 60 * 60 * 1000,
+  }
+  const offset = MS[since]
+  if (!offset) throw new Error(`Invalid since value: ${since}. Must be one of: 1h, 24h, 7d`)
+  return { startTime: now - offset, endTime: now }
+}
+
+/**
+ * List all CloudWatch log groups in the given region using pagination.
+ * @param {string} [region] - AWS region (defaults to 'eu-west-1')
+ * @returns {Promise<LogGroup[]>}
+ */
+export async function listLogGroups(region = 'eu-west-1') {
+  const client = new CloudWatchLogsClient({ region })
+  /** @type {LogGroup[]} */
+  const groups = []
+
+  const paginator = paginateDescribeLogGroups({ client }, {})
+  for await (const page of paginator) {
+    for (const lg of page.logGroups ?? []) {
+      groups.push({
+        name: lg.logGroupName ?? '',
+        storedBytes: lg.storedBytes,
+        retentionDays: lg.retentionInDays,
+        creationTime: lg.creationTime ? new Date(lg.creationTime).toISOString() : undefined,
+      })
+    }
+  }
+
+  return groups
+}
+
+/**
+ * Filter log events from a CloudWatch log group.
+ * @param {string} logGroupName
+ * @param {string} filterPattern - CloudWatch filter pattern ('' = all events)
+ * @param {number} startTime - Epoch milliseconds
+ * @param {number} endTime - Epoch milliseconds
+ * @param {number} limit - Max events to return (1–10000)
+ * @param {string} [region] - AWS region (defaults to 'eu-west-1')
+ * @returns {Promise<LogFilterResult>}
+ */
+export async function filterLogEvents(logGroupName, filterPattern, startTime, endTime, limit, region = 'eu-west-1') {
+  const client = new CloudWatchLogsClient({ region })
+
+  const command = new FilterLogEventsCommand({
+    logGroupName,
+    filterPattern: filterPattern || undefined,
+    startTime,
+    endTime,
+    limit,
+  })
+
+  const result = await client.send(command)
+
+  /** @type {LogEvent[]} */
+  const events = (result.events ?? []).map((e) => ({
+    eventId: e.eventId ?? '',
+    logStreamName: e.logStreamName ?? '',
+    timestamp: e.timestamp ?? 0,
+    message: e.message ?? '',
+  }))
+
+  const truncated = events.length >= limit || Boolean(result.nextToken)
+
+  return {
+    events,
+    truncated,
+    logGroupName,
+    startTime,
+    endTime,
+    filterPattern: filterPattern ?? '',
+  }
+}

package/src/services/config.js

@@ -1,5 +1,5 @@
 import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
 
@@ -58,3 +58,19 @@ export async function saveConfig(config, configPath = CONFIG_PATH) {
 export function configExists(configPath = CONFIG_PATH) {
   return existsSync(configPath)
 }
+
+/**
+ * Load CLI config synchronously. Intended for use in static getters where async is unavailable.
+ * Returns defaults if file doesn't exist or cannot be parsed.
+ * @param {string} [configPath] - Override config path (used in tests)
+ * @returns {CLIConfig}
+ */
+export function loadConfigSync(configPath = process.env.DVMI_CONFIG_PATH ?? CONFIG_PATH) {
+  if (!existsSync(configPath)) return { ...DEFAULTS }
+  try {
+    const raw = readFileSync(configPath, 'utf8')
+    return { ...DEFAULTS, ...JSON.parse(raw) }
+  } catch {
+    return { ...DEFAULTS }
+  }
+}

package/src/types.js

@@ -189,10 +189,72 @@
 
 /**
  * @typedef {Object} AWSCostEntry
- * @property {string} serviceName
- * @property {number} amount
- * @property {string} unit
- * @property {{ start: string, end: string }} period
+ * @property {string} serviceName        - AWS service name (e.g. "Amazon EC2"), or tag value label for tag grouping
+ * @property {string} [tagValue]         - Tag value when grouping by TAG or BOTH (e.g. "prod"); undefined for service-only grouping
+ * @property {number} amount             - Cost amount (USD)
+ * @property {string} unit               - Currency unit (always "USD")
+ * @property {{ start: string, end: string }} period - ISO date range (YYYY-MM-DD)
+ */
+
+/**
+ * @typedef {'service' | 'tag' | 'both'} CostGroupMode
+ * The dimension used to group cost entries.
+ * - 'service': group by AWS service name (default, backward-compatible)
+ * - 'tag': group by a tag key's values (requires tagKey)
+ * - 'both': group by AWS service + tag value simultaneously
+ */
+
+/**
+ * @typedef {Object} CostTrendPoint
+ * @property {string} date     - ISO date (YYYY-MM-DD) for this data point
+ * @property {number} amount   - Total cost for this day (USD)
+ * @property {string} [label]  - Display label: serviceName for service/both grouping,
+ *                               tag value for tag grouping; omitted when not multi-series
+ */
+
+/**
+ * @typedef {Object} CostTrendSeries
+ * @property {string} name          - Series label (service name or tag value)
+ * @property {CostTrendPoint[]} points - Ordered daily data points (ascending by date)
+ */
+
+/**
+ * @typedef {Object} LogGroup
+ * @property {string} name              - Full log group name (e.g. "/aws/lambda/my-fn")
+ * @property {number} [storedBytes]     - Total stored bytes (may be absent for empty groups)
+ * @property {number} [retentionDays]   - Retention policy in days; undefined = never expire
+ * @property {string} [creationTime]    - ISO8601 creation timestamp
+ */
+
+/**
+ * @typedef {Object} LogEvent
+ * @property {string} eventId         - Unique event ID assigned by CloudWatch
+ * @property {string} logStreamName   - Stream within the log group (e.g. "2026/03/26/[$LATEST]abc")
+ * @property {number} timestamp       - Event time as epoch milliseconds
+ * @property {string} message         - Raw log message text
+ */
+
+/**
+ * @typedef {Object} LogFilterResult
+ * @property {LogEvent[]} events      - Matched log events (up to --limit)
+ * @property {boolean} truncated      - True when the result was capped by --limit or AWS pagination
+ * @property {string} logGroupName    - The log group that was queried
+ * @property {number} startTime       - Query start as epoch milliseconds
+ * @property {number} endTime         - Query end as epoch milliseconds
+ * @property {string} filterPattern   - The pattern used ('' = no filter)
+ */
+
+/**
+ * @typedef {Object} ChartBarData
+ * @property {string} name    - Row label (service name, tag value, or "service / tag")
+ * @property {number} value   - Cost amount (USD)
+ */
+
+/**
+ * @typedef {Object} ChartSeries
+ * @property {string} name      - Series label displayed in legend
+ * @property {number[]} values  - Ordered numeric values (one per day, ~60 for 2 months)
+ * @property {string[]} labels  - Date labels matching values array (YYYY-MM-DD)
  */
 
 /**

package/src/utils/aws-vault.js

@@ -0,0 +1,144 @@
+import { loadConfigSync } from '../services/config.js'
+import { execa } from 'execa'
+
+/**
+ * Returns the aws-vault exec prefix to prepend to AWS CLI commands.
+ *
+ * Detection order:
+ *   1. process.env.AWS_VAULT  — set by `aws-vault exec` at runtime in the child process
+ *   2. config.awsProfile      — if an already-loaded config object is passed (avoids sync I/O)
+ *   3. loadConfigSync()       — synchronous fallback for static getters where async is unavailable
+ *
+ * @param {{ awsProfile?: string } | null} [config] - Already-loaded config (optional).
+ *   Pass this when the caller has already loaded config asynchronously to avoid a redundant sync read.
+ * @returns {string} e.g. `"aws-vault exec myprofile -- "` or `""`
+ *
+ * @example
+ * // Inside an async run() method where config is already loaded:
+ * const prefix = awsVaultPrefix(config)
+ * this.error(`No credentials. Use: ${prefix}dvmi costs get`)
+ *
+ * @example
+ * // Inside a static getter (no async available):
+ * static get examples() {
+ *   const prefix = awsVaultPrefix()
+ *   return [`${prefix}<%= config.bin %> costs get my-service`]
+ * }
+ */
+export function awsVaultPrefix(config = null) {
+  // 1. Runtime env var — set by aws-vault exec in the subprocess environment
+  if (process.env.AWS_VAULT) return `aws-vault exec ${process.env.AWS_VAULT} -- `
+
+  // 2. Already-loaded config passed by the caller
+  if (config?.awsProfile) return `aws-vault exec ${config.awsProfile} -- `
+
+  // 3. Synchronous config read — fallback for static getters
+  const synced = loadConfigSync()
+  if (synced.awsProfile) return `aws-vault exec ${synced.awsProfile} -- `
+
+  return ''
+}
+
+/**
+ * Returns true when the current process already has AWS credentials in env.
+ * @returns {boolean}
+ */
+export function hasAwsCredentialEnv() {
+  return Boolean(
+    process.env.AWS_ACCESS_KEY_ID ||
+      process.env.AWS_SESSION_TOKEN,
+  )
+}
+
+/**
+ * Returns true when this process is already running inside aws-vault exec.
+ * @returns {boolean}
+ */
+export function isAwsVaultSession() {
+  return Boolean(process.env.AWS_VAULT)
+}
+
+/**
+ * Re-execute the current dvmi command under aws-vault and mirror stdio.
+ * Returns null when re-exec should not run.
+ *
+ * Guard conditions:
+ * - awsProfile must be configured
+ * - command must not already be inside aws-vault
+ * - process must not already have AWS credentials in env
+ * - re-exec must not have already happened in this process chain
+ *
+ * @param {{ awsProfile?: string } | null} [config]
+ * @returns {Promise<number | null>} child exit code or null when skipped
+ */
+export async function reexecCurrentCommandWithAwsVault(config = null) {
+  const profile = config?.awsProfile ?? loadConfigSync().awsProfile
+  if (!profile) return null
+  if (isAwsVaultSession()) return null
+  if (hasAwsCredentialEnv()) return null
+  if (process.env.DVMI_AWS_VAULT_REEXEC === '1') return null
+
+  try {
+    const child = await execa(
+      'aws-vault',
+      [
+        'exec',
+        profile,
+        '--',
+        process.execPath,
+        ...process.argv.slice(1),
+      ],
+      {
+        reject: false,
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          DVMI_AWS_VAULT_REEXEC: '1',
+        },
+      },
+    )
+
+    return child.exitCode ?? 1
+  } catch {
+    // aws-vault missing or failed to spawn; fallback to normal execution path
+    return null
+  }
+}
+
+/**
+ * Re-execute the current dvmi command under aws-vault using an explicit profile.
+ * This bypasses auto-detection guards and is intended for interactive recovery flows.
+ *
+ * @param {string} profile
+ * @param {Record<string, string>} [extraEnv]
+ * @returns {Promise<number | null>} child exit code or null when skipped/failed to spawn
+ */
+export async function reexecCurrentCommandWithAwsVaultProfile(profile, extraEnv = {}) {
+  if (!profile) return null
+
+  try {
+    const child = await execa(
+      'aws-vault',
+      [
+        'exec',
+        profile,
+        '--',
+        process.execPath,
+        ...process.argv.slice(1),
+      ],
+      {
+        reject: false,
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          DVMI_AWS_VAULT_REEXEC: '1',
+          ...extraEnv,
+        },
+      },
+    )
+
+    return child.exitCode ?? 1
+  } catch {
+    return null
+  }
+}