agent-facets 0.1.2 → 0.2.1

package/src/run.ts

@@ -1,10 +1,10 @@
 import { parse } from '@bomb.sh/args'
-import { commands } from './commands.ts'
+import type { Command } from './commands.ts'
 import { printCommandHelp, printGlobalHelp } from './help.ts'
 import { findClosestCommand } from './suggest.ts'
 import { version } from './version.ts'
 
-export async function run(argv: string[]): Promise<number> {
+export async function run(argv: string[], commands: Record<string, Command>): Promise<number> {
   const args = parse(argv, {
     boolean: ['help', 'version'],
   })
@@ -18,7 +18,7 @@ export async function run(argv: string[]): Promise<number> {
 
   // No command given — show global help
   if (!commandName) {
-    printGlobalHelp()
+    printGlobalHelp(commands)
     return 0
   }
 
@@ -29,7 +29,7 @@ export async function run(argv: string[]): Promise<number> {
     if (subCommand) {
       printCommandHelp(subCommand)
     } else {
-      printGlobalHelp()
+      printGlobalHelp(commands)
     }
     return 0
   }
@@ -51,5 +51,32 @@ export async function run(argv: string[]): Promise<number> {
     return 0
   }
 
-  return command.run(argv.slice(1))
+  // Build per-command flag parsing config
+  const booleanFlags: string[] = []
+  const stringFlags: string[] = []
+
+  if (command.flags) {
+    for (const [name, def] of Object.entries(command.flags)) {
+      if (def.type === 'boolean') booleanFlags.push(name)
+      else if (def.type === 'string') stringFlags.push(name)
+    }
+  }
+
+  // Parse with per-command config
+  const parsed = parse(argv.slice(1), {
+    boolean: booleanFlags,
+    string: stringFlags,
+  })
+
+  // Build positional args and flags
+  const positionalArgs = parsed._.map(String)
+  const flags: Record<string, unknown> = {}
+
+  for (const name of [...booleanFlags, ...stringFlags]) {
+    if (parsed[name] !== undefined) {
+      flags[name] = parsed[name]
+    }
+  }
+
+  return command.run(positionalArgs, flags)
 }

package/src/tui/components/asset-description.tsx

@@ -0,0 +1,17 @@
+import { Box, Text } from 'ink'
+
+export function truncateDescription(text: string, maxLen = 50): string {
+  const lines = text.split(/\r?\n/)
+  const firstLine = lines[0] ?? text
+  const hasMore = lines.length > 1
+  if (firstLine.length <= maxLen) return hasMore ? `${firstLine}...` : firstLine
+  return `${firstLine.slice(0, maxLen)}...`
+}
+
+export function AssetDescription({ description }: { description: string }) {
+  return (
+    <Box marginLeft={4}>
+      <Text dimColor>{truncateDescription(description)}</Text>
+    </Box>
+  )
+}

package/src/tui/components/asset-field-picker.tsx

@@ -0,0 +1,78 @@
+import { Box, Text, useInput } from 'ink'
+import { useEffect, useState } from 'react'
+import { useFocusMode } from '../context/focus-mode-context.ts'
+import { THEME } from '../theme.ts'
+
+export type AssetField = 'name' | 'description'
+
+export function AssetFieldPicker({
+  name,
+  description,
+  initialField,
+  onChoose,
+  onCancel,
+}: {
+  name: string
+  description: string
+  initialField?: AssetField
+  onChoose: (field: AssetField) => void
+  onCancel: () => void
+}) {
+  const { setMode } = useFocusMode()
+  const [field, setField] = useState<AssetField>(initialField ?? 'name')
+
+  useEffect(() => {
+    setMode('field-revision')
+    return () => setMode('form-navigation')
+  }, [setMode])
+
+  useInput((_input, key) => {
+    if (key.upArrow) setField('name')
+    if (key.downArrow) setField('description')
+    if (key.escape) onCancel()
+    if (key.return) onChoose(field)
+  })
+
+  return (
+    <Box flexDirection="column">
+      <Box gap={1} marginLeft={2}>
+        {field === 'name' ? (
+          <>
+            <Text color={THEME.primary} bold>
+              ▸
+            </Text>
+            <Text color={THEME.primary}>{name}</Text>
+            <Text color={THEME.hint}>
+              <Text color={THEME.keyword}>↑↓</Text> select · <Text color={THEME.keyword}>Enter</Text> edit ·{' '}
+              <Text color={THEME.keyword}>Esc</Text> back
+            </Text>
+          </>
+        ) : (
+          <>
+            <Text color={THEME.success}>•</Text>
+            <Text>{name}</Text>
+          </>
+        )}
+      </Box>
+      <Box gap={1} marginLeft={2}>
+        {field === 'description' ? (
+          <>
+            <Text color={THEME.primary} bold>
+              ▸
+            </Text>
+            <Text color={THEME.primary}>{description}</Text>
+            <Text color={THEME.hint}>
+              <Text color={THEME.keyword}>↑↓</Text> select · <Text color={THEME.keyword}>Enter</Text> edit ·{' '}
+              <Text color={THEME.keyword}>Esc</Text> back
+            </Text>
+          </>
+        ) : (
+          <>
+            <Text> </Text>
+            <Text dimColor>{description}</Text>
+          </>
+        )}
+      </Box>
+    </Box>
+  )
+}

package/src/tui/components/asset-inline-input.tsx

@@ -12,6 +12,7 @@ export function AssetInlineInput({
   onError,
   onSubmit,
   onCancel,
+  onDownArrow,
 }: {
   id: string
   value: string
@@ -23,6 +24,7 @@ export function AssetInlineInput({
   onError: (error: string) => void
   onSubmit: (name: string) => void
   onCancel: () => void
+  onDownArrow?: () => void
 }) {
   useInput(
     (_input, key) => {
@@ -47,6 +49,10 @@ export function AssetInlineInput({
         onCancel()
         return
       }
+      if (key.downArrow && onDownArrow) {
+        onDownArrow()
+        return
+      }
       if (key.tab && !value && placeholder) {
         onChange(placeholder)
         return
@@ -63,7 +69,13 @@ export function AssetInlineInput({
         <Text color={THEME.warning}>· {error}</Text>
       ) : value ? (
         <Text color={THEME.hint}>
-          · <Text color={THEME.keyword}>Enter</Text> to save · <Text color={THEME.keyword}>Escape</Text> to revert
+          · <Text color={THEME.keyword}>Enter</Text> save ·{' '}
+          {onDownArrow && (
+            <>
+              <Text color={THEME.keyword}>↓</Text> description ·{' '}
+            </>
+          )}
+          <Text color={THEME.keyword}>Esc</Text> revert
         </Text>
       ) : placeholder ? (
         <Text color={THEME.hint}>

package/src/tui/components/asset-item.tsx

@@ -15,12 +15,8 @@ export function AssetItem({
 }) {
   useInput(
     (_input, key) => {
-      if (key.return) {
-        onEdit()
-      }
-      if (key.delete || key.backspace) {
-        onRemove()
-      }
+      if (key.return) onEdit()
+      if (key.delete || key.backspace) onRemove()
     },
     { isActive: isFocused },
   )
@@ -34,7 +30,7 @@ export function AssetItem({
           </Text>
           <Text color={THEME.primary}>{name}</Text>
           <Text color={THEME.hint}>
-            <Text color={THEME.keyword}>Enter</Text> to edit · <Text color={THEME.keyword}>Delete</Text> to remove
+            <Text color={THEME.keyword}>Enter</Text> edit name · <Text color={THEME.keyword}>Del</Text> remove
           </Text>
         </>
       ) : (

package/src/tui/components/asset-section.tsx

@@ -4,6 +4,9 @@ import { useFocusMode } from '../context/focus-mode-context.ts'
 import { useFocusOrder } from '../context/focus-order-context.ts'
 import type { AssetSectionKey } from '../context/form-state-context.ts'
 import { useFormState } from '../context/form-state-context.ts'
+import { AssetDescription, truncateDescription } from './asset-description.tsx'
+import type { AssetField } from './asset-field-picker.tsx'
+import { AssetFieldPicker } from './asset-field-picker.tsx'
 import { AssetInlineInput } from './asset-inline-input.tsx'
 import { AssetItem } from './asset-item.tsx'
 import { Button } from './button.tsx'
@@ -14,19 +17,22 @@ export function AssetSection({
   defaultName,
   dimmed,
   validate,
+  onEditDescription,
 }: {
   section: AssetSectionKey
   label: string
   defaultName?: string
   dimmed?: boolean
   validate?: (value: string) => string | undefined
+  onEditDescription?: (section: AssetSectionKey, name: string) => void
 }) {
   const { form, addAsset, removeAsset, renameAsset, setAssetAdding, setAssetEditing } = useFormState()
-  const { items, editing, adding } = form.assets[section]
+  const { items, descriptions, editing, adding } = form.assets[section]
   const { setMode } = useFocusMode()
   const { focusedId, focus } = useFocusOrder()
   const [inputValue, setInputValue] = useState('')
   const [error, setError] = useState('')
+  const [selectedItem, setSelectedItem] = useState<string | null>(null)
 
   const startAdding = () => {
     setAssetAdding(section, true)
@@ -42,13 +48,24 @@ export function AssetSection({
     setMode('field-revision')
   }
 
-  const closeInput = () => {
+  const closeInput = (focusTarget?: string | false) => {
     setAssetAdding(section, false)
     setAssetEditing(section, undefined)
     setInputValue('')
     setError('')
-    setMode('form-navigation')
-    focus(`add-${section}`)
+    if (focusTarget !== false) {
+      setMode('form-navigation')
+      focus(focusTarget ?? `add-${section}`)
+    }
+  }
+
+  const handleFieldChoice = (name: string, field: AssetField) => {
+    setSelectedItem(null)
+    if (field === 'name') {
+      startEditing(name)
+    } else {
+      onEditDescription?.(section, name)
+    }
   }
 
   const handleRemove = (name: string) => {
@@ -76,37 +93,66 @@ export function AssetSection({
       {items.map((item, i) => {
         const itemId = `item-${section}-${i}`
         const isFocusedItem = focusedId === itemId
+        const description = descriptions[item] ?? `A ${item} ${section}`
 
-        if (editing === item) {
+        // Field picker (entered via ↓ during name editing)
+        if (selectedItem === item) {
           return (
-            <AssetInlineInput
+            <AssetFieldPicker
               key={itemId}
-              id={itemId}
-              value={inputValue}
-              placeholder={item}
-              error={error}
-              isFocused={isFocusedItem}
-              onChange={setInputValue}
-              validate={validate}
-              onError={setError}
-              onSubmit={(newName) => {
-                renameAsset(section, item, newName)
-                closeInput()
+              name={item}
+              description={truncateDescription(description)}
+              initialField="description"
+              onChoose={(field) => handleFieldChoice(item, field)}
+              onCancel={() => {
+                setSelectedItem(null)
+                setMode('form-navigation')
+                focus(itemId)
               }}
-              onCancel={closeInput}
             />
           )
         }
 
+        // Inline name editing
+        if (editing === item) {
+          return (
+            <Box key={itemId} flexDirection="column">
+              <AssetInlineInput
+                id={itemId}
+                value={inputValue}
+                placeholder={item}
+                error={error}
+                isFocused={isFocusedItem}
+                onChange={setInputValue}
+                validate={validate}
+                onError={setError}
+                onSubmit={(newName) => {
+                  renameAsset(section, item, newName)
+                  closeInput(itemId)
+                }}
+                onCancel={() => closeInput(itemId)}
+                onDownArrow={() => {
+                  closeInput(false)
+                  setSelectedItem(item)
+                }}
+              />
+              <AssetDescription description={description} />
+            </Box>
+          )
+        }
+
+        // Normal display (level 1)
         return (
-          <AssetItem
-            key={itemId}
-            id={itemId}
-            name={item}
-            isFocused={isFocusedItem}
-            onEdit={() => startEditing(item)}
-            onRemove={() => handleRemove(item)}
-          />
+          <Box key={itemId} flexDirection="column">
+            <AssetItem
+              id={itemId}
+              name={item}
+              isFocused={isFocusedItem}
+              onEdit={() => startEditing(item)}
+              onRemove={() => handleRemove(item)}
+            />
+            <AssetDescription description={description} />
+          </Box>
         )
       })}
 

package/src/tui/components/reconciliation-item.tsx

@@ -0,0 +1,129 @@
+import { Box, Text, useInput } from 'ink'
+import Gradient from 'ink-gradient'
+import { useEffect, useState } from 'react'
+import { useFocusOrder } from '../context/focus-order-context.ts'
+import { GRADIENT_STOPS, getAnimatedGradient } from '../gradient.ts'
+import { THEME } from '../theme.ts'
+
+const ANIMATION_INTERVAL_MS = 75
+
+export interface ReconciliationOption {
+  label: string
+}
+
+export function ReconciliationItemRow({
+  id,
+  description,
+  detail,
+  options,
+  selectedIndex,
+  onSelect,
+}: {
+  id: string
+  /** Primary text for this item (e.g., file path or asset name) */
+  description: string
+  /** Optional secondary detail line below the description */
+  detail?: string
+  /** The two action options */
+  options: [ReconciliationOption, ReconciliationOption]
+  /** Index of currently selected option, or null if unresolved */
+  selectedIndex: number | null
+  /** Called when the user locks in an option */
+  onSelect: (index: number) => void
+}) {
+  const { focusedId } = useFocusOrder()
+  const isFocused = focusedId === id
+
+  // Which option is highlighted (cursor position)
+  const [highlightedIndex, setHighlightedIndex] = useState(selectedIndex ?? 0)
+  const [offset, setOffset] = useState(0)
+
+  // Animate gradient when focused
+  useEffect(() => {
+    if (!isFocused) return
+    const interval = setInterval(() => {
+      setOffset((prev) => (prev + 1) % GRADIENT_STOPS.length)
+    }, ANIMATION_INTERVAL_MS)
+    return () => clearInterval(interval)
+  }, [isFocused])
+
+  useInput(
+    (_input, key) => {
+      if (key.leftArrow) setHighlightedIndex(0)
+      if (key.rightArrow) setHighlightedIndex(1)
+      if (key.return) onSelect(highlightedIndex)
+    },
+    { isActive: isFocused },
+  )
+
+  const animatedColors = getAnimatedGradient(offset)
+
+  return (
+    <Box flexDirection="column">
+      <Box gap={2}>
+        <Box gap={1}>
+          {isFocused ? (
+            <Text color={THEME.primary} bold>
+              ▸
+            </Text>
+          ) : (
+            <Text> </Text>
+          )}
+          <Text color={isFocused ? THEME.primary : undefined}>{description}</Text>
+        </Box>
+
+        <Box gap={2}>
+          {options.map((opt, i) => {
+            const isSelected = selectedIndex === i
+            const isHighlighted = isFocused && highlightedIndex === i
+            const isOther = selectedIndex !== null && !isSelected
+
+            if (isHighlighted) {
+              return (
+                <Box key={opt.label} gap={1}>
+                  {isSelected && <Text color={THEME.success}>✓</Text>}
+                  <Gradient colors={animatedColors}>
+                    <Text bold>{opt.label}</Text>
+                  </Gradient>
+                </Box>
+              )
+            }
+
+            if (isSelected && !isFocused) {
+              return (
+                <Box key={opt.label} gap={1}>
+                  <Text color={THEME.success}>✓</Text>
+                  <Gradient colors={[...THEME.gradient]}>
+                    <Text bold>{opt.label}</Text>
+                  </Gradient>
+                </Box>
+              )
+            }
+
+            if (isOther) {
+              return (
+                <Text key={opt.label} dimColor>
+                  {opt.label}
+                </Text>
+              )
+            }
+
+            // Unresolved, unfocused
+            return (
+              <Box key={opt.label} gap={1}>
+                {isSelected && <Text color={THEME.success}>✓</Text>}
+                <Text>{opt.label}</Text>
+              </Box>
+            )
+          })}
+        </Box>
+      </Box>
+
+      {detail && (
+        <Box marginLeft={2}>
+          <Text dimColor>{detail}</Text>
+        </Box>
+      )}
+    </Box>
+  )
+}

package/src/tui/components/stage-row.tsx

@@ -9,6 +9,7 @@ export interface Stage {
   label: string
   status: StageStatus
   detail?: string
+  errors?: string[]
 }
 
 const ICONS: Record<StageStatus, ReactNode> = {
@@ -24,10 +25,21 @@ const ICONS: Record<StageStatus, ReactNode> = {
 
 export function StageRow({ stage }: { stage: Stage }) {
   return (
-    <Box gap={1}>
-      {ICONS[stage.status]}
-      <Text dimColor={stage.status === 'pending'}>{stage.label}</Text>
-      {stage.detail && <Text color={THEME.hint}> — {stage.detail}</Text>}
+    <Box flexDirection="column">
+      <Box gap={1}>
+        {ICONS[stage.status]}
+        <Text dimColor={stage.status === 'pending'}>{stage.label}</Text>
+        {stage.detail && <Text color={THEME.hint}> — {stage.detail}</Text>}
+      </Box>
+      {stage.errors && stage.errors.length > 0 && (
+        <Box flexDirection="column" marginLeft={3}>
+          {stage.errors.map((e) => (
+            <Text key={e} color={THEME.warning}>
+              {e}
+            </Text>
+          ))}
+        </Box>
+      )}
     </Box>
   )
 }

package/src/tui/context/focus-order-context.ts

@@ -21,9 +21,15 @@ const FocusOrderContext = createContext<FocusOrderState>({
   focus: () => {},
 })
 
-export function FocusOrderProvider({ children }: { children: ReactNode }) {
+export function FocusOrderProvider({
+  children,
+  initialFocusId,
+}: {
+  children: ReactNode
+  initialFocusId?: string | null
+}) {
   const [focusIds, setFocusIds] = useState<string[]>([])
-  const [focusedId, setFocusedId] = useState<string | null>(null)
+  const [focusedId, setFocusedId] = useState<string | null>(initialFocusId ?? null)
 
   const focusNext = useCallback(() => {
     setFocusedId((current) => {

package/src/tui/context/form-state-context.ts

@@ -16,6 +16,7 @@ export interface FieldState {
 
 export interface AssetSectionState {
   items: string[]
+  descriptions: Record<string, string>
   editing?: string
   adding: boolean
 }
@@ -46,6 +47,7 @@ interface FormStateContextValue {
   addAsset: (section: AssetSectionKey, name: string) => void
   removeAsset: (section: AssetSectionKey, name: string) => void
   renameAsset: (section: AssetSectionKey, oldName: string, newName: string) => void
+  setAssetDescription: (section: AssetSectionKey, name: string, description: string) => void
   setAssetAdding: (section: AssetSectionKey, adding: boolean) => void
   setAssetEditing: (section: AssetSectionKey, name?: string) => void
 
@@ -57,6 +59,7 @@ interface FormStateContextValue {
 
 const defaultAssetSection: AssetSectionState = {
   items: [],
+  descriptions: {},
   editing: undefined,
   adding: false,
 }
@@ -81,6 +84,7 @@ const FormStateContext = createContext<FormStateContextValue>({
   addAsset: () => {},
   removeAsset: () => {},
   renameAsset: () => {},
+  setAssetDescription: () => {},
   setAssetAdding: () => {},
   setAssetEditing: () => {},
   toCreateOptions: () => ({ name: '', version: '', description: '', skills: [], commands: [], agents: [] }),
@@ -88,8 +92,8 @@ const FormStateContext = createContext<FormStateContextValue>({
 
 // --- Provider ---
 
-export function FormStateProvider({ children }: { children: ReactNode }) {
-  const [form, setForm] = useState<FormState>(defaultForm)
+export function FormStateProvider({ children, initialState }: { children: ReactNode; initialState?: FormState }) {
+  const [form, setForm] = useState<FormState>(initialState ?? defaultForm)
 
   const setFieldValue = useCallback((field: RequiredFieldKey, value: string) => {
     setForm((prev) => ({
@@ -116,11 +120,16 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
     setForm((prev) => {
       const current = prev.assets[section]
       if (current.items.includes(name)) return prev
+      const defaultDesc = `The ${name} ${section} description`
       return {
         ...prev,
         assets: {
           ...prev.assets,
-          [section]: { ...current, items: [...current.items, name] },
+          [section]: {
+            ...current,
+            items: [...current.items, name],
+            descriptions: { ...current.descriptions, [name]: defaultDesc },
+          },
         },
       }
     })
@@ -129,6 +138,7 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
   const removeAsset = useCallback((section: AssetSectionKey, name: string) => {
     setForm((prev) => {
       const current = prev.assets[section]
+      const { [name]: _, ...remainingDescs } = current.descriptions
       return {
         ...prev,
         assets: {
@@ -136,6 +146,7 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
           [section]: {
             ...current,
             items: current.items.filter((item) => item !== name),
+            descriptions: remainingDescs,
             editing: current.editing === name ? undefined : current.editing,
           },
         },
@@ -148,6 +159,7 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
     setForm((prev) => {
       const current = prev.assets[section]
       if (current.items.includes(newName)) return prev
+      const { [oldName]: desc, ...restDescs } = current.descriptions
       return {
         ...prev,
         assets: {
@@ -155,6 +167,7 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
           [section]: {
             ...current,
             items: current.items.map((item) => (item === oldName ? newName : item)),
+            descriptions: { ...restDescs, [newName]: desc ?? `A ${newName} ${section}` },
             editing: current.editing === oldName ? newName : current.editing,
           },
         },
@@ -162,6 +175,22 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
     })
   }, [])
 
+  const setAssetDescription = useCallback((section: AssetSectionKey, name: string, description: string) => {
+    setForm((prev) => {
+      const current = prev.assets[section]
+      return {
+        ...prev,
+        assets: {
+          ...prev.assets,
+          [section]: {
+            ...current,
+            descriptions: { ...current.descriptions, [name]: description },
+          },
+        },
+      }
+    })
+  }, [])
+
   const setAssetAdding = useCallback((section: AssetSectionKey, adding: boolean) => {
     setForm((prev) => ({
       ...prev,
@@ -202,6 +231,7 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
       addAsset,
       removeAsset,
       renameAsset,
+      setAssetDescription,
       setAssetAdding,
       setAssetEditing,
       toCreateOptions,
@@ -213,6 +243,7 @@ export function FormStateProvider({ children }: { children: ReactNode }) {
       addAsset,
       removeAsset,
       renameAsset,
+      setAssetDescription,
       setAssetAdding,
       setAssetEditing,
       toCreateOptions,