types.ts

import type React from 'react'

/**
 * Props passed to every app tab component.
 */
export interface AppTabProps {
  tabId: string
  active: boolean
  context: AppContext
}

/**
 * Sandboxed API surface that the host app exposes to each app tab.
 * Apps must not access window globals directly.
 */
export interface AppContext {
  /** ID of the terminal tab that opened this app tab, if any. */
  terminalId?: string
  /** Working directory at the time the app tab was opened. */
  cwd?: string
  /** Run a shell command in the parent terminal. Only available when terminalId is set. */
  executeCommand?: (cmd: string) => void
  /** Open a file path in the editor, optionally jumping to a line. */
  openFile?: (path: string, line?: number) => void
  /** A specific resource path the host wants this tab to focus/open initially. */
  focusPath?: string
}

/**
 * A slash-command that an app registers.
 * The command name must NOT include the leading "/".
 */
export interface AppCommand {
  name: string
  description: string
  handler?: () => void
}

/** Sidebar nav slot an app can claim. */
export interface AppSidebarEntry {
  icon: React.ComponentType
  label: string
  order?: number
  /**
   * Keep this app's sidebar page mounted (like the Code Editor) so its
   * internal state survives switching panes/tabs and back, instead of
   * unmounting whenever the page isn't the active one. Opt into this only
   * if your page holds meaningful UI state beyond what you can keep in a
   * module-level store.
   */
  sticky?: boolean
}

/** A single contributed context-menu entry. */
export interface AppMenuContribution {
  label: string
  action: () => void
}

/** Info about the file-explorer node a context menu was opened on. */
export interface FileExplorerMenuContext {
  path: string
  name: string
  ext: string
  isDir: boolean
}

/**
 * Extension points apps can hook into to add UI to other parts of the host
 * app, rather than the host hardcoding knowledge of specific apps.
 */
export interface AppContributions {
  /**
   * Add items to the Code Editor's file-explorer right-click menu.
   * Return null/undefined/[] to contribute nothing for a given node.
   */
  fileExplorerContextMenu?: (ctx: FileExplorerMenuContext) => AppMenuContribution[] | null | undefined
}

/**
 * An app descriptor. Export a value of this type as the default export
 * from your app's entry point.
 */
export interface AppManifest {
  /** Unique identifier — use kebab-case (e.g. "my-app"). */
  id: string
  /** Human-readable display name shown in the App Store. */
  name: string
  /** Short description shown in the App Store. */
  description: string
  /** Author name or GitHub handle. */
  author: string
  /** Semver version string. */
  version: string
  /**
   * The tab type string this app owns.
   * The host routes "app:open-tab" events with this type to your TabComponent.
   */
  tabType?: string
  /** Title shown on the tab when opened. */
  tabTitle?: string
  /** React component rendered inside the tab pane. */
  TabComponent?: React.ComponentType<AppTabProps>
  /** Slash-commands this app contributes to the terminal. */
  commands?: AppCommand[]
  /** Sidebar nav slot, if this app should appear as a sidebar page. */
  sidebar?: AppSidebarEntry
  /** UI contributions this app adds to other parts of the host app. */
  contributes?: AppContributions
  /**
   * Optional pre-flight check.
   * Return a human-readable error string if a requirement is missing,
   * or null/undefined if everything is satisfied.
   */
  checkRequirements?: () => string | null | undefined
}