devvami 1.1.2 → 1.3.0

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)
  */
 
 /**
@@ -260,3 +322,69 @@
  * @property {string} owner - GitHub owner (org or user)
  * @property {string} repo - Repository name
  */
+
+/**
+ * @typedef {Object} SecurityTool
+ * @property {string} id - Unique identifier (e.g., "aws-vault", "pass", "gpg", "gcm", "osxkeychain")
+ * @property {string} displayName - Human-readable name for UI output
+ * @property {'aws'|'git'|'dependency'} role - What the tool protects; 'dependency' = required by another tool
+ * @property {'not-installed'|'installed'|'misconfigured'|'skipped'|'n/a'} status - Status after check phase
+ * @property {Platform[]} platforms - Platforms where this tool applies
+ * @property {string|null} version - Detected version string, if available
+ * @property {string|null} hint - Actionable message when status is 'misconfigured' or 'not-installed'
+ */
+
+/**
+ * @typedef {Object} SetupStep
+ * @property {string} id - Unique step identifier (e.g., "install-aws-vault", "init-pass")
+ * @property {string} label - Human-readable description shown to the developer
+ * @property {string} toolId - The SecurityTool this step belongs to
+ * @property {'check'|'install'|'configure'|'verify'} type - Step category
+ * @property {() => Promise<StepResult>} run - Async function that executes the step
+ * @property {boolean} requiresConfirmation - True for 'install' and 'configure' steps
+ * @property {boolean} [skippable] - True if the developer can skip this step without breaking subsequent steps
+ * @property {boolean} [gpgInteractive] - True if the step spawns GPG interactively (requires stdio:inherit)
+ */
+
+/**
+ * @typedef {Object} StepResult
+ * @property {'success'|'skipped'|'failed'} status
+ * @property {string} [message] - Human-readable outcome message
+ * @property {string} [hint] - Actionable recovery suggestion shown only when status is 'failed'
+ * @property {string} [hintUrl] - Documentation URL to include with the hint
+ */
+
+/**
+ * @typedef {Object} SetupSession
+ * @property {Platform} platform - Detected platform for this run
+ * @property {'aws'|'git'|'both'} selection - What the developer chose to set up
+ * @property {SetupStep[]} steps - Ordered list of steps for this session
+ * @property {Map<string, StepResult>} results - Map of stepId → StepResult
+ * @property {'in-progress'|'completed'|'failed'|'cancelled'} overallStatus - Aggregate status
+ */
+
+/**
+ * @typedef {Object} GpgKey
+ * @property {string} id - Long key ID (16-character hex)
+ * @property {string} fingerprint - Full 40-character fingerprint
+ * @property {string} name - Associated name from the key's UID
+ * @property {string} email - Associated email from the key's UID
+ * @property {string|null} expiry - Expiry date as ISO8601 string, or null if no expiry
+ */
+
+/**
+ * @typedef {Object} SecurityToolStatus
+ * @property {string} id - Tool id
+ * @property {string} displayName - Human-readable name
+ * @property {'not-installed'|'installed'|'misconfigured'|'n/a'} status - Current status
+ * @property {string|null} version - Detected version, if any
+ * @property {string|null} hint - Recovery hint if misconfigured
+ */
+
+/**
+ * @typedef {Object} SecuritySetupJsonResult
+ * @property {Platform} platform - Detected platform
+ * @property {'aws'|'git'|'both'|null} selection - Selection made (null for --json health check)
+ * @property {SecurityToolStatus[]} tools - Status of each applicable tool
+ * @property {'success'|'partial'|'not-configured'} overallStatus - Aggregate status
+ */

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
+  }
+}

package/src/utils/welcome.js

@@ -0,0 +1,173 @@
+import chalk from 'chalk'
+import { printBanner } from './banner.js'
+import { isColorEnabled } from './gradient.js'
+import { typewriterLine } from './typewriter.js'
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const STAGGER = 150
+const delay = (ms) => new Promise((r) => setTimeout(r, ms))
+const out = (line) => process.stdout.write(line + '\n')
+const nl = () => process.stdout.write('\n')
+
+// ─── Color palette ────────────────────────────────────────────────────────────
+
+const p = isColorEnabled
+  ? {
+      sep:    (t) => chalk.hex('#4A9EFF').dim(t),
+      cyan:   (t) => chalk.hex('#00D4FF').bold(t),
+      green:  (t) => chalk.hex('#00FF88').bold(t),
+      pink:   (t) => chalk.hex('#FF3399').bold(t),
+      gold:   (t) => chalk.hex('#FFD700').bold(t),
+      orange: (t) => chalk.hex('#FF6B2B').bold(t),
+      blue:   (t) => chalk.hex('#4A9EFF')(t),
+      white:  (t) => chalk.white(t),
+      dim:    (t) => chalk.dim(t),
+    }
+  : Object.fromEntries(
+      ['sep', 'cyan', 'green', 'pink', 'gold', 'orange', 'blue', 'white', 'dim'].map((k) => [
+        k,
+        (t) => t,
+      ]),
+    )
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Build a ruler-style section header.
+ * Example: "  🔐  SUPPLY CHAIN SECURITY ──────────────────────────────"
+ * No right-side border: dashes trail right, no alignment required.
+ *
+ * @param {string} icon
+ * @param {string} label
+ * @param {(t: string) => string} colorFn
+ * @returns {string}
+ */
+function ruler(icon, label, colorFn) {
+  return colorFn(`  ${icon}  ${label} `) + p.sep('─'.repeat(40))
+}
+
+// ─── Welcome screen ───────────────────────────────────────────────────────────
+
+/**
+ * Print the full cyberpunk dvmi welcome screen.
+ * Shows the animated DVMI logo followed by a styled mission dashboard.
+ * Falls back to plain text in non-TTY / NO_COLOR / CI environments.
+ *
+ * @param {string} [version=''] - CLI version string (e.g. '2.1.0')
+ * @returns {Promise<void>}
+ */
+export async function printWelcomeScreen(version = '') {
+  // ── 1. Animated DVMI logo ──────────────────────────────────────────────────
+  await printBanner()
+
+  // ── 2. Badge line (typewriter with brand gradient) ─────────────────────────
+  const versionTag = version ? `v${version}  ·  ` : ''
+  await typewriterLine(`  ◆ Developer Mission Interface  ·  ${versionTag}Node >= 24`)
+
+  // ── 3. Connection established ──────────────────────────────────────────────
+  await delay(STAGGER)
+  nl()
+  out(p.sep('  ' + '─'.repeat(72)))
+  nl()
+  out(p.cyan('  LINK ESTABLISHED'))
+  nl()
+  out(p.white('  dvmi consolidates the operational surface of modern software delivery into'))
+  out(p.white('  one deterministic CLI experience. Instead of context switching across browser'))
+  out(p.white('  tabs, dashboards, and disconnected tools, you run critical workflows from a'))
+  out(p.white('  single terminal interface: consistent output, predictable behavior, full control.'))
+
+  // ── 4. Mission profile ─────────────────────────────────────────────────────
+  await delay(STAGGER)
+  nl()
+  out(ruler('⚙️ ', 'MISSION PROFILE :: WHAT THIS CLI DOES', p.cyan))
+  nl()
+  const mission = [
+    'discover and manage repositories across your GitHub organization',
+    'handle pull requests with faster review and decision flow',
+    'monitor CI/CD pipelines, inspect failures, rerun with intent',
+    'query and read technical documentation without leaving the shell',
+    'track execution priorities through task-oriented commands',
+    'inspect cloud costs early, before budget drift becomes an incident',
+  ]
+  for (const line of mission) {
+    out(p.dim('  -  ') + p.white(line))
+  }
+
+  // ── 5. Supply chain security ───────────────────────────────────────────────
+  await delay(STAGGER)
+  nl()
+  out(ruler('🔐', "SUPPLY CHAIN SECURITY :: VERIFY, DON'T GUESS", p.green))
+  nl()
+  out(p.dim('  dvmi takes a security-first but pragmatic approach to software delivery:'))
+  nl()
+  const security = [
+    'artifact integrity and provenance-aware delivery workflow',
+    'dependency visibility with an SBOM mindset (SPDX / CycloneDX)',
+    'continuous hygiene on dependency risk and secret exposure',
+    'credential management via OS-native secure storage (keychain)',
+    'less improvised shell procedures, more repeatable safe operations',
+  ]
+  for (const line of security) {
+    out(p.green('  ▸  ') + p.white(line))
+  }
+  nl()
+  out(p.dim('  Objective: reduce the risk surface without slowing down delivery.'))
+
+  // ── 6. DevEx high-velocity ─────────────────────────────────────────────────
+  await delay(STAGGER)
+  nl()
+  out(ruler('⚡', 'DEVEX HIGH-VELOCITY :: STAY IN FLOW', p.pink))
+  nl()
+  out(p.dim('  dvmi is designed to lower cognitive cost and keep you in flow:'))
+  nl()
+  const devex = [
+    'less context switching between tools and dashboards',
+    'less time spent hunting down "where did this break"',
+    'faster "what is blocked / what is next" decision loops',
+    'scriptable, composable output for automation and team workflows',
+  ]
+  for (const line of devex) {
+    out(p.pink('  ▸  ') + p.white(line))
+  }
+  nl()
+  out(p.dim('  No noise added. Operational signal only.'))
+
+  // ── 7. Delivery reliability ────────────────────────────────────────────────
+  await delay(STAGGER)
+  nl()
+  out(ruler('📡', 'DELIVERY RELIABILITY :: SHIP WITH CONTROL', p.orange))
+  nl()
+  out(p.white('  From PR readiness to pipeline health to release confidence,'))
+  out(p.white('  dvmi moves teams from reactive debugging to proactive control.'))
+  nl()
+  out(p.white('  Reliability is treated as a habit, not a phase.'))
+
+  // ── 8. Boot sequence ───────────────────────────────────────────────────────
+  await delay(STAGGER)
+  nl()
+  out(ruler('🚀', 'BOOT SEQUENCE', p.gold))
+  nl()
+
+  /** @type {Array<[string, string]>} */
+  const commands = [
+    ['dvmi init',            'configure your workspace'],
+    ['dvmi auth login',      'connect GitHub & ClickUp'],
+    ['dvmi pr status',       'open pull requests'],
+    ['dvmi pipeline status', 'CI/CD health check'],
+    ['dvmi tasks today',     'focus mode: what to ship today'],
+    ['dvmi costs get',       'AWS bill reality check'],
+    ['dvmi doctor',          'diagnose config issues'],
+  ]
+  for (const [cmd, comment] of commands) {
+    out('  ' + p.blue('$ ' + cmd.padEnd(24)) + p.dim('# ' + comment))
+  }
+
+  // ── 9. Closing ─────────────────────────────────────────────────────────────
+  await delay(STAGGER)
+  nl()
+  out(p.sep('  ' + '─'.repeat(72)))
+  nl()
+  out(p.dim('  DVMI PROTOCOL: ') + p.cyan('Ship fast. Verify everything.'))
+  nl()
+}