devvami 1.2.0 → 1.4.0

package/src/types.js

@@ -14,6 +14,70 @@
  * @property {string} [latestVersion] - Latest known CLI version
  * @property {'opencode'|'copilot'} [aiTool] - Preferred AI tool for running prompts
  * @property {string} [promptsDir] - Local directory for downloaded prompts (default: .prompts)
+ * @property {DotfilesConfig} [dotfiles] - Chezmoi dotfiles configuration
+ */
+
+/**
+ * @typedef {Object} DotfilesConfig
+ * @property {boolean} enabled - Whether chezmoi dotfiles management is active
+ * @property {string} [repo] - Remote dotfiles repository URL
+ * @property {string[]} [customSensitivePatterns] - User-added sensitive path patterns
+ */
+
+/**
+ * @typedef {Object} DotfileEntry
+ * @property {string} path - Target file path (e.g. "/home/user/.zshrc")
+ * @property {string} sourcePath - Source path in chezmoi state
+ * @property {boolean} encrypted - Whether the file is stored with encryption
+ * @property {'file'|'dir'|'symlink'} type - Entry type
+ */
+
+/**
+ * @typedef {Object} DotfileRecommendation
+ * @property {string} path - File path to recommend (e.g. "~/.zshrc")
+ * @property {'shell'|'git'|'editor'|'package'|'security'} category - Display grouping
+ * @property {Platform[]} platforms - Platforms this file applies to
+ * @property {boolean} autoEncrypt - Whether to encrypt by default
+ * @property {string} description - Human-readable description
+ */
+
+/**
+ * @typedef {Object} DotfilesSetupResult
+ * @property {Platform} platform - Detected platform
+ * @property {boolean} chezmoiInstalled - Whether chezmoi was found
+ * @property {boolean} encryptionConfigured - Whether age encryption is set up
+ * @property {string|null} sourceDir - Chezmoi source directory path
+ * @property {string|null} publicKey - Age public key
+ * @property {'success'|'skipped'|'failed'} status - Overall setup outcome
+ * @property {string} [message] - Human-readable outcome message
+ */
+
+/**
+ * @typedef {Object} DotfilesStatusResult
+ * @property {Platform} platform - Detected platform
+ * @property {boolean} enabled - Whether dotfiles management is active
+ * @property {boolean} chezmoiInstalled - Whether chezmoi binary exists
+ * @property {boolean} encryptionConfigured - Whether age encryption is set up
+ * @property {string|null} repo - Remote dotfiles repo URL
+ * @property {string|null} sourceDir - Chezmoi source directory
+ * @property {DotfileEntry[]} files - All managed files
+ * @property {{ total: number, encrypted: number, plaintext: number }} summary - File counts
+ */
+
+/**
+ * @typedef {Object} DotfilesAddResult
+ * @property {{ path: string, encrypted: boolean }[]} added - Successfully added files
+ * @property {{ path: string, reason: string }[]} skipped - Skipped files
+ * @property {{ path: string, reason: string }[]} rejected - Rejected files
+ */
+
+/**
+ * @typedef {Object} DotfilesSyncResult
+ * @property {'push'|'pull'|'init-remote'|'skipped'} action - Sync action performed
+ * @property {string|null} repo - Remote repository URL
+ * @property {'success'|'skipped'|'failed'} status - Outcome
+ * @property {string} [message] - Human-readable outcome
+ * @property {string[]} [conflicts] - Conflicting file paths
  */
 
 /**
@@ -189,10 +253,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
+  }
+}