@kjanat/dreamcli 0.0.0 → 1.0.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 (101) hide show
  1. package/CHANGELOG.md +667 -0
  2. package/LICENSE +22 -0
  3. package/README.md +370 -0
  4. package/dist/adapter-B37d9oia.mjs +1 -0
  5. package/dist/adapter-CCSh5juX.cjs +1 -0
  6. package/dist/adapter-DIwO-q7K.d.mts +3447 -0
  7. package/dist/adapter-DQnxxLiE.d.cts +3447 -0
  8. package/dist/auto-5cjZaF9V.mjs +3 -0
  9. package/dist/auto-B0eSgoDw.cjs +3 -0
  10. package/dist/index.cjs +10 -0
  11. package/dist/index.d.cts +920 -0
  12. package/dist/index.d.mts +920 -0
  13. package/dist/index.mjs +10 -0
  14. package/dist/runtime.cjs +1 -0
  15. package/dist/runtime.d.cts +253 -0
  16. package/dist/runtime.d.mts +253 -0
  17. package/dist/runtime.mjs +1 -0
  18. package/dist/testkit-CEDYPvhF.mjs +14 -0
  19. package/dist/testkit-ClIKijxC.cjs +14 -0
  20. package/dist/testkit.cjs +1 -0
  21. package/dist/testkit.d.cts +25 -0
  22. package/dist/testkit.d.mts +25 -0
  23. package/dist/testkit.mjs +1 -0
  24. package/examples/basic.ts +33 -0
  25. package/examples/gh/package.json +48 -0
  26. package/examples/gh/src/commands/auth.ts +66 -0
  27. package/examples/gh/src/commands/issue.ts +120 -0
  28. package/examples/gh/src/commands/pr.ts +125 -0
  29. package/examples/gh/src/data/issues.yaml +5 -0
  30. package/examples/gh/src/data/issues.yaml.d.ts +17 -0
  31. package/examples/gh/src/data/pull-requests.yaml +7 -0
  32. package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
  33. package/examples/gh/src/lib/auth.ts +37 -0
  34. package/examples/gh/src/lib/utils.ts +17 -0
  35. package/examples/gh/src/main.test.ts +306 -0
  36. package/examples/gh/src/main.ts +38 -0
  37. package/examples/gh/tsconfig.json +37 -0
  38. package/examples/interactive.ts +66 -0
  39. package/examples/json-mode.ts +93 -0
  40. package/examples/middleware.ts +71 -0
  41. package/examples/multi-command.ts +66 -0
  42. package/examples/spinner-progress.ts +49 -0
  43. package/examples/testing.ts +145 -0
  44. package/examples/tsconfig.json +17 -0
  45. package/package.json +123 -2
  46. package/src/core/cli/AGENTS.md +72 -0
  47. package/src/core/cli/dispatch.ts +282 -0
  48. package/src/core/cli/index.ts +1425 -0
  49. package/src/core/cli/plugin.ts +111 -0
  50. package/src/core/cli/propagate.ts +97 -0
  51. package/src/core/cli/root-help.ts +269 -0
  52. package/src/core/cli/root-surface.ts +74 -0
  53. package/src/core/completion/AGENTS.md +72 -0
  54. package/src/core/completion/completion-test-helpers.ts +48 -0
  55. package/src/core/completion/index.ts +82 -0
  56. package/src/core/completion/shells/bash.ts +456 -0
  57. package/src/core/completion/shells/fish.ts +24 -0
  58. package/src/core/completion/shells/powershell.ts +24 -0
  59. package/src/core/completion/shells/shared.ts +283 -0
  60. package/src/core/completion/shells/zsh.ts +376 -0
  61. package/src/core/config/index.ts +404 -0
  62. package/src/core/config/package-json.ts +216 -0
  63. package/src/core/errors/index.ts +178 -0
  64. package/src/core/help/index.ts +559 -0
  65. package/src/core/json-schema/index.ts +705 -0
  66. package/src/core/output/AGENTS.md +69 -0
  67. package/src/core/output/activity.ts +568 -0
  68. package/src/core/output/display-value.ts +48 -0
  69. package/src/core/output/index.ts +704 -0
  70. package/src/core/output/writer.ts +46 -0
  71. package/src/core/parse/index.ts +643 -0
  72. package/src/core/prompt/index.ts +566 -0
  73. package/src/core/resolve/AGENTS.md +69 -0
  74. package/src/core/resolve/index.ts +1331 -0
  75. package/src/core/schema/AGENTS.md +61 -0
  76. package/src/core/schema/activity.ts +237 -0
  77. package/src/core/schema/arg.ts +707 -0
  78. package/src/core/schema/command.ts +1263 -0
  79. package/src/core/schema/flag.ts +651 -0
  80. package/src/core/schema/index.ts +82 -0
  81. package/src/core/schema/middleware.ts +171 -0
  82. package/src/core/schema/prompt.ts +148 -0
  83. package/src/core/schema/run.ts +187 -0
  84. package/src/core/testkit/AGENTS.md +55 -0
  85. package/src/core/testkit/index.ts +365 -0
  86. package/src/index.ts +164 -0
  87. package/src/runtime/AGENTS.md +74 -0
  88. package/src/runtime/adapter.ts +300 -0
  89. package/src/runtime/auto.ts +110 -0
  90. package/src/runtime/bun.ts +55 -0
  91. package/src/runtime/deno.ts +355 -0
  92. package/src/runtime/detect.ts +102 -0
  93. package/src/runtime/index.ts +21 -0
  94. package/src/runtime/node-builtins.d.ts +23 -0
  95. package/src/runtime/node.ts +278 -0
  96. package/src/runtime/paths.ts +56 -0
  97. package/src/runtime/support.ts +119 -0
  98. package/src/runtime/test-helpers.ts +40 -0
  99. package/src/runtime.ts +31 -0
  100. package/src/testkit.ts +23 -0
  101. package/src/version.ts +20 -0
@@ -0,0 +1,178 @@
1
+ /**
2
+ * Structured error types for DreamCLI.
3
+ *
4
+ * Base `CLIError` carries stable code, exit code, suggestion, and structured
5
+ * details. `ParseError` and `ValidationError` derive from it with
6
+ * category-appropriate defaults.
7
+ *
8
+ * @module dreamcli/core/errors
9
+ */
10
+
11
+ // --- Error codes — discriminated string union per category
12
+
13
+ /** Codes emitted during argv parsing. */
14
+ export type ParseErrorCode =
15
+ | 'UNKNOWN_FLAG'
16
+ | 'UNKNOWN_COMMAND'
17
+ | 'MISSING_VALUE'
18
+ | 'INVALID_VALUE'
19
+ | 'INVALID_SCHEMA'
20
+ | 'UNEXPECTED_POSITIONAL';
21
+
22
+ /** Codes emitted during post-parse validation / resolution. */
23
+ export type ValidationErrorCode =
24
+ | 'REQUIRED_FLAG'
25
+ | 'REQUIRED_ARG'
26
+ | 'INVALID_ENUM'
27
+ | 'TYPE_MISMATCH'
28
+ | 'CONSTRAINT_VIOLATED';
29
+
30
+ /** Any framework error code (extensible via `string & {}`). */
31
+ // deno-lint-ignore ban-types
32
+ export type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
33
+
34
+ // --- Options bag for CLIError construction
35
+
36
+ /** Options accepted by the `CLIError` constructor. */
37
+ export interface CLIErrorOptions {
38
+ /** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
39
+ readonly code: ErrorCode;
40
+ /**
41
+ * Process exit code.
42
+ * @defaultValue `1`
43
+ */
44
+ readonly exitCode?: number;
45
+ /** One-liner actionable hint shown to the user. */
46
+ readonly suggest?: string;
47
+ /** Arbitrary structured payload (serialised in `--json` mode). */
48
+ readonly details?: Readonly<Record<string, unknown>>;
49
+ /** Original error, if this wraps another. */
50
+ readonly cause?: unknown;
51
+ }
52
+
53
+ // --- CLIError — base structured error
54
+
55
+ /**
56
+ * Base structured error for DreamCLI.
57
+ *
58
+ * Every error surfaced by the framework extends this class, ensuring a
59
+ * consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
60
+ */
61
+ export class CLIError extends Error {
62
+ /** @override */
63
+ override readonly name: string = 'CLIError';
64
+
65
+ /** Stable machine-readable identifier. */
66
+ readonly code: ErrorCode;
67
+
68
+ /** Process exit code (defaults to `1`). */
69
+ readonly exitCode: number;
70
+
71
+ /** One-liner actionable hint. */
72
+ readonly suggest: string | undefined;
73
+
74
+ /** Structured payload for machine output. */
75
+ readonly details: Readonly<Record<string, unknown>> | undefined;
76
+
77
+ constructor(message: string, options: CLIErrorOptions) {
78
+ super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
79
+ this.code = options.code;
80
+ this.exitCode = options.exitCode ?? 1;
81
+ this.suggest = options.suggest;
82
+ this.details = options.details;
83
+ }
84
+
85
+ /**
86
+ * Serialise to a plain object suitable for JSON output.
87
+ * @sealed
88
+ */
89
+ toJSON(): CLIErrorJSON {
90
+ return {
91
+ name: this.name,
92
+ code: this.code,
93
+ message: this.message,
94
+ exitCode: this.exitCode,
95
+ ...(this.suggest !== undefined && { suggest: this.suggest }),
96
+ ...(this.details !== undefined && { details: this.details }),
97
+ };
98
+ }
99
+ }
100
+
101
+ /** Shape returned by `CLIError.toJSON()`. */
102
+ export interface CLIErrorJSON {
103
+ readonly name: string;
104
+ readonly code: ErrorCode;
105
+ readonly message: string;
106
+ readonly exitCode: number;
107
+ readonly suggest?: string;
108
+ readonly details?: Readonly<Record<string, unknown>>;
109
+ }
110
+
111
+ // --- ParseError — argv parsing failures
112
+
113
+ /** Options for `ParseError`. Code is narrowed to parse-specific codes. */
114
+ export interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
115
+ readonly code: ParseErrorCode;
116
+ /**
117
+ * @defaultValue `2`
118
+ */
119
+ readonly exitCode?: number;
120
+ }
121
+
122
+ /**
123
+ * Error thrown when argv tokenization / parsing fails.
124
+ *
125
+ * Exit code defaults to `2` (standard for CLI usage errors).
126
+ */
127
+ export class ParseError extends CLIError {
128
+ /** @override */
129
+ override readonly name = 'ParseError' as const;
130
+ declare readonly code: ParseErrorCode;
131
+
132
+ constructor(message: string, options: ParseErrorOptions) {
133
+ super(message, { ...options, exitCode: options.exitCode ?? 2 });
134
+ }
135
+ }
136
+
137
+ // --- ValidationError — post-parse validation / resolution failures
138
+
139
+ /** Options for `ValidationError`. Code is narrowed to validation-specific codes. */
140
+ export interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
141
+ readonly code: ValidationErrorCode;
142
+ /**
143
+ * @defaultValue `2`
144
+ */
145
+ readonly exitCode?: number;
146
+ }
147
+
148
+ /**
149
+ * Error thrown when resolved values fail validation constraints.
150
+ *
151
+ * Exit code defaults to `2` (standard for CLI usage errors).
152
+ */
153
+ export class ValidationError extends CLIError {
154
+ /** @override */
155
+ override readonly name = 'ValidationError' as const;
156
+ declare readonly code: ValidationErrorCode;
157
+
158
+ constructor(message: string, options: ValidationErrorOptions) {
159
+ super(message, { ...options, exitCode: options.exitCode ?? 2 });
160
+ }
161
+ }
162
+
163
+ // --- Type guard utilities
164
+
165
+ /** Narrows an unknown value to `CLIError`. */
166
+ export function isCLIError(value: unknown): value is CLIError {
167
+ return value instanceof CLIError;
168
+ }
169
+
170
+ /** Narrows an unknown value to `ParseError`. */
171
+ export function isParseError(value: unknown): value is ParseError {
172
+ return value instanceof ParseError;
173
+ }
174
+
175
+ /** Narrows an unknown value to `ValidationError`. */
176
+ export function isValidationError(value: unknown): value is ValidationError {
177
+ return value instanceof ValidationError;
178
+ }