devvami 1.5.0 → 1.5.1

package/src/types.js

@@ -337,11 +337,11 @@
 // ──────────────────────────────────────────────────────────────────────────────
 
 /**
- * @typedef {'mcp'|'command'|'skill'|'agent'} CategoryType
+ * @typedef {'mcp'|'command'|'rule'|'skill'|'agent'} CategoryType
  */
 
 /**
- * @typedef {'vscode-copilot'|'claude-code'|'opencode'|'gemini-cli'|'copilot-cli'} EnvironmentId
+ * @typedef {'vscode-copilot'|'claude-code'|'claude-desktop'|'opencode'|'gemini-cli'|'copilot-cli'|'cursor'|'windsurf'|'continue-dev'|'zed'|'amazon-q'} EnvironmentId
  */
 
 /**
@@ -359,6 +359,12 @@
  * @property {string} [description] - Short description of the command
  */
 
+/**
+ * @typedef {Object} RuleParams
+ * @property {string} content - Rules/instructions content (multi-line Markdown)
+ * @property {string} [description] - Short description of the rule
+ */
+
 /**
  * @typedef {Object} SkillParams
  * @property {string} content - Skill definition content (multi-line)
@@ -378,7 +384,7 @@
  * @property {CategoryType} type - Category type
  * @property {boolean} active - true = deployed to environments, false = removed but kept in store
  * @property {EnvironmentId[]} environments - Target environments for deployment
- * @property {MCPParams|CommandParams|SkillParams|AgentParams} params - Type-specific parameters
+ * @property {MCPParams|CommandParams|RuleParams|SkillParams|AgentParams} params - Type-specific parameters
  * @property {string} createdAt - ISO 8601 timestamp
  * @property {string} updatedAt - ISO 8601 timestamp
  */
@@ -400,10 +406,33 @@
  * @typedef {Object} CategoryCounts
  * @property {number} mcp
  * @property {number} command
+ * @property {number} rule
  * @property {number} skill
  * @property {number} agent
  */
 
+/**
+ * @typedef {Object} NativeEntry
+ * Runtime only — not persisted. Represents an item found in an environment's config
+ * file that is NOT managed by dvmi.
+ * @property {string} name - Entry name (extracted from config key or filename)
+ * @property {CategoryType} type - Category type
+ * @property {EnvironmentId} environmentId - Source environment
+ * @property {'project'|'global'} level - Whether from project-level or global-level config
+ * @property {string} sourcePath - Absolute path to the source config file
+ * @property {object} params - Normalized parameters (same structure as managed entry params)
+ */
+
+/**
+ * @typedef {Object} DriftInfo
+ * Runtime only — not persisted. Describes a managed entry whose deployed state
+ * diverges from dvmi's stored expected state.
+ * @property {string} entryId - ID of the managed CategoryEntry that drifted
+ * @property {EnvironmentId} environmentId - Environment where drift was detected
+ * @property {object} expected - What dvmi expects (from store)
+ * @property {object} actual - What was found in the file
+ */
+
 /**
  * @typedef {Object} DetectedEnvironment
  * @property {EnvironmentId} id - Environment identifier
@@ -414,6 +443,9 @@
  * @property {string[]} unreadable - Paths that exist but failed to parse
  * @property {CategoryType[]} supportedCategories - Category types this environment supports
  * @property {CategoryCounts} counts - Per-category item counts from dvmi-managed entries
+ * @property {CategoryCounts} nativeCounts - Per-category native item counts (items in config files)
+ * @property {NativeEntry[]} nativeEntries - All native entries found for this environment
+ * @property {DriftInfo[]} driftedEntries - Managed entries that have drifted from expected state
  * @property {'project'|'global'|'both'} scope - Where detection occurred
  */
 

package/src/utils/tui/form.js

@@ -20,6 +20,7 @@ import chalk from 'chalk'
  * @property {boolean} required
  * @property {string} placeholder
  * @property {string} [key] - Optional override key for extractValues output
+ * @property {boolean} [hidden] - When true, field is skipped in rendering, navigation, validation, and extraction
  */
 
 /**
@@ -30,6 +31,7 @@ import chalk from 'chalk'
  * @property {number} selectedIndex
  * @property {boolean} required
  * @property {string} [key]
+ * @property {boolean} [hidden]
  */
 
 /**
@@ -45,6 +47,7 @@ import chalk from 'chalk'
  * @property {number} focusedOptionIndex
  * @property {boolean} required
  * @property {string} [key]
+ * @property {boolean} [hidden]
  */
 
 /**
@@ -56,6 +59,7 @@ import chalk from 'chalk'
  * @property {number} cursorCol
  * @property {boolean} required
  * @property {string} [key]
+ * @property {boolean} [hidden]
  */
 
 /**
@@ -69,6 +73,7 @@ import chalk from 'chalk'
  * @property {string} title
  * @property {'editing'|'submitted'|'cancelled'} status
  * @property {string|null} errorMessage
+ * @property {((state: FormState) => string|null)|null} [customValidator] - Optional transport-specific validator
  */
 
 /**
@@ -97,6 +102,25 @@ function fieldKey(field) {
   return field.label.toLowerCase().replace(/\s+/g, '_')
 }
 
+/**
+ * Find the next visible (non-hidden) field index in a given direction.
+ * Wraps around the array. Returns current index if all fields are hidden.
+ * @param {Field[]} fields
+ * @param {number} current - Current focused index
+ * @param {1|-1} direction - 1 for forward, -1 for backward
+ * @returns {number}
+ */
+function nextVisibleIndex(fields, current, direction) {
+  const len = fields.length
+  let next = (current + direction + len) % len
+  let checked = 0
+  while (fields[next]?.hidden && checked < len) {
+    next = (next + direction + len) % len
+    checked++
+  }
+  return next
+}
+
 /**
  * Render the text cursor inside a string value at the given position.
  * Inserts a `|` character at the cursor index.
@@ -263,6 +287,7 @@ export function buildFormScreen(formState, viewportHeight, termCols) {
 
   for (let i = 0; i < formState.fields.length; i++) {
     const field = formState.fields[i]
+    if (field.hidden) continue
     const isFocused = i === formState.focusedFieldIndex
 
     // Header line
@@ -311,6 +336,7 @@ export function extractValues(formState) {
   const result = {}
 
   for (const field of formState.fields) {
+    if (field.hidden) continue
     const key = fieldKey(field)
 
     if (field.type === 'text') {
@@ -339,6 +365,7 @@ export function extractValues(formState) {
  */
 function validateForm(formState) {
   for (const field of formState.fields) {
+    if (field.hidden) continue
     if (!field.required) continue
 
     if (field.type === 'text' && field.value.trim() === '') {
@@ -636,20 +663,20 @@ export function handleFormKeypress(formState, key) {
     return attemptSubmit(formState)
   }
 
-  // ── Tab: next field ───────────────────────────────────────────────────────
+  // ── Tab: next field (skip hidden) ──────────────────────────────────────────
   if (key.name === 'tab' && !key.shift) {
     return {
       ...formState,
-      focusedFieldIndex: (focusedFieldIndex + 1) % fields.length,
+      focusedFieldIndex: nextVisibleIndex(fields, focusedFieldIndex, 1),
       errorMessage: null,
     }
   }
 
-  // ── Shift+Tab: previous field ─────────────────────────────────────────────
+  // ── Shift+Tab: previous field (skip hidden) ──────────────────────────────
   if (key.name === 'tab' && key.shift) {
     return {
       ...formState,
-      focusedFieldIndex: (focusedFieldIndex - 1 + fields.length) % fields.length,
+      focusedFieldIndex: nextVisibleIndex(fields, focusedFieldIndex, -1),
       errorMessage: null,
     }
   }
@@ -680,9 +707,15 @@ export function handleFormKeypress(formState, key) {
   if (focusedField.type === 'selector') {
     const updated = handleSelectorFieldKey(focusedField, key)
     if (updated === focusedField) return formState
+    let newFields = replaceAt(fields, focusedFieldIndex, updated)
+    // Dynamic visibility: when transport selector changes, toggle field visibility
+    if (fieldKey(focusedField) === 'transport') {
+      const newTransport = updated.options[updated.selectedIndex]
+      newFields = updateMCPFieldVisibility(newFields, newTransport)
+    }
     return {
       ...formState,
-      fields: replaceAt(fields, focusedFieldIndex, updated),
+      fields: newFields,
     }
   }
 
@@ -691,7 +724,7 @@ export function handleFormKeypress(formState, key) {
     if ('advanceField' in result) {
       return {
         ...formState,
-        focusedFieldIndex: Math.min(focusedFieldIndex + 1, lastFieldIndex),
+        focusedFieldIndex: nextVisibleIndex(fields, focusedFieldIndex, 1),
       }
     }
     if (result === focusedField) return formState
@@ -704,11 +737,10 @@ export function handleFormKeypress(formState, key) {
   if (focusedField.type === 'editor') {
     const result = handleEditorFieldKey(focusedField, key)
     if ('advanceField' in result) {
-      // Esc in editor cancels the form only if we treat it as a field-level escape.
-      // Per spec, Esc in editor moves to next field.
+      // Esc in editor moves to next field (skip hidden)
       return {
         ...formState,
-        focusedFieldIndex: Math.min(focusedFieldIndex + 1, lastFieldIndex),
+        focusedFieldIndex: nextVisibleIndex(fields, focusedFieldIndex, 1),
       }
     }
     if (result === focusedField) return formState
@@ -735,6 +767,13 @@ function attemptSubmit(formState) {
       errorMessage: `"${invalidLabel}" is required.`,
     }
   }
+  // Run custom validator (e.g. MCP transport-specific checks)
+  if (formState.customValidator) {
+    const customError = formState.customValidator(formState)
+    if (customError !== null) {
+      return {...formState, errorMessage: customError}
+    }
+  }
   return {
     submitted: /** @type {true} */ (true),
     values: extractValues(formState),
@@ -760,8 +799,11 @@ function replaceAt(arr, index, value) {
 /**
  * Return form fields for creating or editing an MCP entry.
  *
- * Fields: name (text), environments (multiselect), transport (selector), command (text),
- * args (text), url (text), description (text, optional).
+ * Fields: name (text), environments (multiselect), transport (selector),
+ * command (text, stdio only), args (editor, stdio only), url (text, remote only),
+ * env vars (editor), description (text, optional).
+ *
+ * Fields are dynamically shown/hidden based on the selected transport.
  *
  * @param {import('../../types.js').CategoryEntry|null} [entry] - Existing entry to pre-fill from, or null to create
  * @param {import('../../types.js').DetectedEnvironment[]} [compatibleEnvs] - Environments compatible with this category type
@@ -773,8 +815,10 @@ export function getMCPFormFields(entry = null, compatibleEnvs = []) {
 
   const transportOptions = ['stdio', 'sse', 'streamable-http']
   const transportIndex = p ? Math.max(0, transportOptions.indexOf(p.transport)) : 0
+  const transport = transportOptions[transportIndex]
 
-  return [
+  /** @type {Field[]} */
+  const fields = [
     /** @type {TextField} */ ({
       type: 'text',
       label: 'Name',
@@ -810,14 +854,14 @@ export function getMCPFormFields(entry = null, compatibleEnvs = []) {
       required: false,
       placeholder: 'npx my-mcp-server',
     }),
-    /** @type {TextField} */ ({
-      type: 'text',
+    /** @type {MiniEditorField} */ ({
+      type: 'editor',
       label: 'Args',
       key: 'args',
-      value: p?.args ? p.args.join(' ') : '',
-      cursor: p?.args ? p.args.join(' ').length : 0,
+      lines: p?.args?.length > 0 ? [...p.args] : [''],
+      cursorLine: 0,
+      cursorCol: 0,
       required: false,
-      placeholder: '--port 3000 --verbose',
     }),
     /** @type {TextField} */ ({
       type: 'text',
@@ -828,6 +872,15 @@ export function getMCPFormFields(entry = null, compatibleEnvs = []) {
       required: false,
       placeholder: 'https://mcp.example.com',
     }),
+    /** @type {MiniEditorField} */ ({
+      type: 'editor',
+      label: 'Env Vars',
+      key: 'env',
+      lines: p?.env ? Object.entries(p.env).map(([k, v]) => `${k}=${v}`) : [''],
+      cursorLine: 0,
+      cursorCol: 0,
+      required: false,
+    }),
     /** @type {TextField} */ ({
       type: 'text',
       label: 'Description',
@@ -838,6 +891,67 @@ export function getMCPFormFields(entry = null, compatibleEnvs = []) {
       placeholder: 'Optional description',
     }),
   ]
+
+  return updateMCPFieldVisibility(fields, transport)
+}
+
+/**
+ * Toggle visibility of MCP-specific fields based on the selected transport.
+ * - stdio: show Command + Args, hide URL
+ * - sse/streamable-http: show URL, hide Command + Args
+ * - Env Vars and Description are always visible
+ *
+ * @param {Field[]} fields
+ * @param {string} transport
+ * @returns {Field[]}
+ */
+export function updateMCPFieldVisibility(fields, transport) {
+  const isStdio = transport === 'stdio'
+  return fields.map((f) => {
+    const key = f.key || f.label.toLowerCase().replace(/\s+/g, '_')
+    if (key === 'command' || key === 'args') {
+      return {...f, hidden: !isStdio}
+    }
+    if (key === 'url') {
+      return {...f, hidden: isStdio}
+    }
+    return f
+  })
+}
+
+/**
+ * MCP-specific form validator. Checks that:
+ * - stdio transport has a non-empty command
+ * - sse/streamable-http transport has a non-empty URL
+ * - Env var lines (if any) follow KEY=VALUE format
+ *
+ * @param {FormState} formState
+ * @returns {string|null} Error message or null if valid
+ */
+export function validateMCPForm(formState) {
+  const values = extractValues(formState)
+  const transport = values.transport
+
+  if (transport === 'stdio') {
+    if (!values.command || /** @type {string} */ (values.command).trim() === '') {
+      return 'Command is required for stdio transport'
+    }
+  } else if (transport === 'sse' || transport === 'streamable-http') {
+    if (!values.url || /** @type {string} */ (values.url).trim() === '') {
+      return 'URL is required for sse/streamable-http transport'
+    }
+  }
+
+  if (values.env && typeof values.env === 'string') {
+    const lines = /** @type {string} */ (values.env).split('\n').filter((l) => l.trim() !== '')
+    for (const line of lines) {
+      if (!line.includes('=')) {
+        return `Invalid env var format: "${line}" (expected KEY=VALUE)`
+      }
+    }
+  }
+
+  return null
 }
 
 /**
@@ -950,6 +1064,70 @@ export function getSkillFormFields(entry = null, compatibleEnvs = []) {
   ]
 }
 
+/**
+ * Return form fields for creating or editing an Agent entry.
+ *
+ * Fields: name (text), environments (multiselect), description (text, optional), instructions (editor).
+ *
+ * @param {import('../../types.js').CategoryEntry|null} [entry] - Existing entry to pre-fill from, or null to create
+ * @param {import('../../types.js').DetectedEnvironment[]} [compatibleEnvs] - Environments compatible with this category type
+ * @returns {Field[]}
+ */
+/**
+ * Return form fields for creating or editing a Rule entry.
+ *
+ * Fields: name (text), environments (multiselect), description (text, optional), content (editor).
+ *
+ * @param {import('../../types.js').CategoryEntry|null} [entry] - Existing entry to pre-fill from, or null to create
+ * @param {import('../../types.js').DetectedEnvironment[]} [compatibleEnvs] - Environments compatible with this category type
+ * @returns {Field[]}
+ */
+export function getRuleFormFields(entry = null, compatibleEnvs = []) {
+  /** @type {import('../../types.js').RuleParams|null} */
+  const p = entry ? /** @type {import('../../types.js').RuleParams} */ (entry.params) : null
+  const contentStr = p?.content ?? ''
+  const contentLines = contentStr.length > 0 ? contentStr.split('\n') : ['']
+
+  return [
+    /** @type {TextField} */ ({
+      type: 'text',
+      label: 'Name',
+      key: 'name',
+      value: entry ? entry.name : '',
+      cursor: entry ? entry.name.length : 0,
+      required: true,
+      placeholder: 'my-rule',
+    }),
+    /** @type {MultiSelectField} */ ({
+      type: 'multiselect',
+      label: 'Environments',
+      key: 'environments',
+      options: compatibleEnvs.map((env) => ({id: env.id, label: env.name})),
+      selected: new Set(entry ? entry.environments : []),
+      focusedOptionIndex: 0,
+      required: true,
+    }),
+    /** @type {TextField} */ ({
+      type: 'text',
+      label: 'Description',
+      key: 'description',
+      value: p?.description ?? '',
+      cursor: (p?.description ?? '').length,
+      required: false,
+      placeholder: 'Optional description',
+    }),
+    /** @type {MiniEditorField} */ ({
+      type: 'editor',
+      label: 'Content',
+      key: 'content',
+      lines: contentLines,
+      cursorLine: 0,
+      cursorCol: 0,
+      required: true,
+    }),
+  ]
+}
+
 /**
  * Return form fields for creating or editing an Agent entry.
  *