Skip to content

Latest commit

 

History

History
303 lines (242 loc) · 5.43 KB

types.md

File metadata and controls

303 lines (242 loc) · 5.43 KB

Type System Reference

Overview

All TypeScript interfaces and type definitions are in src/types.ts. This document covers the core types used throughout the codebase.

Response Types

ToolResponse

Standard wrapper for all tool operation results.

interface ToolResponse<T = unknown> {
  success: boolean;
  data?: T;
  error?: string;
}

All tools return ToolResponse<SomeData>. Check success before accessing data.

ListAppsResponse

interface ListAppsResponse {
  apps: string[];
}

ExecuteResponse

interface ExecuteResponse {
  stdout: string;
  stderr: string;
  exitCode: number;
}

Parameter Types

ExecuteParams

interface ExecuteParams {
  script: string;
  timeout?: number;
}

GetDictionaryParams

interface GetDictionaryParams {
  app: string;
}

Dictionary Types

These types represent parsed AppleScript dictionaries (SDEF).

AppleScriptDictionary

interface AppleScriptDictionary {
  application: string;
  suites: DictionarySuite[];
  version?: string | undefined;
}

DictionarySuite

interface DictionarySuite {
  name: string;
  code?: string | undefined;
  description?: string | undefined;
  classes: DictionaryClass[];
  commands: DictionaryCommand[];
  enumerations: DictionaryEnumeration[];
}

DictionaryClass

interface DictionaryClass {
  name: string;
  code?: string | undefined;
  description?: string | undefined;
  plural?: string | undefined;
  inherits?: string | undefined;
  properties: DictionaryProperty[];
  elements: DictionaryElement[];
  respondsTo?: string[] | undefined;
}

DictionaryProperty

interface DictionaryProperty {
  name: string;
  code?: string | undefined;
  type: string;
  access: 'r' | 'w' | 'rw';
  description?: string | undefined;
}

DictionaryElement

interface DictionaryElement {
  type: string;
  description?: string | undefined;
  access?: string | undefined;
}

DictionaryCommand

interface DictionaryCommand {
  name: string;
  code?: string | undefined;
  description?: string | undefined;
  directParameter?: {
    type: string;
    description?: string | undefined;
    optional: boolean;
  };
  parameters: CommandParameter[];
  result?: {
    type: string;
    description?: string | undefined;
  };
}

CommandParameter

interface CommandParameter {
  name: string;
  code?: string | undefined;
  type: string;
  description?: string | undefined;
  optional: boolean;
}

DictionaryEnumeration

interface DictionaryEnumeration {
  name: string;
  code?: string | undefined;
  description?: string | undefined;
  values: EnumerationValue[];
}

EnumerationValue

interface EnumerationValue {
  name: string;
  code?: string | undefined;
  description?: string | undefined;
}

Cache Types

CacheEntry

interface CacheEntry<T> {
  data: T;
  timestamp: number;
  appPath: string;
}

Type Guards

isExecuteParams

function isExecuteParams(value: unknown): value is ExecuteParams

Validates that value has required script string and optional timeout number.

isGetDictionaryParams

function isGetDictionaryParams(value: unknown): value is GetDictionaryParams

Validates that value has required app string.

Extended Types (in other modules)

SafetyAnalysis (execute.ts)

interface SafetyAnalysis {
  safe: boolean;
  risk: 'none' | 'low' | 'medium' | 'high' | 'critical';
  warnings: string[];
  requiresConfirmation: boolean;
}

ExecutionRecord (pattern-store.ts)

interface ExecutionRecord {
  id: string;
  timestamp: string;
  intent: string;
  apps: string[];
  script: string;
  success: boolean;
  result: string;
  category: 'media' | 'files' | 'communication' | 'productivity' | 'system' | 'other';
  actions: string[];
  successCount: number;
  keywords: string[];
}

SystemState (system-state.ts)

interface SystemState {
  timestamp: string;
  frontmostApp: string;
  runningApps: string[];
  finderSelection: string[];
  clipboardText: string | null;
  currentVolume: number;
  musicPlaying: {
    isPlaying: boolean;
    track: string | null;
    artist: string | null;
    album: string | null;
  };
  safariTabs: Array<{ title: string; url: string }>;
}

FailureAnalysis (analyzer.ts)

interface FailureAnalysis {
  errorType: ErrorType;
  rootCause: string;
  suggestions: string[];
  relatedSuccessfulPattern: string | null;
  fixedScript: string | null;
  confidence: 'high' | 'medium' | 'low';
}

type ErrorType =
  | 'permission_denied'
  | 'app_not_running'
  | 'syntax_error'
  | 'object_not_found'
  | 'property_not_found'
  | 'command_not_understood'
  | 'timeout'
  | 'type_mismatch'
  | 'index_out_of_bounds'
  | 'missing_value'
  | 'user_cancelled'
  | 'unknown';

TypeScript Configuration

The project uses strict TypeScript settings:

{
  "strict": true,
  "noImplicitReturns": true,
  "noFallthroughCasesInSwitch": true,
  "noUncheckedIndexedAccess": true,
  "exactOptionalPropertyTypes": true,
  "noImplicitOverride": true
}

Notable settings:

  • noUncheckedIndexedAccess: Array/object index access returns T | undefined
  • exactOptionalPropertyTypes: Optional properties cannot have undefined as a value unless explicitly typed