@dual-os/cli 0.0.0-stage → 0.11.0-next.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 (254) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +15 -2
  3. package/dist/_virtual/_rolldown/runtime.js +13 -0
  4. package/dist/auth/credentials.d.ts +17 -0
  5. package/dist/auth/credentials.d.ts.map +1 -0
  6. package/dist/auth/credentials.js +57 -0
  7. package/dist/auth/credentials.js.map +1 -0
  8. package/dist/auth/destination.d.ts +22 -0
  9. package/dist/auth/destination.d.ts.map +1 -0
  10. package/dist/auth/destination.js +49 -0
  11. package/dist/auth/destination.js.map +1 -0
  12. package/dist/auth/http.d.ts +12 -0
  13. package/dist/auth/http.d.ts.map +1 -0
  14. package/dist/auth/http.js +34 -0
  15. package/dist/auth/http.js.map +1 -0
  16. package/dist/auth/login.d.ts +22 -0
  17. package/dist/auth/login.d.ts.map +1 -0
  18. package/dist/auth/login.js +98 -0
  19. package/dist/auth/login.js.map +1 -0
  20. package/dist/auth/protocol.d.ts +26 -0
  21. package/dist/auth/protocol.d.ts.map +1 -0
  22. package/dist/auth/protocol.js +31 -0
  23. package/dist/auth/protocol.js.map +1 -0
  24. package/dist/baseline.d.ts +18 -0
  25. package/dist/baseline.d.ts.map +1 -0
  26. package/dist/baseline.js +22 -0
  27. package/dist/baseline.js.map +1 -0
  28. package/dist/bin.d.ts +1 -0
  29. package/dist/bin.js +7 -0
  30. package/dist/bin.js.map +1 -0
  31. package/dist/cli.d.ts +19 -0
  32. package/dist/cli.d.ts.map +1 -0
  33. package/dist/cli.js +492 -0
  34. package/dist/cli.js.map +1 -0
  35. package/dist/create/choices.d.ts +58 -0
  36. package/dist/create/choices.d.ts.map +1 -0
  37. package/dist/create/choices.js +121 -0
  38. package/dist/create/choices.js.map +1 -0
  39. package/dist/create/deployment.d.ts +48 -0
  40. package/dist/create/deployment.d.ts.map +1 -0
  41. package/dist/create/deployment.js +66 -0
  42. package/dist/create/deployment.js.map +1 -0
  43. package/dist/create/scaffold.d.ts +57 -0
  44. package/dist/create/scaffold.d.ts.map +1 -0
  45. package/dist/create/scaffold.js +198 -0
  46. package/dist/create/scaffold.js.map +1 -0
  47. package/dist/create/source-reference.d.ts +39 -0
  48. package/dist/create/source-reference.d.ts.map +1 -0
  49. package/dist/create/source-reference.js +185 -0
  50. package/dist/create/source-reference.js.map +1 -0
  51. package/dist/create/template.d.ts +116 -0
  52. package/dist/create/template.d.ts.map +1 -0
  53. package/dist/create/template.js +211 -0
  54. package/dist/create/template.js.map +1 -0
  55. package/dist/diagnostics.d.ts +6 -0
  56. package/dist/diagnostics.d.ts.map +1 -0
  57. package/dist/diagnostics.js +18 -0
  58. package/dist/diagnostics.js.map +1 -0
  59. package/dist/help.d.ts +16 -0
  60. package/dist/help.d.ts.map +1 -0
  61. package/dist/help.js +73 -0
  62. package/dist/help.js.map +1 -0
  63. package/dist/openapi/bundle.d.ts +18 -0
  64. package/dist/openapi/bundle.d.ts.map +1 -0
  65. package/dist/openapi/bundle.js +201 -0
  66. package/dist/openapi/bundle.js.map +1 -0
  67. package/dist/openapi/discovery.d.ts +30 -0
  68. package/dist/openapi/discovery.d.ts.map +1 -0
  69. package/dist/openapi/discovery.js +325 -0
  70. package/dist/openapi/discovery.js.map +1 -0
  71. package/dist/openapi/emit.d.ts +52 -0
  72. package/dist/openapi/emit.d.ts.map +1 -0
  73. package/dist/openapi/emit.js +596 -0
  74. package/dist/openapi/emit.js.map +1 -0
  75. package/dist/openapi/graphql.d.ts +102 -0
  76. package/dist/openapi/graphql.d.ts.map +1 -0
  77. package/dist/openapi/graphql.js +294 -0
  78. package/dist/openapi/graphql.js.map +1 -0
  79. package/dist/openapi/identity.d.ts +88 -0
  80. package/dist/openapi/identity.d.ts.map +1 -0
  81. package/dist/openapi/identity.js +98 -0
  82. package/dist/openapi/identity.js.map +1 -0
  83. package/dist/openapi/mcp.d.ts +21 -0
  84. package/dist/openapi/mcp.d.ts.map +1 -0
  85. package/dist/openapi/mcp.js +133 -0
  86. package/dist/openapi/mcp.js.map +1 -0
  87. package/dist/openapi/operations.d.ts +165 -0
  88. package/dist/openapi/operations.d.ts.map +1 -0
  89. package/dist/openapi/operations.js +361 -0
  90. package/dist/openapi/operations.js.map +1 -0
  91. package/dist/openapi/overlay.d.ts +23 -0
  92. package/dist/openapi/overlay.d.ts.map +1 -0
  93. package/dist/openapi/overlay.js +115 -0
  94. package/dist/openapi/overlay.js.map +1 -0
  95. package/dist/openapi/plugin.d.ts +83 -0
  96. package/dist/openapi/plugin.d.ts.map +1 -0
  97. package/dist/openapi/plugin.js +468 -0
  98. package/dist/openapi/plugin.js.map +1 -0
  99. package/dist/openapi/polymorphism.d.ts +21 -0
  100. package/dist/openapi/polymorphism.d.ts.map +1 -0
  101. package/dist/openapi/polymorphism.js +96 -0
  102. package/dist/openapi/polymorphism.js.map +1 -0
  103. package/dist/openapi/postman.d.ts +21 -0
  104. package/dist/openapi/postman.d.ts.map +1 -0
  105. package/dist/openapi/postman.js +286 -0
  106. package/dist/openapi/postman.js.map +1 -0
  107. package/dist/openapi/schema.d.ts +178 -0
  108. package/dist/openapi/schema.d.ts.map +1 -0
  109. package/dist/openapi/schema.js +1234 -0
  110. package/dist/openapi/schema.js.map +1 -0
  111. package/dist/openapi/select.d.ts +22 -0
  112. package/dist/openapi/select.d.ts.map +1 -0
  113. package/dist/openapi/select.js +79 -0
  114. package/dist/openapi/select.js.map +1 -0
  115. package/dist/openapi/spec.d.ts +147 -0
  116. package/dist/openapi/spec.d.ts.map +1 -0
  117. package/dist/openapi/spec.js +263 -0
  118. package/dist/openapi/spec.js.map +1 -0
  119. package/dist/openapi/swagger.d.ts +166 -0
  120. package/dist/openapi/swagger.d.ts.map +1 -0
  121. package/dist/openapi/swagger.js +298 -0
  122. package/dist/openapi/swagger.js.map +1 -0
  123. package/dist/openapi/versions.d.ts +52 -0
  124. package/dist/openapi/versions.d.ts.map +1 -0
  125. package/dist/openapi/versions.js +120 -0
  126. package/dist/openapi/versions.js.map +1 -0
  127. package/dist/plugin/archive.d.ts +27 -0
  128. package/dist/plugin/archive.d.ts.map +1 -0
  129. package/dist/plugin/archive.js +170 -0
  130. package/dist/plugin/archive.js.map +1 -0
  131. package/dist/plugin/bundle.d.ts +27 -0
  132. package/dist/plugin/bundle.d.ts.map +1 -0
  133. package/dist/plugin/bundle.js +328 -0
  134. package/dist/plugin/bundle.js.map +1 -0
  135. package/dist/plugin/init.d.ts +18 -0
  136. package/dist/plugin/init.d.ts.map +1 -0
  137. package/dist/plugin/init.js +121 -0
  138. package/dist/plugin/init.js.map +1 -0
  139. package/dist/plugin/inspection.d.ts +24 -0
  140. package/dist/plugin/inspection.d.ts.map +1 -0
  141. package/dist/plugin/inspection.js +24 -0
  142. package/dist/plugin/inspection.js.map +1 -0
  143. package/dist/plugin/package.d.ts +26 -0
  144. package/dist/plugin/package.d.ts.map +1 -0
  145. package/dist/plugin/package.js +73 -0
  146. package/dist/plugin/package.js.map +1 -0
  147. package/dist/plugin/publication.d.ts +29 -0
  148. package/dist/plugin/publication.d.ts.map +1 -0
  149. package/dist/plugin/publication.js +65 -0
  150. package/dist/plugin/publication.js.map +1 -0
  151. package/dist/plugin/validation.d.ts +15 -0
  152. package/dist/plugin/validation.d.ts.map +1 -0
  153. package/dist/plugin/validation.js +119 -0
  154. package/dist/plugin/validation.js.map +1 -0
  155. package/dist/release/archives.d.ts +33 -0
  156. package/dist/release/archives.d.ts.map +1 -0
  157. package/dist/release/archives.js +81 -0
  158. package/dist/release/archives.js.map +1 -0
  159. package/dist/release/release-manifest.d.ts +182 -0
  160. package/dist/release/release-manifest.d.ts.map +1 -0
  161. package/dist/release/release-manifest.js +79 -0
  162. package/dist/release/release-manifest.js.map +1 -0
  163. package/dist/release/releases.d.ts +36 -0
  164. package/dist/release/releases.d.ts.map +1 -0
  165. package/dist/release/releases.js +122 -0
  166. package/dist/release/releases.js.map +1 -0
  167. package/dist/skills.d.ts +35 -0
  168. package/dist/skills.d.ts.map +1 -0
  169. package/dist/skills.js +257 -0
  170. package/dist/skills.js.map +1 -0
  171. package/package.json +73 -4
  172. package/skills/dual-fde/SKILL.md +38 -0
  173. package/skills/dual-fde/references/access.md +62 -0
  174. package/skills/dual-fde/references/author-plugins.md +54 -0
  175. package/skills/dual-fde/references/cli.md +97 -0
  176. package/skills/dual-fde/references/manage-plugins.md +78 -0
  177. package/skills/dual-fde/references/migrations-deployment.md +84 -0
  178. package/skills/dual-fde/references/openapi-plugins.md +47 -0
  179. package/skills/dual-fde/references/sdk-docs.md +56 -0
  180. package/skills/dual-fde/references/upgrades.md +115 -0
  181. package/skills/dual-fde/references/working-context.md +69 -0
  182. package/src/auth/credentials.ts +84 -0
  183. package/src/auth/destination.ts +83 -0
  184. package/src/auth/http.ts +39 -0
  185. package/src/auth/login.ts +177 -0
  186. package/src/auth/protocol.ts +37 -0
  187. package/src/baseline.ts +15 -0
  188. package/src/bin.ts +4 -0
  189. package/src/cli.ts +969 -0
  190. package/src/create/choices.ts +177 -0
  191. package/src/create/deployment.ts +96 -0
  192. package/src/create/scaffold.ts +334 -0
  193. package/src/create/source-reference.ts +212 -0
  194. package/src/create/template.ts +300 -0
  195. package/src/diagnostics.ts +8 -0
  196. package/src/help.ts +142 -0
  197. package/src/openapi/bundle.ts +290 -0
  198. package/src/openapi/discovery.ts +438 -0
  199. package/src/openapi/emit.ts +1031 -0
  200. package/src/openapi/graphql.ts +375 -0
  201. package/src/openapi/identity.ts +153 -0
  202. package/src/openapi/mcp.ts +165 -0
  203. package/src/openapi/operations.ts +781 -0
  204. package/src/openapi/overlay.ts +195 -0
  205. package/src/openapi/plugin.ts +856 -0
  206. package/src/openapi/polymorphism.ts +207 -0
  207. package/src/openapi/postman.ts +403 -0
  208. package/src/openapi/schema.ts +2138 -0
  209. package/src/openapi/select.ts +113 -0
  210. package/src/openapi/spec.ts +401 -0
  211. package/src/openapi/swagger.ts +422 -0
  212. package/src/openapi/versions.ts +174 -0
  213. package/src/plugin/archive.ts +244 -0
  214. package/src/plugin/bundle.ts +572 -0
  215. package/src/plugin/init.ts +178 -0
  216. package/src/plugin/inspection.ts +19 -0
  217. package/src/plugin/package.ts +140 -0
  218. package/src/plugin/publication.ts +128 -0
  219. package/src/plugin/validation.ts +213 -0
  220. package/src/release/archives.ts +133 -0
  221. package/src/release/release-manifest.ts +79 -0
  222. package/src/release/releases.ts +210 -0
  223. package/src/skills.ts +434 -0
  224. package/templates/compose/.env.compose.example.hbs +3 -0
  225. package/templates/compose/.env.host.example.hbs +4 -0
  226. package/templates/compose/Dockerfile.hbs +12 -0
  227. package/templates/compose/OPERATIONS.md.hbs +159 -0
  228. package/templates/compose/_dockerignore +14 -0
  229. package/templates/compose/compose.external.yaml +7 -0
  230. package/templates/compose/compose.host-linux.yaml +5 -0
  231. package/templates/compose/compose.host.yaml.hbs +15 -0
  232. package/templates/compose/compose.yaml.hbs +85 -0
  233. package/templates/compose/release.env.hbs +2 -0
  234. package/templates/default/.env.example.hbs +79 -0
  235. package/templates/default/README.md.hbs +150 -0
  236. package/templates/default/_gitignore +11 -0
  237. package/templates/default/packages/customer-plugin/src/Customer.ts.hbs +17 -0
  238. package/templates/default/packages/customer-plugin/tsconfig.json +15 -0
  239. package/templates/default/packages/execution-layer/src/App.ts.hbs +7 -0
  240. package/templates/default/packages/execution-layer/src/Host.ts.hbs +31 -0
  241. package/templates/default/packages/execution-layer/src/Telemetry.ts.hbs +23 -0
  242. package/templates/default/packages/execution-layer/src/api.ts.hbs +21 -0
  243. package/templates/default/packages/execution-layer/src/bootstrap.ts +22 -0
  244. package/templates/default/packages/execution-layer/src/migrate.ts +11 -0
  245. package/templates/default/packages/execution-layer/src/registry-check.ts +29 -0
  246. package/templates/default/packages/execution-layer/src/registry-sync.ts +14 -0
  247. package/templates/default/packages/execution-layer/src/worker.ts.hbs +16 -0
  248. package/templates/default/packages/execution-layer/test/app.host-test.ts.hbs +58 -0
  249. package/templates/default/packages/execution-layer/test/app.test.ts.hbs +16 -0
  250. package/templates/default/tsconfig.json +5 -0
  251. package/templates/default/vitest.config.ts +5 -0
  252. package/templates/default/vitest.host.config.ts +6 -0
  253. package/templates/opensandbox/OPEN-SANDBOX.md +25 -0
  254. package/templates/opensandbox/docker/agent-sandbox.Dockerfile +41 -0
@@ -0,0 +1,781 @@
1
+ import {
2
+ Array,
3
+ HashMap,
4
+ HashSet,
5
+ Match,
6
+ Option,
7
+ Order,
8
+ Predicate,
9
+ Record,
10
+ Result,
11
+ Schema,
12
+ String,
13
+ identity,
14
+ pipe,
15
+ } from "effect";
16
+
17
+ import { OpenApiSchema } from "./schema.ts";
18
+ import { OpenApiSpec } from "./spec.ts";
19
+
20
+ const methods = ["delete", "get", "head", "options", "patch", "post", "put", "trace"] as const;
21
+
22
+ type Method = (typeof methods)[number];
23
+
24
+ interface Skipped {
25
+ readonly operation?: { readonly method: Method; readonly operationId: string };
26
+ readonly path: string;
27
+ readonly reason: string;
28
+ }
29
+
30
+ export interface SchemaAt {
31
+ readonly value: unknown;
32
+ readonly pointer: string;
33
+ }
34
+
35
+ export interface Parameter {
36
+ readonly name: string;
37
+ readonly location: "path" | "query" | "header";
38
+ readonly required: boolean;
39
+ readonly description?: string;
40
+ readonly schema: Option.Option<SchemaAt>;
41
+ readonly commaSeparated: boolean;
42
+ readonly deepObject: boolean;
43
+ readonly exploded?: boolean;
44
+ readonly delimiter?: "|" | " ";
45
+ }
46
+
47
+ type Encoding = "json" | "form" | "multipart" | "text" | "binary";
48
+
49
+ export interface Body {
50
+ readonly encoding: Encoding;
51
+ readonly contentType: string;
52
+ readonly deepObject?: readonly string[];
53
+ readonly joined?: readonly (string | [string, string])[];
54
+ readonly required: boolean;
55
+ readonly schema: Option.Option<SchemaAt>;
56
+ }
57
+
58
+ export interface Response {
59
+ readonly headers?: readonly string[];
60
+ readonly kind: "json" | "text" | "binary" | "void" | "unknown";
61
+ readonly schema: Option.Option<SchemaAt>;
62
+ readonly status: string;
63
+ readonly contentType: string;
64
+ }
65
+
66
+ export interface Operation {
67
+ readonly pathSegments?: readonly string[];
68
+ readonly preauthenticatedUpload?: boolean;
69
+ readonly googleDownload?: boolean;
70
+ readonly nextLink?: boolean;
71
+ readonly alias?: Alias;
72
+ readonly googleUpload?: GoogleUpload;
73
+ readonly graphql?: Graphql;
74
+ readonly mcp?: Mcp;
75
+ readonly operationId: string;
76
+ readonly deprecated: boolean;
77
+ readonly method: Method;
78
+ readonly path: string;
79
+ readonly url: string;
80
+ readonly groupId: string;
81
+ readonly actionId: string;
82
+ readonly actionName: string;
83
+ readonly description: Option.Option<string>;
84
+ readonly parameters: readonly Parameter[];
85
+ readonly bodies: readonly Body[];
86
+ readonly responses: readonly Response[];
87
+ }
88
+
89
+ export type Alias = typeof Alias.Type;
90
+ const Alias = Schema.Struct({
91
+ parameter: Schema.String,
92
+ prefix: Schema.String,
93
+ replacement: Schema.String,
94
+ });
95
+
96
+ type Graphql = typeof Graphql.Type;
97
+ const Graphql = Schema.Struct({
98
+ document: Schema.NonEmptyString,
99
+ endpoint: Schema.NonEmptyString,
100
+ field: Schema.NonEmptyString,
101
+ });
102
+
103
+ type Mcp = typeof Mcp.Type;
104
+ const Mcp = Schema.Struct({
105
+ endpoint: Schema.NonEmptyString,
106
+ structured: Schema.Boolean,
107
+ tool: Schema.NonEmptyString,
108
+ });
109
+
110
+ type GoogleUpload = typeof GoogleUpload.Type;
111
+ const GoogleUpload = Schema.Struct({
112
+ maxSize: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^\d+$/u))),
113
+ resumableUrl: Schema.optionalKey(Schema.String),
114
+ });
115
+
116
+ interface Source {
117
+ readonly spec: OpenApiSpec.Spec;
118
+ readonly specUrl?: URL;
119
+ }
120
+
121
+ interface Candidate {
122
+ readonly method: Method;
123
+ readonly path: string;
124
+ readonly item: OpenApiSpec.Located;
125
+ readonly operation: OpenApiSpec.JsonObject;
126
+ }
127
+
128
+ function isJson(media: string) {
129
+ return pipe(media, String.endsWith("/json")) || pipe(media, String.endsWith("+json"));
130
+ }
131
+
132
+ function isText(media: string) {
133
+ return (
134
+ pipe(media, String.startsWith("text/")) ||
135
+ pipe(media, String.startsWith("message/")) ||
136
+ pipe(media, String.endsWith("/xml")) ||
137
+ pipe(media, String.endsWith("+xml"))
138
+ );
139
+ }
140
+
141
+ function isFileMedia(media: string) {
142
+ return (
143
+ Array.some(["image/", "audio/", "video/", "font/"], prefix =>
144
+ pipe(media, String.startsWith(prefix)),
145
+ ) || Array.contains(["application/octet-stream", "application/pdf", "application/zip"], media)
146
+ );
147
+ }
148
+
149
+ function bodyShape(spec: OpenApiSpec.Spec, schema: Option.Option<SchemaAt>) {
150
+ const resolved = Option.getOrUndefined(
151
+ Option.map(schema, found => OpenApiSpec.resolve(spec, found.value)),
152
+ );
153
+ if (
154
+ resolved === undefined ||
155
+ resolved["format"] === "binary" ||
156
+ resolved["format"] === "byte" ||
157
+ resolved["contentEncoding"] !== undefined ||
158
+ resolved["contentMediaType"] !== undefined
159
+ ) {
160
+ return undefined;
161
+ }
162
+ const types = Array.ensure(resolved["type"] ?? []);
163
+ if (
164
+ Array.contains(types, "object") ||
165
+ Array.contains(types, "array") ||
166
+ Array.some(["properties", "items", "allOf", "oneOf", "anyOf"], keyword =>
167
+ Record.has(resolved, keyword),
168
+ )
169
+ ) {
170
+ return "json" as const;
171
+ }
172
+ if (Array.contains(types, "string")) {
173
+ return "text" as const;
174
+ }
175
+ return undefined;
176
+ }
177
+
178
+ const ignoredHeaders = ["accept", "authorization", "content-type"];
179
+
180
+ const styles = [
181
+ "deepObject",
182
+ "form",
183
+ "label",
184
+ "matrix",
185
+ "pipeDelimited",
186
+ "simple",
187
+ "spaceDelimited",
188
+ ];
189
+
190
+ function styleOf(declaration: OpenApiSpec.JsonObject) {
191
+ const declared = declaration["style"];
192
+ return Predicate.isString(declared)
193
+ ? pipe(
194
+ styles,
195
+ Array.findFirst(style => String.toLowerCase(style) === String.toLowerCase(declared)),
196
+ Option.getOrElse(() => declared),
197
+ )
198
+ : undefined;
199
+ }
200
+
201
+ function contentEntries(owner: OpenApiSpec.Located) {
202
+ return Array.map(Record.toEntries(OpenApiSpec.asObject(owner.value["content"]) ?? {}), entry => ({
203
+ deepObject: Record.keys(
204
+ Record.filter(
205
+ OpenApiSpec.asObject(OpenApiSpec.asObject(entry[1])?.["encoding"]) ?? {},
206
+ encoding => styleOf(OpenApiSpec.asObject(encoding) ?? {}) === "deepObject",
207
+ ),
208
+ ),
209
+ joined: Array.flatMap(
210
+ Record.toEntries(OpenApiSpec.asObject(OpenApiSpec.asObject(entry[1])?.["encoding"]) ?? {}),
211
+ (field): (string | [string, string])[] => {
212
+ const name = field[0];
213
+ const value = field[1];
214
+ const encoding = OpenApiSpec.asObject(value) ?? {};
215
+ if (Predicate.isString(encoding["x-dual-delimiter"])) {
216
+ return [[name, encoding["x-dual-delimiter"]]];
217
+ }
218
+ if (encoding["explode"] !== false) {
219
+ return [];
220
+ }
221
+ const style = styleOf(encoding);
222
+ if (style === "form") {
223
+ return [name];
224
+ }
225
+ if (style === "spaceDelimited") {
226
+ return [[name, " "]];
227
+ }
228
+ if (style === "pipeDelimited") {
229
+ return [[name, "|"]];
230
+ }
231
+ return [];
232
+ },
233
+ ),
234
+ media: pipe(entry[0], String.toLowerCase, String.split(";"), Array.headNonEmpty, String.trim),
235
+ schema: Option.map(
236
+ Option.fromNullishOr(OpenApiSpec.asObject(entry[1])?.schema),
237
+ (value): SchemaAt => ({
238
+ pointer: `${owner.pointer}/content/${OpenApiSpec.pointerToken(entry[0])}/schema`,
239
+ value,
240
+ }),
241
+ ),
242
+ }));
243
+ }
244
+
245
+ function segmentsOf(value: string) {
246
+ return Array.filter(pipe(value, String.split(/[./]+/u)), String.isNonEmpty);
247
+ }
248
+
249
+ const delimiters: Partial<Record<string, "|" | " ">> = { pipeDelimited: "|", spaceDelimited: " " };
250
+
251
+ function parameterFor(spec: OpenApiSpec.Spec, located: OpenApiSpec.Located) {
252
+ const declaration = located.value;
253
+ const name = declaration.name;
254
+ const location = declaration.in;
255
+ if (!Predicate.isString(name) || !Predicate.isString(location)) {
256
+ return Result.fail(`its parameter ${located.pointer} has no name or location`);
257
+ }
258
+ if (location === "cookie") {
259
+ return Result.fail("it declares cookie parameters, which Dual plugins do not expose");
260
+ }
261
+ const style = styleOf(declaration);
262
+ if (
263
+ style !== undefined &&
264
+ !Array.contains(["deepObject", "form", "pipeDelimited", "simple", "spaceDelimited"], style)
265
+ ) {
266
+ return Result.fail(`its parameter ${name} uses the ${style} style`);
267
+ }
268
+ const schema =
269
+ declaration.schema === undefined
270
+ ? pipe(
271
+ contentEntries(located),
272
+ Array.findFirst(entry => entry.schema),
273
+ )
274
+ : Option.some({ pointer: `${located.pointer}/schema`, value: declaration.schema });
275
+ const resolved = OpenApiSpec.resolve(
276
+ spec,
277
+ Option.getOrUndefined(Option.map(schema, found => found.value)),
278
+ );
279
+ const declared = declaration.description ?? resolved?.description;
280
+ const description =
281
+ location === "path" && Predicate.isString(declared) && /url-?encoded/iu.test(declared)
282
+ ? `${declared} Pass it unencoded; the client encodes it.`
283
+ : declared;
284
+ const explode = declaration["explode"] ?? (style === undefined || style === "form");
285
+ const joined =
286
+ location === "query" &&
287
+ style !== "deepObject" &&
288
+ explode === false &&
289
+ resolved?.["type"] === "array";
290
+ const delimiter = joined && style !== undefined ? delimiters[style] : undefined;
291
+ return Result.succeed({
292
+ commaSeparated: joined && delimiter === undefined,
293
+ deepObject: location === "query" && style === "deepObject",
294
+ ...(location === "query" &&
295
+ declaration.schema !== undefined &&
296
+ (style === undefined || style === "form") &&
297
+ explode !== false
298
+ ? { exploded: true }
299
+ : {}),
300
+ ...(delimiter === undefined ? {} : { delimiter }),
301
+ ...(Predicate.isString(description) ? { description } : {}),
302
+ location: location === "path" || location === "header" ? location : "query",
303
+ name,
304
+ required: location === "path" || declaration.required === true,
305
+ schema,
306
+ } satisfies Parameter);
307
+ }
308
+
309
+ function operationFor(source: Source, candidate: Candidate, generic: HashSet.HashSet<string>) {
310
+ const spec = source.spec;
311
+ const operation = candidate.operation;
312
+ const pointer = `${candidate.item.pointer}/${candidate.method}`;
313
+ const summary = Predicate.isString(operation.summary) ? operation.summary : undefined;
314
+ const operationId = pipe(
315
+ [operation.operationId, summary],
316
+ Array.filter(Predicate.isString),
317
+ Array.findFirst(value => String.isNonEmpty(OpenApiSpec.kebab(value))),
318
+ Option.getOrElse(() => `${candidate.method} ${candidate.path}`),
319
+ );
320
+ function fail(reason: string): Result.Result<never, Skipped> {
321
+ return Result.fail({
322
+ operation: { method: candidate.method, operationId },
323
+ path: candidate.path,
324
+ reason,
325
+ });
326
+ }
327
+
328
+ const declared = [
329
+ ...Array.map(
330
+ Array.isArray(candidate.item.value.parameters) ? candidate.item.value.parameters : [],
331
+ (value, index) => ({ pointer: `${candidate.item.pointer}/parameters/${index}`, value }),
332
+ ),
333
+ ...Array.map(
334
+ Array.isArray(operation.parameters) ? operation.parameters : [],
335
+ (value, index) => ({ pointer: `${pointer}/parameters/${index}`, value }),
336
+ ),
337
+ ];
338
+ const read = Result.all(
339
+ Array.map(declared, entry => {
340
+ const located = OpenApiSpec.locate(spec, entry.value, entry.pointer);
341
+ return Result.isFailure(located)
342
+ ? Result.fail(located.failure)
343
+ : parameterFor(spec, located.success);
344
+ }),
345
+ );
346
+ if (Result.isFailure(read)) {
347
+ return fail(read.failure);
348
+ }
349
+ const parameters = pipe(
350
+ Record.fromEntries(
351
+ Array.map(read.success, parameter => [`${parameter.location} ${parameter.name}`, parameter]),
352
+ ),
353
+ Record.values,
354
+ Array.filter(
355
+ parameter =>
356
+ parameter.location !== "header" ||
357
+ !Array.contains(ignoredHeaders, String.toLowerCase(parameter.name)),
358
+ ),
359
+ );
360
+ const inputs: Parameter[] = [
361
+ ...Array.map(OpenApiSpec.templateNames(candidate.path), name =>
362
+ pipe(
363
+ Array.findFirst(
364
+ parameters,
365
+ parameter => parameter.location === "path" && parameter.name === name,
366
+ ),
367
+ Option.getOrElse((): Parameter => ({
368
+ commaSeparated: false,
369
+ deepObject: false,
370
+ location: "path",
371
+ name,
372
+ required: true,
373
+ schema: Option.none(),
374
+ })),
375
+ ),
376
+ ),
377
+ ...Array.filter(parameters, parameter => parameter.location !== "path"),
378
+ ];
379
+ const alias = Option.getOrUndefined(Schema.decodeUnknownOption(Alias)(operation["x-dual-alias"]));
380
+
381
+ const requestBody =
382
+ candidate.method === "get" || candidate.method === "head" || operation.requestBody === undefined
383
+ ? undefined
384
+ : OpenApiSpec.locate(spec, operation.requestBody, `${pointer}/requestBody`);
385
+ if (requestBody !== undefined && Result.isFailure(requestBody)) {
386
+ return fail(`its request body cannot be read: ${requestBody.failure}`);
387
+ }
388
+ const bodies = Array.map(
389
+ requestBody === undefined ? [] : contentEntries(requestBody.success),
390
+ (entry): Body => ({
391
+ contentType: entry.media,
392
+ ...(entry.media === "application/x-www-form-urlencoded" &&
393
+ Array.isReadonlyArrayNonEmpty(entry.deepObject)
394
+ ? { deepObject: entry.deepObject }
395
+ : {}),
396
+ ...(Array.isReadonlyArrayNonEmpty(entry.joined) ? { joined: entry.joined } : {}),
397
+ encoding: pipe(
398
+ Match.value(entry.media),
399
+ Match.when(isJson, (): Encoding => "json"),
400
+ Match.when("application/x-www-form-urlencoded", (): Encoding => "form"),
401
+ Match.when(String.startsWith("multipart/"), (): Encoding => "multipart"),
402
+ Match.when(isText, (): Encoding => "text"),
403
+ Match.when(isFileMedia, (): Encoding => "binary"),
404
+ Match.orElse((): Encoding => bodyShape(spec, entry.schema) ?? "binary"),
405
+ ),
406
+ required: requestBody?.success.value.required === true,
407
+ schema: entry.schema,
408
+ }),
409
+ );
410
+ const names = [
411
+ ...Array.dedupe(Array.map(inputs, parameter => parameter.name)),
412
+ ...(Array.isReadonlyArrayNonEmpty(bodies) ? ["payload"] : []),
413
+ ...(bodies.length > 1 ? ["contentType"] : []),
414
+ ];
415
+ const repeated = Option.getOrUndefined(
416
+ Array.findFirst(names, (name, index) => Array.contains(Array.take(names, index), name)),
417
+ );
418
+ if (repeated !== undefined) {
419
+ return fail(`its input field ${repeated} is declared twice`);
420
+ }
421
+
422
+ const responses = OpenApiSpec.asObject(operation.responses) ?? {};
423
+ const successes = Array.sort(
424
+ Array.filter(Record.keys(responses), code => /^2(?:\d\d|xx)$/iu.test(code)),
425
+ Order.String,
426
+ );
427
+ const statuses = Array.isReadonlyArrayNonEmpty(successes)
428
+ ? successes
429
+ : Array.filter(["default"], status => Record.has(responses, status));
430
+ const located = Result.all(
431
+ Array.map(statuses, status =>
432
+ Result.map(
433
+ OpenApiSpec.locate(
434
+ spec,
435
+ responses[status],
436
+ `${pointer}/responses/${OpenApiSpec.pointerToken(status)}`,
437
+ ),
438
+ response => ({ response, status }),
439
+ ),
440
+ ),
441
+ );
442
+ if (Result.isFailure(located)) {
443
+ return fail(`its successful response cannot be read: ${located.failure}`);
444
+ }
445
+ const declaredResponses = Array.flatMap(located.success, (entry): readonly Response[] => {
446
+ const content = contentEntries(entry.response);
447
+ const headers = Record.keys(OpenApiSpec.asObject(entry.response.value.headers) ?? {});
448
+ const metadata = Array.isReadonlyArrayEmpty(headers) ? {} : { headers };
449
+ return Array.isReadonlyArrayEmpty(content)
450
+ ? [
451
+ {
452
+ ...metadata,
453
+ contentType: "",
454
+ kind: entry.status === "204" || entry.status === "205" ? "void" : "unknown",
455
+ schema: Option.none(),
456
+ status: entry.status,
457
+ },
458
+ ]
459
+ : Array.map(content, media => ({
460
+ contentType: media.media,
461
+ kind: pipe(
462
+ Match.value(media.media),
463
+ Match.when(isJson, (): Response["kind"] => "json"),
464
+ Match.when(isText, (): Response["kind"] => "text"),
465
+ Match.when("application/x-www-form-urlencoded", (): Response["kind"] => "text"),
466
+ Match.when(isFileMedia, (): Response["kind"] => "binary"),
467
+ Match.orElse((): Response["kind"] => bodyShape(spec, media.schema) ?? "binary"),
468
+ ),
469
+ schema: media.schema,
470
+ status: entry.status,
471
+ }));
472
+ });
473
+ const responseVariants: Response[] = Array.isReadonlyArrayEmpty(declaredResponses)
474
+ ? [{ contentType: "", kind: "unknown", schema: Option.none(), status: "2XX" }]
475
+ : declaredResponses;
476
+
477
+ const server = OpenApiSpec.serverUrl(
478
+ OpenApiSpec.firstServer(
479
+ operation["servers"],
480
+ candidate.item.value["servers"],
481
+ spec.document.servers,
482
+ ),
483
+ source.specUrl,
484
+ );
485
+ if (Result.isFailure(server)) {
486
+ return fail(server.failure);
487
+ }
488
+ const groupSource = pipe(
489
+ Array.filter(Array.isArray(operation["tags"]) ? operation["tags"] : [], Predicate.isString),
490
+ Array.findFirst(value => String.isNonEmpty(OpenApiSpec.kebab(value))),
491
+ Option.orElse(() =>
492
+ Array.findFirst(
493
+ pipe(candidate.path, String.split("/")),
494
+ part =>
495
+ String.isNonEmpty(OpenApiSpec.kebab(part)) &&
496
+ !pipe(part, String.startsWith("{")) &&
497
+ !/^(?:v\d+(?:[._-]\d+)*|\d+)$/iu.test(part),
498
+ ),
499
+ ),
500
+ Option.getOrElse(() => "root"),
501
+ );
502
+ const groupSegments = Array.map(segmentsOf(groupSource), OpenApiSpec.kebab);
503
+ const actionSegments = Array.dropWhile(segmentsOf(operationId), (segment, index) =>
504
+ Option.contains(Array.get(groupSegments, index), OpenApiSpec.kebab(segment)),
505
+ );
506
+ const named = Option.match(Option.fromNullishOr(summary), {
507
+ onNone: () => OpenApiSpec.titleCase(operationId),
508
+ onSome: text =>
509
+ HashSet.has(generic, text)
510
+ ? OpenApiSpec.titleCase(
511
+ Array.join([candidate.method, ...staticSegments(candidate.path)], " "),
512
+ )
513
+ : text,
514
+ });
515
+ const googleUpload =
516
+ operation["x-dual-google-upload"] === undefined
517
+ ? undefined
518
+ : Schema.decodeUnknownResult(GoogleUpload)(operation["x-dual-google-upload"]);
519
+ if (googleUpload !== undefined && Result.isFailure(googleUpload)) {
520
+ return fail("its Google upload protocol declaration is invalid");
521
+ }
522
+ const graphql =
523
+ operation["x-dual-graphql"] === undefined
524
+ ? undefined
525
+ : Schema.decodeUnknownResult(Graphql)(operation["x-dual-graphql"]);
526
+ if (graphql !== undefined && Result.isFailure(graphql)) {
527
+ return fail("its GraphQL declaration is invalid");
528
+ }
529
+ if (Predicate.isString(operation["x-dual-excluded"])) {
530
+ return fail(operation["x-dual-excluded"]);
531
+ }
532
+ const mcp =
533
+ operation["x-dual-mcp"] === undefined
534
+ ? undefined
535
+ : Schema.decodeUnknownResult(Mcp)(operation["x-dual-mcp"]);
536
+ if (mcp !== undefined && Result.isFailure(mcp)) {
537
+ return fail("its Model Context Protocol tool declaration is invalid");
538
+ }
539
+ return Result.succeed({
540
+ ...(Array.isArray(operation["x-dual-path-segments"])
541
+ ? { pathSegments: Array.filter(operation["x-dual-path-segments"], Predicate.isString) }
542
+ : {}),
543
+ ...(operation["x-dual-preauthenticated-upload"] === true
544
+ ? { preauthenticatedUpload: true }
545
+ : {}),
546
+ ...(operation["x-dual-google-download"] === true ? { googleDownload: true } : {}),
547
+ ...(operation["x-dual-next-link"] === true ? { nextLink: true } : {}),
548
+ ...(alias === undefined ? {} : { alias }),
549
+ ...(googleUpload === undefined ? {} : { googleUpload: googleUpload.success }),
550
+ ...(graphql === undefined ? {} : { graphql: graphql.success }),
551
+ ...(mcp === undefined ? {} : { mcp: mcp.success }),
552
+ actionId: OpenApiSpec.kebab(
553
+ Array.isArrayNonEmpty(actionSegments) ? Array.join(actionSegments, ".") : operationId,
554
+ ),
555
+ actionName: named,
556
+ bodies,
557
+ deprecated: operation.deprecated === true,
558
+ description: pipe(
559
+ Option.liftPredicate(operation.description, Predicate.isString),
560
+ Option.filter(description => description !== named && !HashSet.has(generic, description)),
561
+ description =>
562
+ operation.deprecated === true
563
+ ? Option.some(
564
+ `Deprecated by the API provider. ${Option.getOrElse(description, () => "")}`,
565
+ )
566
+ : description,
567
+ ),
568
+ groupId: OpenApiSpec.kebab(groupSource),
569
+ method: candidate.method,
570
+ operationId: Predicate.isString(operation.operationId) ? operation.operationId : "",
571
+ parameters:
572
+ alias === undefined
573
+ ? inputs
574
+ : Array.map(inputs, parameter =>
575
+ parameter.location === "path" && parameter.name === alias.parameter
576
+ ? {
577
+ ...parameter,
578
+ description:
579
+ parameter.description === undefined
580
+ ? `Omit it to use ${alias.replacement}.`
581
+ : `${pipe(parameter.description, String.replace(/\.?\s*$/u, "."))} Omit it to use ${alias.replacement}.`,
582
+ required: false,
583
+ }
584
+ : parameter,
585
+ ),
586
+ path: candidate.path,
587
+ responses: responseVariants,
588
+ url: `${server.success}${candidate.path}`,
589
+ });
590
+ }
591
+
592
+ function candidates(spec: OpenApiSpec.Spec) {
593
+ return pipe(
594
+ Record.toEntries(spec.document.paths),
595
+ Array.sort(Order.mapInput(Order.String, (entry: readonly [string, unknown]) => entry[0])),
596
+ Array.flatMap((entry): Result.Result<Candidate, Skipped>[] => {
597
+ const path = entry[0];
598
+ const item = OpenApiSpec.locate(spec, entry[1], `#/paths/${OpenApiSpec.pointerToken(path)}`);
599
+ if (Result.isFailure(item)) {
600
+ return [Result.fail({ path, reason: `its path item cannot be read: ${item.failure}` })];
601
+ }
602
+ return Array.getSomes(
603
+ Array.map(methods, method =>
604
+ Option.map(
605
+ Option.fromNullishOr(OpenApiSpec.asObject(item.success.value[method])),
606
+ operation => Result.succeed({ item: item.success, method, operation, path }),
607
+ ),
608
+ ),
609
+ );
610
+ }),
611
+ );
612
+ }
613
+
614
+ export function walk(source: Source) {
615
+ const all = candidates(source.spec);
616
+ const generic = pipe(
617
+ Array.getSuccesses(all),
618
+ Array.flatMap(candidate =>
619
+ Array.map(
620
+ Array.filter(
621
+ [candidate.operation.summary, candidate.operation.description],
622
+ Predicate.isString,
623
+ ),
624
+ text => ({
625
+ resource: pipe(
626
+ candidate.path,
627
+ String.split("/"),
628
+ Array.filter(
629
+ segment =>
630
+ String.isNonEmpty(segment) &&
631
+ !pipe(segment, String.includes("{")) &&
632
+ !pipe(segment, String.startsWith("$")),
633
+ ),
634
+ Array.last,
635
+ ),
636
+ text,
637
+ }),
638
+ ),
639
+ ),
640
+ Array.groupBy(entry => entry.text),
641
+ Record.filter(entries => Array.dedupe(Array.map(entries, entry => entry.resource)).length > 1),
642
+ Record.keys,
643
+ HashSet.fromIterable,
644
+ );
645
+ const separated = pipe(
646
+ all,
647
+ Array.map(candidate =>
648
+ Result.isFailure(candidate)
649
+ ? Result.fail(candidate.failure)
650
+ : operationFor(source, candidate.success, generic),
651
+ ),
652
+ Array.separate,
653
+ );
654
+ return { operations: separated[0], skipped: separated[1] };
655
+ }
656
+
657
+ export function withReadableGroupIds(
658
+ documents: readonly {
659
+ readonly name: Option.Option<string>;
660
+ readonly title: string;
661
+ readonly operations: readonly Operation[];
662
+ }[],
663
+ ) {
664
+ const titles = Array.map(documents, document =>
665
+ pipe(OpenApiSpec.kebab(document.title), String.split("-")),
666
+ );
667
+ const groups = Array.map(
668
+ Array.dedupe(
669
+ Array.flatMap(documents, document =>
670
+ Array.map(document.operations, operation => operation.groupId),
671
+ ),
672
+ ),
673
+ String.split("-"),
674
+ );
675
+ const shared = Array.match(groups, {
676
+ onEmpty: () => 0,
677
+ onNonEmpty: all =>
678
+ all.length === 1
679
+ ? 0
680
+ : Array.takeWhile(Array.headNonEmpty(all), (word, index) =>
681
+ Array.every(all, words => Option.contains(Array.get(words, index), word)),
682
+ ).length,
683
+ });
684
+ const readable = Array.zipWith(documents, titles, (document, title) => {
685
+ const own = Array.filter(
686
+ title,
687
+ word => !Array.every(titles, other => Array.contains(other, word)),
688
+ );
689
+ const prefix = pipe(
690
+ document.name,
691
+ Option.map(String.split("-")),
692
+ Option.getOrElse(() => (Array.isReadonlyArrayEmpty(own) ? title : own)),
693
+ );
694
+ return HashMap.fromIterable(
695
+ Array.map(
696
+ Array.dedupe(Array.map(document.operations, operation => operation.groupId)),
697
+ id => {
698
+ const words = pipe(id, String.split("-"));
699
+ const kept = Array.drop(words, shared);
700
+ const named = [
701
+ ...(documents.length > 1 ? prefix : []),
702
+ ...(Array.isReadonlyArrayEmpty(kept) ? words : kept),
703
+ ];
704
+ const collapsed = Array.filter(
705
+ named,
706
+ (word, position) =>
707
+ !Option.exists(
708
+ Array.get(named, position - 1),
709
+ before => OpenApiSpec.singular(before) === OpenApiSpec.singular(word),
710
+ ),
711
+ );
712
+ return [id, Array.join(collapsed, "-")] as const;
713
+ },
714
+ ),
715
+ );
716
+ });
717
+ const clashing = pipe(
718
+ Array.flatMap(readable, ids => Array.fromIterable(HashMap.values(ids))),
719
+ Array.groupBy(identity),
720
+ Record.filter(members => members.length > 1),
721
+ );
722
+ return Array.zipWith(documents, readable, (document, ids) =>
723
+ Array.map(document.operations, operation => {
724
+ const id = HashMap.getUnsafe(ids, operation.groupId);
725
+ return Record.has(clashing, id) ? operation : { ...operation, groupId: id };
726
+ }),
727
+ );
728
+ }
729
+
730
+ function suffixed(
731
+ operations: readonly Operation[],
732
+ suffix: (operation: Operation, colliding: readonly Operation[]) => string,
733
+ ) {
734
+ function key(operation: Operation) {
735
+ return `${operation.groupId}/${operation.actionId}`;
736
+ }
737
+ const byKey = Array.groupBy(operations, key);
738
+ return Array.map(operations, operation =>
739
+ pipe(
740
+ Record.get(byKey, key(operation)),
741
+ Option.filter(colliding => colliding.length > 1),
742
+ Option.map(colliding => suffix(operation, colliding)),
743
+ Option.filter(String.isNonEmpty),
744
+ Option.match({
745
+ onNone: () => operation,
746
+ onSome: added => ({ ...operation, actionId: `${operation.actionId}-${added}` }),
747
+ }),
748
+ ),
749
+ );
750
+ }
751
+
752
+ function staticSegments(path: string) {
753
+ return pipe(
754
+ path,
755
+ String.split("/"),
756
+ Array.filter(segment => !pipe(segment, String.includes("{"))),
757
+ Array.map(OpenApiSpec.kebab),
758
+ Array.filter(String.isNonEmpty),
759
+ );
760
+ }
761
+
762
+ export function withUniqueActionIds(operations: readonly Operation[]) {
763
+ return suffixed(
764
+ suffixed(
765
+ suffixed(operations, operation => operation.method),
766
+ (operation, colliding) =>
767
+ pipe(
768
+ staticSegments(operation.path),
769
+ Array.filter(
770
+ segment =>
771
+ !Array.every(colliding, other => Array.contains(staticSegments(other.path), segment)),
772
+ ),
773
+ Array.join("-"),
774
+ ),
775
+ ),
776
+ operation =>
777
+ pipe(OpenApiSchema.hash(`${operation.method} ${operation.path}`), String.slice(0, 6)),
778
+ );
779
+ }
780
+
781
+ export * as OpenApiOperations from "./operations.ts";