@orbytautomation/engine 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +1 -1
  2. package/dist/errors/ErrorCodes.d.ts +205 -6
  3. package/dist/errors/ErrorCodes.d.ts.map +1 -1
  4. package/dist/errors/ErrorCodes.js +398 -5
  5. package/dist/errors/ErrorCodes.js.map +1 -1
  6. package/dist/errors/ErrorDebugger.d.ts +98 -0
  7. package/dist/errors/ErrorDebugger.d.ts.map +1 -0
  8. package/dist/errors/ErrorDebugger.js +283 -0
  9. package/dist/errors/ErrorDebugger.js.map +1 -0
  10. package/dist/errors/ErrorDetector.d.ts +148 -0
  11. package/dist/errors/ErrorDetector.d.ts.map +1 -0
  12. package/dist/errors/ErrorDetector.js +358 -0
  13. package/dist/errors/ErrorDetector.js.map +1 -0
  14. package/dist/errors/ErrorFormatter.d.ts +92 -3
  15. package/dist/errors/ErrorFormatter.d.ts.map +1 -1
  16. package/dist/errors/ErrorFormatter.js +220 -4
  17. package/dist/errors/ErrorFormatter.js.map +1 -1
  18. package/dist/errors/ErrorHandler.d.ts +259 -0
  19. package/dist/errors/ErrorHandler.d.ts.map +1 -0
  20. package/dist/errors/ErrorHandler.js +378 -0
  21. package/dist/errors/ErrorHandler.js.map +1 -0
  22. package/dist/errors/FieldRegistry.d.ts +39 -0
  23. package/dist/errors/FieldRegistry.d.ts.map +1 -1
  24. package/dist/errors/FieldRegistry.js +172 -74
  25. package/dist/errors/FieldRegistry.js.map +1 -1
  26. package/dist/errors/OrbytError.d.ts +85 -3
  27. package/dist/errors/OrbytError.d.ts.map +1 -1
  28. package/dist/errors/OrbytError.js +151 -4
  29. package/dist/errors/OrbytError.js.map +1 -1
  30. package/dist/errors/SchedulerError.d.ts +93 -1
  31. package/dist/errors/SchedulerError.d.ts.map +1 -1
  32. package/dist/errors/SchedulerError.js +145 -1
  33. package/dist/errors/SchedulerError.js.map +1 -1
  34. package/dist/errors/SecurityErrors.d.ts +94 -12
  35. package/dist/errors/SecurityErrors.d.ts.map +1 -1
  36. package/dist/errors/SecurityErrors.js +162 -18
  37. package/dist/errors/SecurityErrors.js.map +1 -1
  38. package/dist/errors/StepError.d.ts +111 -1
  39. package/dist/errors/StepError.d.ts.map +1 -1
  40. package/dist/errors/StepError.js +182 -1
  41. package/dist/errors/StepError.js.map +1 -1
  42. package/dist/errors/WorkflowError.d.ts +139 -2
  43. package/dist/errors/WorkflowError.d.ts.map +1 -1
  44. package/dist/errors/WorkflowError.js +264 -22
  45. package/dist/errors/WorkflowError.js.map +1 -1
  46. package/dist/errors/index.d.ts +5 -1
  47. package/dist/errors/index.d.ts.map +1 -1
  48. package/dist/errors/index.js +7 -4
  49. package/dist/errors/index.js.map +1 -1
  50. package/dist/loader/WorkflowLoader.d.ts +83 -21
  51. package/dist/loader/WorkflowLoader.d.ts.map +1 -1
  52. package/dist/loader/WorkflowLoader.js +169 -55
  53. package/dist/loader/WorkflowLoader.js.map +1 -1
  54. package/dist/parser/SchemaValidator.d.ts.map +1 -1
  55. package/dist/parser/SchemaValidator.js +2 -1
  56. package/dist/parser/SchemaValidator.js.map +1 -1
  57. package/package.json +1 -1
@@ -4,19 +4,53 @@
4
4
  * Foundation for all Orbyt errors with diagnostic capabilities.
5
5
  * Provides structured error information for CLI, UI, and AI integrations.
6
6
  *
7
+ * ARCHITECTURE:
8
+ * - Error codes (ORB-XX-NNN): Structured codes for error identification
9
+ * - Exit codes (from @dev-ecosystem/core): Process exit codes for shell scripts
10
+ * - Severity levels: ERROR, WARNING, INFO
11
+ * - Context + hints: Help users debug and fix issues
12
+ *
7
13
  * @module errors
8
14
  */
9
- import { getErrorCategory } from './ErrorCodes.js';
15
+ import { getErrorCategory, getErrorDescription, getExitCodeForError, getSuggestedAction, isUserError, isRetryable } from './ErrorCodes.js';
10
16
  /**
11
17
  * Base error class for all Orbyt errors
18
+ *
19
+ * Provides rich diagnostic information including:
20
+ * - Structured error code
21
+ * - Exit code for process termination
22
+ * - Location in workflow where error occurred
23
+ * - Hints for fixing the error
24
+ * - Additional context for debugging
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * throw new OrbytError({
29
+ * code: OrbytErrorCode.SCHEMA_MISSING_FIELD,
30
+ * message: 'Missing required field "version"',
31
+ * exitCode: ExitCodes.INVALID_SCHEMA,
32
+ * path: 'workflow',
33
+ * hint: 'Add "version: 1.0" to your workflow definition',
34
+ * severity: ErrorSeverity.ERROR,
35
+ * });
36
+ * ```
12
37
  */
13
38
  export class OrbytError extends Error {
14
39
  /** Error diagnostic information */
15
40
  diagnostic;
41
+ /** Timestamp when error occurred */
42
+ timestamp;
16
43
  constructor(diagnostic) {
17
44
  super(diagnostic.message);
18
45
  this.name = getErrorCategory(diagnostic.code);
19
- this.diagnostic = diagnostic;
46
+ this.diagnostic = {
47
+ ...diagnostic,
48
+ // Use getExitCodeForError for proper mapping, fallback to provided or default
49
+ exitCode: diagnostic.exitCode || getExitCodeForError(diagnostic.code),
50
+ // If no hint provided, use suggested action
51
+ hint: diagnostic.hint || getSuggestedAction(diagnostic.code),
52
+ };
53
+ this.timestamp = new Date();
20
54
  // Maintains proper stack trace for where error was thrown (V8 only)
21
55
  if (Error.captureStackTrace) {
22
56
  Error.captureStackTrace(this, this.constructor);
@@ -28,6 +62,12 @@ export class OrbytError extends Error {
28
62
  get code() {
29
63
  return this.diagnostic.code;
30
64
  }
65
+ /**
66
+ * Get the exit code for process termination
67
+ */
68
+ get exitCode() {
69
+ return this.diagnostic.exitCode;
70
+ }
31
71
  /**
32
72
  * Get the error path (where it occurred)
33
73
  */
@@ -46,32 +86,139 @@ export class OrbytError extends Error {
46
86
  get severity() {
47
87
  return this.diagnostic.severity;
48
88
  }
89
+ /**
90
+ * Get detailed error description
91
+ */
92
+ get description() {
93
+ return getErrorDescription(this.code);
94
+ }
95
+ /**
96
+ * Check if this is a user-fixable error
97
+ * @returns True if user can fix by changing workflow
98
+ */
99
+ get isUserError() {
100
+ return isUserError(this.code);
101
+ }
102
+ /**
103
+ * Check if this error is retryable
104
+ * @returns True if retry might succeed
105
+ */
106
+ get isRetryable() {
107
+ return isRetryable(this.code);
108
+ }
109
+ /**
110
+ * Get error category (Schema, Validation, Execution, Runtime)
111
+ */
112
+ get category() {
113
+ return getErrorCategory(this.code);
114
+ }
49
115
  /**
50
116
  * Format error as string for logging/display
117
+ * Includes all diagnostic information in a readable format
118
+ *
119
+ * @returns Formatted error string
51
120
  */
52
121
  toString() {
53
122
  let msg = `${this.name} [${this.code}]`;
54
123
  if (this.path) {
55
124
  msg += ` at ${this.path}`;
56
125
  }
57
- msg += `\n${this.message}`;
126
+ msg += `\n\n${this.message}`;
58
127
  if (this.hint) {
59
- msg += `\n Hint: ${this.hint}`;
128
+ msg += `\n\n💡 Hint: ${this.hint}`;
129
+ }
130
+ if (this.diagnostic.context && Object.keys(this.diagnostic.context).length > 0) {
131
+ msg += `\n\n📋 Context: ${JSON.stringify(this.diagnostic.context, null, 2)}`;
60
132
  }
61
133
  return msg;
62
134
  }
135
+ /**
136
+ * Format error as detailed string with full diagnostic info
137
+ * Used for verbose logging and debugging
138
+ *
139
+ * @returns Detailed formatted error string with box drawing
140
+ */
141
+ toDetailedString() {
142
+ const lines = [
143
+ '━'.repeat(70),
144
+ `❌ ${this.name}`,
145
+ '━'.repeat(70),
146
+ '',
147
+ `Error Code: ${this.code}`,
148
+ `Exit Code: ${this.exitCode} (${this.getExitCodeDescription()})`,
149
+ `Severity: ${this.severity.toUpperCase()}`,
150
+ `Category: ${this.category}`,
151
+ `Timestamp: ${this.timestamp.toISOString()}`,
152
+ `User Fixable: ${this.isUserError ? 'Yes' : 'No'}`,
153
+ `Retryable: ${this.isRetryable ? 'Yes' : 'No'}`,
154
+ ];
155
+ if (this.path) {
156
+ lines.push(`Location: ${this.path}`);
157
+ }
158
+ lines.push('', '📝 Message:', ` ${this.message}`);
159
+ if (this.description) {
160
+ lines.push('', '📖 Description:', ` ${this.description}`);
161
+ }
162
+ if (this.hint) {
163
+ lines.push('', '💡 Hint:', ` ${this.hint}`);
164
+ }
165
+ if (this.diagnostic.context && Object.keys(this.diagnostic.context).length > 0) {
166
+ lines.push('', '📋 Context:');
167
+ Object.entries(this.diagnostic.context).forEach(([key, value]) => {
168
+ lines.push(` ${key}: ${JSON.stringify(value)}`);
169
+ });
170
+ }
171
+ lines.push('', '━'.repeat(70));
172
+ return lines.join('\n');
173
+ }
174
+ /**
175
+ * Get human-readable description of exit code
176
+ */
177
+ getExitCodeDescription() {
178
+ // Import at runtime to avoid circular dependencies
179
+ try {
180
+ const { getExitCodeDescription } = require('@dev-ecosystem/core');
181
+ return getExitCodeDescription(this.exitCode);
182
+ }
183
+ catch {
184
+ return 'exit code';
185
+ }
186
+ }
63
187
  /**
64
188
  * Convert to JSON for structured logging
189
+ * Suitable for sending to logging services, APIs, or storing in databases
190
+ *
191
+ * @returns JSON representation of error
65
192
  */
66
193
  toJSON() {
67
194
  return {
68
195
  name: this.name,
196
+ category: this.category,
69
197
  code: this.code,
198
+ exitCode: this.exitCode,
70
199
  message: this.message,
200
+ description: this.description,
71
201
  path: this.path,
72
202
  hint: this.hint,
73
203
  severity: this.severity,
74
204
  context: this.diagnostic.context,
205
+ timestamp: this.timestamp.toISOString(),
206
+ isUserError: this.isUserError,
207
+ isRetryable: this.isRetryable,
208
+ };
209
+ }
210
+ /**
211
+ * Create a simplified error object for CLI display
212
+ * Contains only essential information for user-facing output
213
+ *
214
+ * @returns Simplified error object
215
+ */
216
+ toSimpleObject() {
217
+ return {
218
+ code: this.code,
219
+ message: this.message,
220
+ hint: this.hint,
221
+ path: this.path,
75
222
  };
76
223
  }
77
224
  }
@@ -1 +1 @@
1
- {"version":3,"file":"OrbytError.js","sourceRoot":"","sources":["../../src/errors/OrbytError.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAiC,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAyBlF;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,mCAAmC;IACnB,UAAU,CAAuB;IAEjD,YAAY,UAAgC;QAC1C,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,oEAAoE;QACpE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC;QAExC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,GAAG,IAAI,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,CAAC;QAED,GAAG,IAAI,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAE3B,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,GAAG,IAAI,aAAa,IAAI,CAAC,IAAI,EAAE,CAAC;QAClC,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO;SACjC,CAAC;IACJ,CAAC;CACF"}
1
+ {"version":3,"file":"OrbytError.js","sourceRoot":"","sources":["../../src/errors/OrbytError.ts"],"names":[],"mappings":"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"}
@@ -1,2 +1,94 @@
1
- export {};
1
+ /**
2
+ * Scheduler Error
3
+ *
4
+ * Structured error for workflow scheduler failures.
5
+ * Used for cron triggers, scheduled workflows, and scheduling conflicts.
6
+ *
7
+ * Exit codes:
8
+ * - VALIDATION_FAILED: Invalid cron expression or schedule config
9
+ * - MISSING_CONFIG: Schedule not found
10
+ * - INTERNAL_ERROR: Scheduler internal error
11
+ *
12
+ * @module errors
13
+ */
14
+ import { ExitCodes } from '@dev-ecosystem/core';
15
+ import { OrbytError } from './OrbytError.js';
16
+ /**
17
+ * Scheduler error codes
18
+ * Note: These are engine-specific and may be added to ecosystem-core in the future
19
+ */
20
+ export declare enum SchedulerErrorCode {
21
+ /** Invalid cron expression */
22
+ INVALID_CRON_EXPRESSION = "ORBYT-SCH-001",
23
+ /** Schedule conflict */
24
+ SCHEDULE_CONFLICT = "ORBYT-SCH-002",
25
+ /** Scheduler not initialized */
26
+ SCHEDULER_NOT_INITIALIZED = "ORBYT-SCH-003",
27
+ /** Workflow scheduling failed */
28
+ WORKFLOW_SCHEDULE_FAILED = "ORBYT-SCH-004",
29
+ /** Schedule not found */
30
+ SCHEDULE_NOT_FOUND = "ORBYT-SCH-005"
31
+ }
32
+ /**
33
+ * Scheduler-specific error context
34
+ */
35
+ export interface SchedulerErrorContext {
36
+ /** Cron expression if applicable */
37
+ cronExpression?: string;
38
+ /** Workflow path being scheduled */
39
+ workflowPath?: string;
40
+ /** Schedule ID */
41
+ scheduleId?: string;
42
+ /** Trigger type (cron, event, webhook) */
43
+ triggerType?: string;
44
+ /** Next scheduled run time */
45
+ nextRun?: Date;
46
+ /** Additional context */
47
+ [key: string]: any;
48
+ }
49
+ /**
50
+ * Scheduler Error class
51
+ */
52
+ export declare class SchedulerError extends OrbytError {
53
+ readonly scheduleId?: string;
54
+ readonly cronExpression?: string;
55
+ constructor(params: {
56
+ code: SchedulerErrorCode;
57
+ message: string;
58
+ scheduleId?: string;
59
+ cronExpression?: string;
60
+ context?: Partial<SchedulerErrorContext>;
61
+ hint?: string;
62
+ cause?: Error;
63
+ exitCode?: ExitCodes;
64
+ });
65
+ /**
66
+ * Determine exit code based on scheduler error code
67
+ */
68
+ private static getExitCode;
69
+ /**
70
+ * Determine severity based on error code
71
+ */
72
+ private static determineSeverity;
73
+ /**
74
+ * Factory: Invalid cron expression
75
+ */
76
+ static invalidCronExpression(expression: string, reason?: string): SchedulerError;
77
+ /**
78
+ * Factory: Schedule conflict
79
+ */
80
+ static scheduleConflict(scheduleId: string, workflowPath: string): SchedulerError;
81
+ /**
82
+ * Factory: Scheduler not initialized
83
+ */
84
+ static notInitialized(): SchedulerError;
85
+ /**
86
+ * Factory: Workflow scheduling failed
87
+ */
88
+ static schedulingFailed(workflowPath: string, cause: Error): SchedulerError;
89
+ /**
90
+ * Factory: Schedule not found
91
+ */
92
+ static notFound(scheduleId: string): SchedulerError;
93
+ }
2
94
  //# sourceMappingURL=SchedulerError.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"SchedulerError.d.ts","sourceRoot":"","sources":["../../src/errors/SchedulerError.ts"],"names":[],"mappings":""}
1
+ {"version":3,"file":"SchedulerError.d.ts","sourceRoot":"","sources":["../../src/errors/SchedulerError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,8BAA8B;IAC9B,uBAAuB,kBAAkB;IAEzC,wBAAwB;IACxB,iBAAiB,kBAAkB;IAEnC,gCAAgC;IAChC,yBAAyB,kBAAkB;IAE3C,iCAAiC;IACjC,wBAAwB,kBAAkB;IAE1C,yBAAyB;IACzB,kBAAkB,kBAAkB;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,IAAI,CAAC;IAEf,yBAAyB;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpC,SAAgB,cAAc,CAAC,EAAE,MAAM,CAAC;gBAE5B,MAAM,EAAE;QAClB,IAAI,EAAE,kBAAkB,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,OAAO,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;QACzC,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,KAAK,CAAC;QACd,QAAQ,CAAC,EAAE,SAAS,CAAC;KACtB;IAmBD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAgB1B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAkBhC;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc;IASjF;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,cAAc;IAUjF;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,cAAc;IAQvC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,cAAc;IAU3E;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc;CAQpD"}
@@ -1,2 +1,146 @@
1
- export {};
1
+ /**
2
+ * Scheduler Error
3
+ *
4
+ * Structured error for workflow scheduler failures.
5
+ * Used for cron triggers, scheduled workflows, and scheduling conflicts.
6
+ *
7
+ * Exit codes:
8
+ * - VALIDATION_FAILED: Invalid cron expression or schedule config
9
+ * - MISSING_CONFIG: Schedule not found
10
+ * - INTERNAL_ERROR: Scheduler internal error
11
+ *
12
+ * @module errors
13
+ */
14
+ import { ExitCodes } from '@dev-ecosystem/core';
15
+ import { OrbytError } from './OrbytError.js';
16
+ import { ErrorSeverity } from './ErrorCodes.js';
17
+ /**
18
+ * Scheduler error codes
19
+ * Note: These are engine-specific and may be added to ecosystem-core in the future
20
+ */
21
+ export var SchedulerErrorCode;
22
+ (function (SchedulerErrorCode) {
23
+ /** Invalid cron expression */
24
+ SchedulerErrorCode["INVALID_CRON_EXPRESSION"] = "ORBYT-SCH-001";
25
+ /** Schedule conflict */
26
+ SchedulerErrorCode["SCHEDULE_CONFLICT"] = "ORBYT-SCH-002";
27
+ /** Scheduler not initialized */
28
+ SchedulerErrorCode["SCHEDULER_NOT_INITIALIZED"] = "ORBYT-SCH-003";
29
+ /** Workflow scheduling failed */
30
+ SchedulerErrorCode["WORKFLOW_SCHEDULE_FAILED"] = "ORBYT-SCH-004";
31
+ /** Schedule not found */
32
+ SchedulerErrorCode["SCHEDULE_NOT_FOUND"] = "ORBYT-SCH-005";
33
+ })(SchedulerErrorCode || (SchedulerErrorCode = {}));
34
+ /**
35
+ * Scheduler Error class
36
+ */
37
+ export class SchedulerError extends OrbytError {
38
+ scheduleId;
39
+ cronExpression;
40
+ constructor(params) {
41
+ super({
42
+ code: params.code,
43
+ message: params.message,
44
+ exitCode: params.exitCode || SchedulerError.getExitCode(params.code),
45
+ severity: SchedulerError.determineSeverity(params.code),
46
+ context: {
47
+ scheduleId: params.scheduleId,
48
+ cronExpression: params.cronExpression,
49
+ causeMessage: params.cause?.message,
50
+ ...params.context,
51
+ },
52
+ hint: params.hint,
53
+ });
54
+ this.scheduleId = params.scheduleId;
55
+ this.cronExpression = params.cronExpression;
56
+ }
57
+ /**
58
+ * Determine exit code based on scheduler error code
59
+ */
60
+ static getExitCode(code) {
61
+ switch (code) {
62
+ case SchedulerErrorCode.INVALID_CRON_EXPRESSION:
63
+ return ExitCodes.VALIDATION_FAILED;
64
+ case SchedulerErrorCode.SCHEDULE_NOT_FOUND:
65
+ return ExitCodes.MISSING_CONFIG;
66
+ case SchedulerErrorCode.SCHEDULE_CONFLICT:
67
+ return ExitCodes.VALIDATION_FAILED;
68
+ default:
69
+ return ExitCodes.INTERNAL_ERROR;
70
+ }
71
+ }
72
+ /**
73
+ * Determine severity based on error code
74
+ */
75
+ static determineSeverity(code) {
76
+ switch (code) {
77
+ case SchedulerErrorCode.INVALID_CRON_EXPRESSION:
78
+ case SchedulerErrorCode.SCHEDULE_NOT_FOUND:
79
+ return ErrorSeverity.ERROR;
80
+ case SchedulerErrorCode.SCHEDULER_NOT_INITIALIZED:
81
+ case SchedulerErrorCode.WORKFLOW_SCHEDULE_FAILED:
82
+ return ErrorSeverity.ERROR;
83
+ case SchedulerErrorCode.SCHEDULE_CONFLICT:
84
+ return ErrorSeverity.WARNING;
85
+ default:
86
+ return ErrorSeverity.ERROR;
87
+ }
88
+ }
89
+ /**
90
+ * Factory: Invalid cron expression
91
+ */
92
+ static invalidCronExpression(expression, reason) {
93
+ return new SchedulerError({
94
+ code: SchedulerErrorCode.INVALID_CRON_EXPRESSION,
95
+ message: `Invalid cron expression: "${expression}"${reason ? ` - ${reason}` : ''}`,
96
+ cronExpression: expression,
97
+ hint: 'Cron expression must follow standard cron syntax: "minute hour day month weekday"',
98
+ });
99
+ }
100
+ /**
101
+ * Factory: Schedule conflict
102
+ */
103
+ static scheduleConflict(scheduleId, workflowPath) {
104
+ return new SchedulerError({
105
+ code: SchedulerErrorCode.SCHEDULE_CONFLICT,
106
+ message: `Schedule conflict for workflow: ${workflowPath}`,
107
+ scheduleId,
108
+ context: { workflowPath },
109
+ hint: 'A workflow with the same schedule ID already exists. Use a different ID or remove the existing schedule.',
110
+ });
111
+ }
112
+ /**
113
+ * Factory: Scheduler not initialized
114
+ */
115
+ static notInitialized() {
116
+ return new SchedulerError({
117
+ code: SchedulerErrorCode.SCHEDULER_NOT_INITIALIZED,
118
+ message: 'Workflow scheduler is not initialized',
119
+ hint: 'Enable the scheduler in engine configuration: { enableScheduler: true }',
120
+ });
121
+ }
122
+ /**
123
+ * Factory: Workflow scheduling failed
124
+ */
125
+ static schedulingFailed(workflowPath, cause) {
126
+ return new SchedulerError({
127
+ code: SchedulerErrorCode.WORKFLOW_SCHEDULE_FAILED,
128
+ message: `Failed to schedule workflow: ${workflowPath}`,
129
+ context: { workflowPath },
130
+ cause,
131
+ hint: 'Check the workflow definition and cron trigger configuration.',
132
+ });
133
+ }
134
+ /**
135
+ * Factory: Schedule not found
136
+ */
137
+ static notFound(scheduleId) {
138
+ return new SchedulerError({
139
+ code: SchedulerErrorCode.SCHEDULE_NOT_FOUND,
140
+ message: `Schedule not found: ${scheduleId}`,
141
+ scheduleId,
142
+ hint: 'Verify that the schedule ID is correct and the schedule exists.',
143
+ });
144
+ }
145
+ }
2
146
  //# sourceMappingURL=SchedulerError.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"SchedulerError.js","sourceRoot":"","sources":["../../src/errors/SchedulerError.ts"],"names":[],"mappings":""}
1
+ {"version":3,"file":"SchedulerError.js","sourceRoot":"","sources":["../../src/errors/SchedulerError.ts"],"names":[],"mappings":"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"}
@@ -1,11 +1,36 @@
1
1
  /**
2
2
  * Security Error System
3
3
  *
4
- * Structured errors for security violations.
5
- * These errors are thrown when users attempt to manipulate engine-controlled fields.
4
+ * Structured errors for security violations in workflows.
5
+ * These errors are thrown when users attempt to:
6
+ * - Manipulate engine-controlled fields
7
+ * - Use reserved field names/annotations
8
+ * - Override billing, execution, or identity fields
9
+ * - Bypass security boundaries
10
+ *
11
+ * CRITICAL: Security errors indicate attempts to compromise:
12
+ * - Billing integrity and usage tracking
13
+ * - Audit trails and compliance
14
+ * - Execution identity and ownership
15
+ * - Security boundaries
16
+ *
17
+ * USAGE:
18
+ * =====
19
+ * Use factory methods for creating security errors:
20
+ *
21
+ * ```typescript
22
+ * // ❌ Bad: Generic error
23
+ * throw new Error('Reserved field');
24
+ *
25
+ * // ✅ Good: Structured security error
26
+ * throw SecurityError.reservedFieldOverride('_internal', 'workflow.context');
27
+ * ```
6
28
  *
7
29
  * @module errors/security
8
30
  */
31
+ import { ExitCodes } from '@dev-ecosystem/core';
32
+ import { OrbytError, type OrbytErrorDiagnostic } from './OrbytError.js';
33
+ import { OrbytErrorCode, ErrorSeverity } from './ErrorCodes.js';
9
34
  /**
10
35
  * Security error codes
11
36
  */
@@ -26,7 +51,8 @@ export declare enum SecurityErrorCode {
26
51
  RESERVED_ANNOTATION_NAMESPACE = "ENGINE_RESERVED_ANNOTATION_NAMESPACE"
27
52
  }
28
53
  /**
29
- * Security violation details
54
+ * Security violation details (legacy format for backward compatibility)
55
+ * @deprecated Use SecurityError factory methods instead
30
56
  */
31
57
  export interface SecurityViolationDetails {
32
58
  /** Error code for programmatic handling */
@@ -46,30 +72,86 @@ export interface SecurityViolationDetails {
46
72
  * Security Error
47
73
  *
48
74
  * Thrown when users attempt to manipulate engine-controlled fields.
49
- * This is a CRITICAL error that must never be silently ignored.
75
+ * Extends OrbytError to provide consistent error handling with proper exit codes.
76
+ *
77
+ * CRITICAL: Security violations indicate attempts to compromise:
78
+ * - Billing integrity → Manipulating usage tracking
79
+ * - Audit compliance → Hiding execution traces
80
+ * - System security → Bypassing access controls
50
81
  */
51
- export declare class SecurityError extends Error {
52
- readonly code: SecurityErrorCode;
53
- readonly violations: SecurityViolationDetails[];
54
- readonly isEngineError = true;
55
- constructor(violations: SecurityViolationDetails[]);
82
+ export declare class SecurityError extends OrbytError {
83
+ readonly violations?: SecurityViolationDetails[];
84
+ constructor(diagnostic: OrbytErrorDiagnostic | SecurityViolationDetails[]);
56
85
  /**
57
86
  * Format violations into a clear, actionable error message
58
87
  */
59
88
  private static formatViolations;
89
+ /**
90
+ * Create reserved field override error
91
+ *
92
+ * @param field - Reserved field name that was attempted
93
+ * @param path - Path where field was found
94
+ * @param fieldType - Type of reserved field (e.g., 'billing', 'execution', 'internal')
95
+ * @returns SecurityError for reserved field violation
96
+ */
97
+ static reservedFieldOverride(field: string, path: string, fieldType?: 'billing' | 'execution' | 'identity' | 'ownership' | 'usage' | 'internal'): SecurityError;
98
+ /**
99
+ * Create reserved annotation namespace error
100
+ *
101
+ * @param annotation - Annotation key that uses reserved namespace
102
+ * @param path - Path where annotation was found
103
+ * @returns SecurityError for reserved annotation usage
104
+ */
105
+ static reservedAnnotation(annotation: string, path: string): SecurityError;
106
+ /**
107
+ * Create field manipulation detected error
108
+ *
109
+ * @param fields - Array of protected fields that were attempted
110
+ * @param path - Path where manipulation was detected
111
+ * @returns SecurityError with multiple violations
112
+ */
113
+ static fieldManipulationDetected(fields: Array<{
114
+ field: string;
115
+ reason: string;
116
+ }>, path: string): SecurityError;
117
+ /**
118
+ * Create permission denied error
119
+ *
120
+ * @param resource - Resource that was attempted to access
121
+ * @param path - Path where access was attempted
122
+ * @param requiredPermission - Required permission that was missing (optional)
123
+ * @returns SecurityError for insufficient permissions
124
+ */
125
+ static permissionDenied(resource: string, path: string, requiredPermission?: string): SecurityError;
60
126
  /**
61
127
  * Convert to JSON for API responses
62
128
  */
63
129
  toJSON(): {
64
130
  error: string;
65
- code: SecurityErrorCode;
131
+ code: OrbytErrorCode;
66
132
  message: string;
67
- violations: SecurityViolationDetails[];
68
- isEngineError: boolean;
133
+ exitCode: ExitCodes;
134
+ hint: string | undefined;
135
+ violations: SecurityViolationDetails[] | undefined;
136
+ severity: ErrorSeverity;
137
+ context: Record<string, any> | undefined;
69
138
  };
70
139
  }
71
140
  /**
72
141
  * Create a security error for reserved field violations
142
+ *
143
+ * @deprecated Use SecurityError.reservedFieldOverride() or other factory methods instead
144
+ * @param violations - Array of security violation details
145
+ * @returns SecurityError instance
146
+ *
147
+ * @example
148
+ * ```typescript
149
+ * // Old way (legacy):
150
+ * const error = createSecurityError([{ field: '_internal', ... }]);
151
+ *
152
+ * // New way (preferred):
153
+ * const error = SecurityError.reservedFieldOverride('_internal', 'workflow.context');
154
+ * ```
73
155
  */
74
156
  export declare function createSecurityError(violations: SecurityViolationDetails[]): SecurityError;
75
157
  //# sourceMappingURL=SecurityErrors.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"SecurityErrors.d.ts","sourceRoot":"","sources":["../../src/errors/SecurityErrors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,kDAAkD;IAClD,uBAAuB,mCAAmC;IAE1D,mDAAmD;IACnD,sBAAsB,kCAAkC;IAExD,sDAAsD;IACtD,uBAAuB,mCAAmC;IAE1D,6CAA6C;IAC7C,wBAAwB,oCAAoC;IAE5D,iDAAiD;IACjD,sBAAsB,kCAAkC;IAExD,kDAAkD;IAClD,uBAAuB,mCAAmC;IAE1D,0DAA0D;IAC1D,6BAA6B,yCAAyC;CACvE;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,IAAI,EAAE,iBAAiB,CAAC;IAExB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IAEjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IAEd,kDAAkD;IAClD,cAAc,CAAC,EAAE,GAAG,CAAC;IAErB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf,oBAAoB;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAgB,IAAI,EAAE,iBAAiB,CAAC;IACxC,SAAgB,UAAU,EAAE,wBAAwB,EAAE,CAAC;IACvD,SAAgB,aAAa,QAAQ;gBAEzB,UAAU,EAAE,wBAAwB,EAAE;IAclD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IA6E/B;;OAEG;IACH,MAAM;;;;;;;CASP;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,wBAAwB,EAAE,GAAG,aAAa,CAEzF"}
1
+ {"version":3,"file":"SecurityErrors.d.ts","sourceRoot":"","sources":["../../src/errors/SecurityErrors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,kDAAkD;IAClD,uBAAuB,mCAAmC;IAE1D,mDAAmD;IACnD,sBAAsB,kCAAkC;IAExD,sDAAsD;IACtD,uBAAuB,mCAAmC;IAE1D,6CAA6C;IAC7C,wBAAwB,oCAAoC;IAE5D,iDAAiD;IACjD,sBAAsB,kCAAkC;IAExD,kDAAkD;IAClD,uBAAuB,mCAAmC;IAE1D,0DAA0D;IAC1D,6BAA6B,yCAAyC;CACvE;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,IAAI,EAAE,iBAAiB,CAAC;IAExB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IAEjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IAEd,kDAAkD;IAClD,cAAc,CAAC,EAAE,GAAG,CAAC;IAErB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf,oBAAoB;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,SAAgB,UAAU,CAAC,EAAE,wBAAwB,EAAE,CAAC;gBAE5C,UAAU,EAAE,oBAAoB,GAAG,wBAAwB,EAAE;IAwBzE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IA+E/B;;;;;;;OAOG;IACH,MAAM,CAAC,qBAAqB,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,GAAG,UAAuB,GAChG,aAAa;IAqBhB;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,aAAa;IAYhB;;;;;;OAMG;IACH,MAAM,CAAC,yBAAyB,CAC9B,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAChD,IAAI,EAAE,MAAM,GACX,aAAa;IAahB;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,kBAAkB,CAAC,EAAE,MAAM,GAC1B,aAAa;IAgBhB;;OAEG;IACH,MAAM;;;;;;;;;;CAYP;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,wBAAwB,EAAE,GAAG,aAAa,CAEzF"}