@specforge/mcp 1.5.3 → 2.0.0

package/dist/types/index.d.ts

@@ -24,6 +24,86 @@ export interface Project {
  * Specification status values
  */
 export type SpecificationStatus = 'draft' | 'planning' | 'ready' | 'in_progress' | 'completed';
+/**
+ * Naming conventions for the specification
+ *
+ * Defines consistent naming patterns used across the codebase.
+ */
+export interface NamingConventions {
+    /** File naming pattern (e.g., "camelCase.ts") */
+    files?: string;
+    /** Function naming pattern (e.g., "_hookFunction") */
+    functions?: string;
+    /** Interface naming pattern (e.g., "FunctionNameProps") */
+    interfaces?: string;
+    /** Action naming pattern (e.g., "SCREAMING_SNAKE_CASE") */
+    actions?: string;
+    /** Component naming pattern (e.g., "PascalCase") */
+    components?: string;
+    /** Variable naming pattern (e.g., "camelCase") */
+    variables?: string;
+    /** Class naming pattern (e.g., "PascalCase") */
+    classes?: string;
+    /** Constant naming pattern (e.g., "UPPER_SNAKE_CASE") */
+    constants?: string;
+}
+/**
+ * Code standards defined at specification level
+ *
+ * Forms the top level of the pattern inheritance chain.
+ * These standards are inherited by all epics and tickets within the specification.
+ */
+export interface SpecificationCodeStandards {
+    /** Primary language (e.g., "TypeScript") */
+    language?: string;
+    /** Async pattern (e.g., "async/await") */
+    asyncPattern?: string;
+    /** Error handling approach (e.g., "Result<T> pattern") */
+    errorHandling?: string;
+    /** Documentation style (e.g., "JSDoc with @example") */
+    documentation?: string;
+    /** Testing approach (e.g., "AAA pattern") */
+    testing?: string;
+    /** Naming conventions */
+    naming?: NamingConventions;
+    /** State management pattern */
+    stateManagement?: string;
+    /** API pattern (e.g., "REST", "GraphQL") */
+    apiPattern?: string;
+    /** Logging approach */
+    logging?: string;
+    /** Validation approach */
+    validation?: string;
+    /** Additional custom standards */
+    custom?: Record<string, string>;
+}
+/**
+ * Return type patterns for CRUD operations
+ *
+ * Defines consistent return types for database/API operations.
+ */
+export interface ReturnTypes {
+    /** Create operation return type (e.g., "BusinessCreateResult<T>") */
+    create?: string;
+    /** Update operation return type (e.g., "BusinessUpdateResult<T>") */
+    update?: string;
+    /** Delete operation return type (e.g., "BusinessDeleteResult") */
+    delete?: string;
+    /** List operation return type (e.g., "BusinessListResult<T>") */
+    list?: string;
+    /** Get single item return type */
+    get?: string;
+    /** Additional custom return types */
+    custom?: Record<string, string>;
+}
+/**
+ * Type guard for SpecificationCodeStandards
+ */
+export declare function isValidCodeStandards(value: unknown): value is SpecificationCodeStandards;
+/**
+ * Type guard for ReturnTypes
+ */
+export declare function isValidReturnTypes(value: unknown): value is ReturnTypes;
 /**
  * Specification entity
  */
@@ -49,9 +129,73 @@ export interface Specification {
     priority?: 'high' | 'medium' | 'low';
     tags?: string[];
     estimatedHours?: number;
+    /** Code standards for the specification (inherited by epics/tickets) */
+    codeStandards?: SpecificationCodeStandards;
+    /** Common imports used across the specification */
+    commonImports?: string[];
+    /** Return type patterns for CRUD operations */
+    returnTypes?: ReturnTypes;
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Shared patterns defined at epic level
+ *
+ * These patterns can override specification-level patterns for all tickets
+ * within the epic. Useful for epics that need different conventions.
+ */
+export interface EpicSharedPatterns {
+    /** Override error handling for this epic */
+    errorHandling?: string;
+    /** Epic-specific return type override */
+    returnType?: string;
+    /** Action prefix for Redux actions (e.g., "CHANNEL_") */
+    actionPrefix?: string;
+    /** Redux state slice path (e.g., "state.channel") */
+    stateSlice?: string;
+    /** API base path for this epic */
+    apiBasePath?: string;
+    /** Component folder for this epic */
+    componentFolder?: string;
+    /** Hook naming pattern for this epic */
+    hookPattern?: string;
+    /** Additional custom patterns */
+    custom?: Record<string, string>;
+}
+/**
+ * Common files used across all tickets in an epic
+ *
+ * Defines file paths that are shared/referenced by multiple tickets
+ * in the epic. Helps AI understand the epic's file structure.
+ */
+export interface EpicCommonFiles {
+    /** Reducer file path */
+    reducer?: string;
+    /** Actions file path */
+    actions?: string;
+    /** Types file path */
+    types?: string;
+    /** Index/barrel file path */
+    index?: string;
+    /** Selectors file path */
+    selectors?: string;
+    /** Hooks file path */
+    hooks?: string;
+    /** API client file path */
+    api?: string;
+    /** Test utilities file path */
+    testUtils?: string;
+    /** Additional custom files */
+    custom?: Record<string, string>;
+}
+/**
+ * Type guard for EpicSharedPatterns
+ */
+export declare function isValidEpicSharedPatterns(value: unknown): value is EpicSharedPatterns;
+/**
+ * Type guard for EpicCommonFiles
+ */
+export declare function isValidEpicCommonFiles(value: unknown): value is EpicCommonFiles;
 /**
  * Epic status values
  */
@@ -77,7 +221,7 @@ export interface Epic {
     fileStructure?: string;
     techStack?: string[];
     dependencies?: string[];
-    apiContracts?: any;
+    apiContracts?: unknown;
     status: EpicStatus;
     progress: number;
     order: number;
@@ -90,6 +234,12 @@ export interface Epic {
     tags?: string[];
     estimatedHours?: number;
     acceptanceCriteria?: string[];
+    /** Shared patterns for this epic (overrides specification patterns) */
+    sharedPatterns?: EpicSharedPatterns;
+    /** Additional imports specific to this epic */
+    additionalImports?: string[];
+    /** Common files shared across tickets in this epic */
+    commonFiles?: EpicCommonFiles;
     createdAt: string;
     updatedAt: string;
 }
@@ -98,37 +248,248 @@ export interface Epic {
  */
 export type TicketStatus = 'todo' | 'queue' | 'in_progress' | 'blocked' | 'done';
 /**
- * Implementation details stored with a ticket
+ * Supported implementation step action types
+ */
+export type ImplementationAction = 'create' | 'code' | 'validate' | 'api' | 'dispatch' | 'test' | 'config' | 'refactor' | 'delete' | 'document';
+/**
+ * A single implementation step with structured details
+ */
+export interface ImplementationStep {
+    /** Execution order (1-based) */
+    order: number;
+    /** Brief title describing the step */
+    title: string;
+    /** Type of action to perform */
+    action: ImplementationAction;
+    /** Detailed description of what to do */
+    detail: string;
+    /** Optional code snippet for reference */
+    codeSnippet?: string;
+    /** Optional file path this step applies to */
+    targetFile?: string;
+    /** Estimated minutes for this step */
+    estimatedMinutes?: number;
+}
+/**
+ * Code example for reference
+ */
+export interface CodeExample {
+    /** Name/title of the example */
+    name: string;
+    /** Programming language */
+    language: string;
+    /** The actual code */
+    code: string;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Implementation details stored with a ticket (enhanced schema)
  */
 export interface TicketImplementation {
-    /** Files to create */
+    /** Ordered list of implementation steps */
+    steps?: ImplementationStep[];
+    /** Optional code examples for reference */
+    codeExamples?: CodeExample[];
+    /** Optional summary or overview */
+    summary?: string;
+    /** Optional prerequisites */
+    prerequisites?: string[];
+    /** @deprecated Use steps[].targetFile with action='create' */
     filesToCreate?: string[];
-    /** Files to modify */
+    /** @deprecated Use steps[].targetFile with action='code' */
     filesToModify?: string[];
-    /** Implementation steps */
-    steps?: string[];
-    /** Code snippets */
+    /** @deprecated Use codeExamples or steps[].codeSnippet */
     codeSnippets?: Record<string, string>;
-    /** Testing approach */
+    /** @deprecated Use steps with action='test' */
     testing?: string;
-    /** Notes */
+    /** @deprecated Use summary field */
     notes?: string;
 }
 /**
- * Technical details for a ticket
+ * Type guard to check if value is valid TicketImplementation
+ */
+export declare function isValidImplementation(value: unknown): value is TicketImplementation;
+/**
+ * HTTP methods for API endpoints
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * File to be created
+ */
+export interface FileCreate {
+    /** File path relative to project root */
+    path: string;
+    /** Purpose/description of the file */
+    purpose: string;
+    /** Optional template or boilerplate to use */
+    template?: string;
+}
+/**
+ * File to be modified
+ */
+export interface FileModify {
+    /** File path relative to project root */
+    path: string;
+    /** Description of the change */
+    change: string;
+    /** Optional specific line range */
+    lineRange?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * File to be deleted
+ */
+export interface FileDelete {
+    /** File path relative to project root */
+    path: string;
+    /** Reason for deletion */
+    reason: string;
+}
+/**
+ * API endpoint definition
+ */
+export interface ApiEndpoint {
+    /** HTTP method */
+    method: HttpMethod;
+    /** URL path */
+    path: string;
+    /** Description of the endpoint */
+    description: string;
+    /** Optional request body schema */
+    requestBody?: string;
+    /** Optional response schema */
+    responseBody?: string;
+}
+/**
+ * Database operation
+ */
+export interface DatabaseOperation {
+    /** Operation type */
+    type: 'create' | 'read' | 'update' | 'delete' | 'migration';
+    /** Table/collection name */
+    table: string;
+    /** Description of the operation */
+    description: string;
+}
+/**
+ * Environment variable definition
+ */
+export interface EnvVarDefinition {
+    /** Variable name */
+    name: string;
+    /** Description of the variable */
+    description: string;
+    /** Whether the variable is required */
+    required: boolean;
+}
+/**
+ * External service dependency
+ */
+export interface ExternalServiceDependency {
+    /** Service name */
+    name: string;
+    /** Purpose of using the service */
+    purpose: string;
+}
+/**
+ * Technical details for a ticket (enhanced schema)
+ *
+ * Captures file operations, patterns, imports, API endpoints,
+ * and other technical requirements in a structured format.
  */
 export interface TicketTechnicalDetails {
-    /** Files referenced */
-    files?: string[];
-    /** Technology stack */
+    /** File operations */
+    files?: {
+        create?: FileCreate[];
+        modify?: FileModify[];
+        delete?: FileDelete[];
+    };
+    /** Pattern references (key: pattern name, value: description/usage) */
+    patterns?: Record<string, string>;
+    /** Required imports/dependencies */
+    imports?: string[];
+    /** API endpoints involved */
+    endpoints?: ApiEndpoint[];
+    /** Database operations */
+    database?: DatabaseOperation[];
+    /** Environment variables needed */
+    envVars?: EnvVarDefinition[];
+    /** External service dependencies */
+    externalServices?: ExternalServiceDependency[];
+    /** @deprecated Use files.create/modify for file operations */
     stack?: string[];
-    /** API endpoints */
-    endpoints?: string[];
-    /** Database changes */
+    /** @deprecated Use database field */
     databaseChanges?: string[];
-    /** Environment variables */
-    envVars?: string[];
 }
+/**
+ * Type guard for TicketTechnicalDetails
+ *
+ * Validates that a value conforms to the TicketTechnicalDetails structure.
+ */
+export declare function isValidTechnicalDetails(value: unknown): value is TicketTechnicalDetails;
+/**
+ * Reference type for categorizing links
+ */
+export type ReferenceType = 'documentation' | 'example' | 'related' | 'external';
+/**
+ * Reference link with optional description
+ */
+export interface Reference {
+    /** URL or document path */
+    url: string;
+    /** Title or description */
+    title: string;
+    /** Type of reference */
+    type?: ReferenceType;
+}
+/**
+ * Alternative approach consideration
+ */
+export interface Alternative {
+    /** Title of the alternative */
+    title: string;
+    /** Description of the approach */
+    description: string;
+    /** Why it wasn't chosen */
+    reason?: string;
+    /** Pros of this alternative */
+    pros?: string[];
+    /** Cons of this alternative */
+    cons?: string[];
+}
+/**
+ * Notes and context for a ticket (enhanced schema)
+ *
+ * Captures warnings, best practices, alternatives, references,
+ * and other contextual information in a structured format.
+ */
+export interface TicketNotes {
+    /** Important warnings and gotchas */
+    warnings?: string[];
+    /** Recommended best practices */
+    bestPractices?: string[];
+    /** Alternative approaches considered */
+    alternatives?: Alternative[] | string[];
+    /** Reference links and documentation */
+    references?: Reference[] | string[];
+    /** General context and background */
+    context?: string;
+    /** Known limitations */
+    limitations?: string[];
+    /** Future considerations */
+    futureWork?: string[];
+    /** Related tickets or issues */
+    relatedTickets?: string[];
+}
+/**
+ * Type guard for TicketNotes
+ *
+ * Validates that a value conforms to the TicketNotes structure.
+ */
+export declare function isValidNotes(value: unknown): value is TicketNotes;
 /**
  * Ticket entity
  */
@@ -144,7 +505,8 @@ export interface Ticket {
     priority?: 'high' | 'medium' | 'low';
     complexity?: 'small' | 'medium' | 'large' | 'xlarge';
     tags?: string[];
-    notes?: string;
+    /** Notes and context - supports both simple string (legacy) and structured TicketNotes */
+    notes?: string | TicketNotes;
     implementation?: TicketImplementation;
     acceptanceCriteria?: string[];
     technicalDetails?: TicketTechnicalDetails;
@@ -558,4 +920,190 @@ export interface ResetTicketsResult {
         reason: string;
     }>;
 }
+/**
+ * Ticket definition for bulk creation
+ */
+export interface BulkCreateTicketDefinition {
+    /** Ticket title (required) */
+    title: string;
+    /** Ticket description */
+    description?: string;
+    /** Estimated hours */
+    estimatedHours?: number;
+    /** Complexity level */
+    complexity?: 'small' | 'medium' | 'large' | 'xlarge';
+    /** Priority level */
+    priority?: 'high' | 'medium' | 'low';
+    /** Acceptance criteria */
+    acceptanceCriteria?: string[];
+    /** Implementation details */
+    implementation?: TicketImplementation;
+    /** Technical details */
+    technicalDetails?: TicketTechnicalDetails;
+    /** Tags */
+    tags?: string[];
+}
+/**
+ * Inline dependency definition for bulk creation
+ */
+export interface BulkCreateDependencyDefinition {
+    /** Index of the ticket in the tickets array */
+    ticket: number;
+    /** Index(es) of the ticket(s) it depends on */
+    dependsOn: number | number[];
+}
+/**
+ * Request for bulk create tickets operation
+ */
+export interface BulkCreateTicketsRequest {
+    /** Epic ID to create tickets in */
+    epicId: string;
+    /** Array of ticket definitions */
+    tickets: BulkCreateTicketDefinition[];
+    /** Optional inline dependencies using array indexes */
+    dependencies?: BulkCreateDependencyDefinition[];
+}
+/**
+ * Created ticket info in bulk create response
+ */
+export interface BulkCreatedTicketInfo {
+    /** Generated ticket ID */
+    id: string;
+    /** Assigned ticket number */
+    ticketNumber: number;
+    /** Ticket title */
+    title: string;
+}
+/**
+ * Result of bulk create tickets operation
+ */
+export interface BulkCreateTicketsResult {
+    /** Number of tickets created */
+    created: number;
+    /** Created ticket information */
+    tickets: BulkCreatedTicketInfo[];
+    /** Number of dependencies created */
+    dependenciesCreated: number;
+}
+/**
+ * Single dependency definition for bulk add
+ */
+export interface BulkDependencyDefinition {
+    /** ID of the ticket that will depend on another */
+    ticketId: string;
+    /** ID of the ticket it will depend on */
+    dependsOnId: string;
+    /** Type of dependency (default: 'requires') */
+    type?: 'blocks' | 'requires';
+}
+/**
+ * Request for bulk add dependencies operation
+ */
+export interface BulkAddDependenciesRequest {
+    /** Array of dependency definitions */
+    dependencies: BulkDependencyDefinition[];
+    /** Skip validation of circular dependencies (default: false) */
+    skipCircularCheck?: boolean;
+}
+/**
+ * Result of bulk add dependencies operation
+ */
+export interface BulkAddDependenciesResult {
+    /** Number of dependencies created */
+    created: number;
+    /** IDs of created dependency records */
+    dependencyIds: string[];
+    /** Dependencies that were skipped (duplicates) */
+    skipped: number;
+}
+/**
+ * Request for lookup_project operation
+ */
+export interface LookupProjectRequest {
+    /** Project name to search for (partial match, case-insensitive) */
+    name: string;
+}
+/**
+ * Minimal project info returned by lookup_project
+ */
+export interface LookupProjectResult {
+    /** Project ID */
+    id: string;
+    /** Project name */
+    name: string;
+    /** Number of specifications in the project */
+    specCount: number;
+}
+/**
+ * Request for lookup_specification operation
+ */
+export interface LookupSpecificationRequest {
+    /** Specification title to search for (partial match, case-insensitive) */
+    title: string;
+    /** Optional project ID to narrow search */
+    projectId?: string;
+}
+/**
+ * Minimal specification info returned by lookup_specification
+ */
+export interface LookupSpecificationResult {
+    /** Specification ID */
+    id: string;
+    /** Specification title */
+    title: string;
+    /** Status */
+    status: SpecificationStatus;
+    /** Number of epics */
+    epicCount: number;
+}
+/**
+ * Request for lookup_epic operation
+ */
+export interface LookupEpicRequest {
+    /** Epic title to search for (partial match, case-insensitive) */
+    title: string;
+    /** Specification ID to search within */
+    specificationId: string;
+}
+/**
+ * Minimal epic info returned by lookup_epic
+ */
+export interface LookupEpicResult {
+    /** Epic ID */
+    id: string;
+    /** Epic title */
+    title: string;
+    /** Epic number */
+    epicNumber: number;
+    /** Status */
+    status: EpicStatus;
+    /** Number of tickets */
+    ticketCount: number;
+}
+/**
+ * Request for lookup_ticket operation
+ */
+export interface LookupTicketRequest {
+    /** Ticket title to search for (partial match, case-insensitive) */
+    title: string;
+    /** Optional epic ID to narrow search */
+    epicId?: string;
+    /** Optional specification ID to narrow search */
+    specificationId?: string;
+}
+/**
+ * Minimal ticket info returned by lookup_ticket
+ */
+export interface LookupTicketResult {
+    /** Ticket ID */
+    id: string;
+    /** Ticket title */
+    title: string;
+    /** Ticket number */
+    ticketNumber: number;
+    /** Status */
+    status: TicketStatus;
+    /** Epic ID */
+    epicId: string;
+}
 //# sourceMappingURL=index.d.ts.map