anhedral 0.10.1 → 0.11.1

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 (183) hide show
  1. package/README.md +79 -124
  2. package/assets/patches/LICENSE.braces +21 -0
  3. package/assets/patches/LICENSE.node-forge +50 -0
  4. package/assets/patches/audit-deps.mjs +167 -0
  5. package/assets/patches/braces@3.0.3.patch +127 -0
  6. package/assets/patches/node-forge@1.4.0.patch +41 -0
  7. package/dist/auth-schema.js +3 -3
  8. package/dist/bin.js +284 -163
  9. package/dist/capabilities.d.ts +4 -4
  10. package/dist/capabilities.js +6 -2
  11. package/dist/capability-contract.d.ts +47 -0
  12. package/dist/capability-contract.js +153 -0
  13. package/dist/catalog-model.d.ts +24 -0
  14. package/dist/catalog-model.js +1 -0
  15. package/dist/catalog-registration.d.ts +16 -0
  16. package/dist/catalog-registration.js +22 -0
  17. package/dist/catalog-snapshot.d.ts +5 -0
  18. package/dist/catalog-snapshot.js +97 -0
  19. package/dist/cli-arguments.d.ts +16 -0
  20. package/dist/cli-arguments.js +115 -0
  21. package/dist/cli-output.d.ts +8 -0
  22. package/dist/cli-output.js +236 -0
  23. package/dist/cloudflare.d.ts +14 -3
  24. package/dist/cloudflare.js +196 -36
  25. package/dist/command-schema.d.ts +21 -0
  26. package/dist/command-schema.js +418 -0
  27. package/dist/delivery.d.ts +12 -5
  28. package/dist/delivery.js +173 -39
  29. package/dist/dependencies.d.ts +24 -0
  30. package/dist/dependencies.js +48 -0
  31. package/dist/dependency-patches.d.ts +7 -0
  32. package/dist/dependency-patches.js +125 -0
  33. package/dist/index.d.ts +26 -1
  34. package/dist/index.js +17 -1
  35. package/dist/inspector-model.d.ts +123 -0
  36. package/dist/inspector-model.js +1 -0
  37. package/dist/integration-service-readers.d.ts +13 -0
  38. package/dist/integration-service-readers.js +173 -0
  39. package/dist/lifecycle-model.d.ts +15 -0
  40. package/dist/lifecycle-model.js +20 -0
  41. package/dist/lifecycle.d.ts +11 -0
  42. package/dist/lifecycle.js +91 -0
  43. package/dist/mobile-delivery.d.ts +100 -0
  44. package/dist/mobile-delivery.js +319 -0
  45. package/dist/neon-service-data.d.ts +8 -0
  46. package/dist/neon-service-data.js +117 -0
  47. package/dist/platforms/mobile.js +8 -5
  48. package/dist/pnpm-policy.d.ts +2 -2
  49. package/dist/pnpm-policy.js +19 -45
  50. package/dist/project-catalog.d.ts +41 -0
  51. package/dist/project-catalog.js +288 -0
  52. package/dist/project-config.d.ts +14 -0
  53. package/dist/project-config.js +89 -0
  54. package/dist/project-inspector.d.ts +4 -0
  55. package/dist/project-inspector.js +702 -0
  56. package/dist/project-lifecycle.d.ts +25 -0
  57. package/dist/project-lifecycle.js +57 -0
  58. package/dist/project-state.d.ts +22 -1
  59. package/dist/project-state.js +361 -27
  60. package/dist/provider-auth.d.ts +41 -0
  61. package/dist/provider-auth.js +209 -0
  62. package/dist/provider-readiness.js +27 -10
  63. package/dist/providers/adapters.d.ts +17 -0
  64. package/dist/providers/adapters.js +272 -0
  65. package/dist/providers/api.d.ts +29 -0
  66. package/dist/providers/api.js +253 -0
  67. package/dist/providers/config.d.ts +15 -0
  68. package/dist/providers/config.js +182 -0
  69. package/dist/providers/definitions.d.ts +318 -0
  70. package/dist/providers/definitions.js +127 -0
  71. package/dist/providers/provision.d.ts +24 -0
  72. package/dist/providers/provision.js +76 -0
  73. package/dist/providers/receipts.d.ts +20 -0
  74. package/dist/providers/receipts.js +66 -0
  75. package/dist/providers/recovery-verification.d.ts +7 -0
  76. package/dist/providers/recovery-verification.js +112 -0
  77. package/dist/providers/recovery.d.ts +30 -0
  78. package/dist/providers/recovery.js +34 -0
  79. package/dist/providers/runtime.d.ts +10 -0
  80. package/dist/providers/runtime.js +254 -0
  81. package/dist/providers/schema.d.ts +28 -0
  82. package/dist/providers/schema.js +49 -0
  83. package/dist/providers/state.d.ts +55 -0
  84. package/dist/providers/state.js +289 -0
  85. package/dist/provision.d.ts +10 -1
  86. package/dist/provision.js +91 -4
  87. package/dist/r2-service-data.d.ts +2 -0
  88. package/dist/r2-service-data.js +136 -0
  89. package/dist/readiness.js +9 -13
  90. package/dist/registry/add.d.ts +6 -0
  91. package/dist/registry/add.js +93 -22
  92. package/dist/registry/commands.d.ts +3 -2
  93. package/dist/registry/commands.js +52 -15
  94. package/dist/registry/options.d.ts +1 -1
  95. package/dist/registry/options.js +5 -4
  96. package/dist/registry/preview.d.ts +11 -0
  97. package/dist/registry/preview.js +91 -0
  98. package/dist/registry/receipt.d.ts +1 -0
  99. package/dist/registry/receipt.js +19 -4
  100. package/dist/registry/resolve.js +5 -1
  101. package/dist/registry/usage.d.ts +10 -0
  102. package/dist/registry/usage.js +18 -37
  103. package/dist/render.d.ts +2 -0
  104. package/dist/render.js +6 -0
  105. package/dist/runtime-policy.d.ts +4 -0
  106. package/dist/runtime-policy.js +21 -0
  107. package/dist/scaffold/auth.js +3 -19
  108. package/dist/scaffold/bootstrap.js +2 -2
  109. package/dist/scaffold/compose.js +9 -3
  110. package/dist/scaffold/database.js +107 -25
  111. package/dist/scaffold/documentation.js +18 -13
  112. package/dist/scaffold/lint.d.ts +4 -0
  113. package/dist/scaffold/lint.js +56 -0
  114. package/dist/scaffold/neon-realtime.d.ts +2 -0
  115. package/dist/scaffold/neon-realtime.js +97 -0
  116. package/dist/scaffold/stack-documentation.js +1 -1
  117. package/dist/scaffold/void.d.ts +4 -0
  118. package/dist/scaffold/void.js +256 -0
  119. package/dist/scaffold/web.js +7 -1
  120. package/dist/scaffold/workspace.js +127 -25
  121. package/dist/service-deletion.d.ts +29 -0
  122. package/dist/service-deletion.js +195 -0
  123. package/dist/service-descriptor.d.ts +10 -0
  124. package/dist/service-descriptor.js +78 -0
  125. package/dist/service-model.d.ts +49 -0
  126. package/dist/service-model.js +8 -0
  127. package/dist/service-operations.d.ts +29 -0
  128. package/dist/service-operations.js +78 -0
  129. package/dist/service-readers.d.ts +8 -0
  130. package/dist/service-readers.js +247 -0
  131. package/dist/services-command.d.ts +39 -0
  132. package/dist/services-command.js +100 -0
  133. package/dist/ship.d.ts +348 -0
  134. package/dist/ship.js +237 -0
  135. package/dist/stack-registry.d.ts +4 -2
  136. package/dist/stack-registry.js +48 -12
  137. package/dist/standard.d.ts +2 -1
  138. package/dist/standard.js +33 -14
  139. package/dist/transaction.d.ts +2 -0
  140. package/dist/transaction.js +10 -0
  141. package/dist/util.js +17 -2
  142. package/dist/vercel.d.ts +5 -3
  143. package/dist/vercel.js +96 -14
  144. package/dist/version.d.ts +1 -1
  145. package/dist/version.js +1 -1
  146. package/dist/vinext.d.ts +1 -0
  147. package/dist/vinext.js +13 -1
  148. package/dist/void-execution.d.ts +10 -0
  149. package/dist/void-execution.js +94 -0
  150. package/dist/void-migrations.d.ts +6 -0
  151. package/dist/void-migrations.js +110 -0
  152. package/dist/void-state.d.ts +16 -0
  153. package/dist/void-state.js +65 -0
  154. package/dist/void.d.ts +3 -0
  155. package/dist/void.js +5 -0
  156. package/docs/cli-design.md +67 -0
  157. package/docs/delivery-workflow.md +32 -17
  158. package/docs/plugin-ui.md +102 -0
  159. package/docs/provider-configuration.md +116 -0
  160. package/docs/stack-standard.md +175 -0
  161. package/docs/void-verification.md +185 -0
  162. package/package.json +29 -23
  163. package/assets/anhedral-cli-init-technical.svg +0 -322
  164. package/assets/anhedral-cli-init.svg +0 -322
  165. package/assets/anhedral-mark.svg +0 -4
  166. package/assets/anhedral.svg +0 -4
  167. package/assets/favicon.ico +0 -0
  168. package/assets/security/LICENSES.txt +0 -63
  169. package/assets/security/audit-deps.mjs +0 -300
  170. package/assets/security/braces-regression.mjs +0 -102
  171. package/assets/security/braces@3.0.3.patch +0 -285
  172. package/assets/security/decode-uri-component@0.2.2.patch +0 -149
  173. package/assets/security/decoder-regression.mjs +0 -37
  174. package/assets/security/forge-regression.mjs +0 -46
  175. package/assets/security/manifest.json +0 -53
  176. package/assets/security/node-forge@1.4.0.patch +0 -26
  177. package/dist/managed-hosting.d.ts +0 -49
  178. package/dist/managed-hosting.js +0 -373
  179. package/dist/security-backports.d.ts +0 -3
  180. package/dist/security-backports.js +0 -26
  181. package/docs/application-stack-standard.md +0 -104
  182. package/docs/managed-hosting-architecture.md +0 -87
  183. package/docs/sponsorships.md +0 -25
@@ -0,0 +1,236 @@
1
+ const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
2
+ const entries = (value) => (Array.isArray(value) ? value.map(record) : []);
3
+ const string = (value) => typeof value === 'string' ? value.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '') : '';
4
+ const names = (value) => Array.isArray(value)
5
+ ? value
6
+ .filter((entry) => typeof entry === 'string')
7
+ .map(string)
8
+ .join(', ')
9
+ : '';
10
+ /** Human output is an explicit summary, never a recursive dump of provider payloads. */
11
+ export function formatResult(command, value) {
12
+ const data = record(value);
13
+ const lines = [];
14
+ const next = (action) => {
15
+ if (string(action))
16
+ lines.push(`Next: ${string(action)}`);
17
+ };
18
+ if (command === 'init') {
19
+ lines.push(data.generated ? `Created ${string(data.root)}.` : `Stack preview for ${string(data.root)}.`, `Stack: ${names(data.products)}.`, `Hosting: ${string(data.hosting)}.`, '');
20
+ const catalog = record(data.catalog);
21
+ if (catalog.state === 'registered')
22
+ lines.push('Registered in your local Anhedral dashboard.');
23
+ if (catalog.state === 'pending')
24
+ next(catalog.nextAction);
25
+ if (data.generated)
26
+ lines.push('Review the generated source and provider settings in anhedral.json (providers).', 'In the project directory, start development with pnpm dev. Run pnpm check before delivery.', 'Next: anhedral auth, then connect the intended hosting account and preview anhedral ship --dry-run.');
27
+ else
28
+ lines.push('No files, provider resources or deployments were created.');
29
+ }
30
+ else if (command === 'services') {
31
+ if (Array.isArray(data.services)) {
32
+ lines.push(`${data.services.length} local service entries.`);
33
+ for (const service of entries(data.services))
34
+ lines.push(` ${string(service.key)}${service.state ? ` — ${string(service.state)}` : ''}`);
35
+ }
36
+ else if (Array.isArray(data.points)) {
37
+ lines.push(`Analytics: ${string(data.source)}.`, `Window: ${string(data.start)} to ${string(data.end)} (UTC).`, `${data.points.length} provider data points.`, 'Use --json for the complete aggregate values.');
38
+ }
39
+ else if (Array.isArray(data.rows)) {
40
+ lines.push(`Read ${data.rows.length} rows.`, `Private data${data.masked ? '; sensitive fields are masked' : ''}. Use --json to inspect values.`);
41
+ }
42
+ else if (string(data.token)) {
43
+ lines.push(`Deletion plan: ${string(data.kind)} ${string(data.name)}.`, string(data.impact), `Affected apps: ${names(data.applications) || 'None recorded'}.`, `Expires: ${string(data.expiresAt)}.`, 'Use --json for the single-use confirmation token; deleting requires the exact resource name.');
44
+ }
45
+ else if (Array.isArray(value))
46
+ lines.push(`Tables: ${names(value) || 'None'}.`);
47
+ else
48
+ lines.push(`Service: ${string(data.state) || 'Checked'}.`, string(data.message));
49
+ }
50
+ else if (command === 'add') {
51
+ lines.push(data.dryRun ? 'Addition preview.' : 'Stack parts added.', names(data.items) ? `Parts: ${names(data.items)}.` : 'No new stack parts.', `Project: ${string(data.root)}.`);
52
+ const files = Array.isArray(data.files) ? data.files : [];
53
+ if (files.length)
54
+ lines.push('', ...files.map((file) => ` ${string(file)}`));
55
+ if (data.filesChecked === false)
56
+ lines.push('Source files were not checked: this selection needs the networked web bootstrap.');
57
+ if (names(data.conflicts))
58
+ lines.push(`Conflicts: ${names(data.conflicts)}.`);
59
+ for (const preview of entries(data.previews))
60
+ lines.push('', string(preview.path), string(preview.unavailable ?? preview.diff ?? preview.content));
61
+ if (data.dryRun)
62
+ lines.push('', 'No application files were changed.');
63
+ else
64
+ next('Run anhedral doctor and review the selected services’ setup requirements.');
65
+ }
66
+ else if (command === 'inspect') {
67
+ lines.push(`Project: ${string(data.name) || 'Name unavailable'}.`, 'Local recorded evidence; authentication and live provider status are not checked.');
68
+ const selection = record(record(data.selection).data);
69
+ lines.push(`Stack: ${names(selection.products) || 'Unavailable'}.`);
70
+ for (const target of entries(record(data.targets).data)) {
71
+ const latest = record(target.latestAttempt), successful = record(target.lastSuccessful);
72
+ lines.push(` ${string(target.application)} — ${string(target.provider)} (${string(target.delivery)})`);
73
+ if (string(latest.state))
74
+ lines.push(` Latest recorded target result: ${string(latest.state)}.`);
75
+ if (string(latest.operationState))
76
+ lines.push(` Overall attempt: ${string(latest.operationState)}.`);
77
+ if (string(successful.id))
78
+ lines.push(` Last recorded success: ${string(successful.id)}.`);
79
+ if (string(target.error))
80
+ lines.push(` ${string(target.error)}`);
81
+ }
82
+ for (const check of entries(record(record(data.readiness).data).checks))
83
+ lines.push(` ${check.ok ? 'pass' : 'fail'} ${string(check.id)} — ${string(check.detail)}`);
84
+ for (const key of [
85
+ 'selection',
86
+ 'workspaces',
87
+ 'configuration',
88
+ 'targets',
89
+ 'setupProviders',
90
+ 'integrations',
91
+ 'cloudflareResources',
92
+ 'readiness',
93
+ 'operation',
94
+ ]) {
95
+ const section = record(data[key]);
96
+ if (section.state === 'unavailable')
97
+ lines.push(`${key}: ${string(section.error) || 'Unavailable'}.`);
98
+ }
99
+ next('Use --json for target-specific records. Review local checks, then explicitly run auth or ship when intended.');
100
+ }
101
+ else if (command === 'auth') {
102
+ const checks = entries(data.checks);
103
+ lines.push(checks.length ? 'Provider authentication' : 'This stack requires no provider authentication.');
104
+ for (const check of checks) {
105
+ lines.push(` ${string(check.provider).padEnd(12)}${string(check.state)}${string(check.access) && check.access !== 'none' ? ` (${string(check.access)} access)` : ''}`);
106
+ if (check.state !== 'verified' || check.access === 'runtime')
107
+ next(check.nextAction);
108
+ }
109
+ if (checks.length && string(data.note))
110
+ lines.push(string(data.note));
111
+ if (checks.length)
112
+ next(data.authenticated
113
+ ? 'Complete provider settings, connect the intended hosting account, then run anhedral ship --dry-run.'
114
+ : 'Resolve the reported access checks, then repeat anhedral auth --status.');
115
+ }
116
+ else if (command === 'integrations') {
117
+ lines.push(data.recovered
118
+ ? 'Integration resource reconciled.'
119
+ : 'Integration receipts (recorded locally).');
120
+ for (const provider of entries(data.providers)) {
121
+ lines.push(` ${string(provider.provider)}`);
122
+ for (const operation of entries(provider.operations))
123
+ lines.push(` ${string(operation.operation)}: ${string(operation.status)}`);
124
+ }
125
+ if (string(data.operation))
126
+ lines.push(`Operation: ${string(data.operation)}`);
127
+ next(data.nextAction ??
128
+ 'Use --json to inspect the resource IDs and safe recovery descriptors. Unknown operations must be verified before retrying.');
129
+ }
130
+ else if (command === 'registry') {
131
+ lines.push(`${string(data.name)} (${string(data.type)})`, string(data.description));
132
+ if (names(data.targets))
133
+ lines.push(`Files: ${names(data.targets)}`);
134
+ if (names(data.registryDependencies))
135
+ lines.push(`Requires: ${names(data.registryDependencies)}`);
136
+ const setup = record(data.setup);
137
+ for (const key of ['access', 'credentials', 'resources', 'verify'])
138
+ if (names(setup[key]))
139
+ lines.push(`${key}: ${names(setup[key])}`);
140
+ next(`Inspect anhedral add ${string(data.name)} --dry-run in your project.`);
141
+ }
142
+ else if (command === 'doctor') {
143
+ const local = record(data.local);
144
+ const checks = entries(data.checks ?? local.checks);
145
+ lines.push(data.localReady ? 'Local project checks passed.' : 'Local project checks need attention.');
146
+ for (const check of checks) {
147
+ lines.push(` ${check.ok ? 'pass' : 'fail'} ${string(check.id)}${string(check.detail) ? ` — ${string(check.detail)}` : ''}`);
148
+ if (check.ok === false)
149
+ next(check.nextAction);
150
+ }
151
+ if (data.providerVerification)
152
+ lines.push(`Provider evidence: ${string(data.providerVerification)}.`);
153
+ for (const check of entries(data.prerequisiteChecks)) {
154
+ lines.push(` ${check.ok ? 'pass' : 'fail'} ${string(check.id)} — ${string(check.detail)}`);
155
+ if (check.ok === false)
156
+ next(check.nextAction);
157
+ }
158
+ lines.push('Local readiness does not certify production behavior.');
159
+ }
160
+ else {
161
+ const project = record(data.project);
162
+ const release = record(data.release);
163
+ const state = string(data.state ?? release.state);
164
+ lines.push(data.mutation === false
165
+ ? `${command}: preview only.`
166
+ : `${command}${state ? `: ${state}` : ': completed'}.`);
167
+ if (string(project.name))
168
+ lines.push(`Project: ${string(project.name)} (${string(project.provider)}).`);
169
+ if (string(release.id))
170
+ lines.push(`Release: ${string(release.id)}`);
171
+ if (string(data.buildId))
172
+ lines.push(`Build: ${string(data.buildId)} (${string(data.platform)}, ${string(data.profile)}).`);
173
+ if (string(data.evidence))
174
+ lines.push(`Evidence: ${string(data.evidence)}.`);
175
+ if (typeof data.activeRecordedVersion === 'boolean')
176
+ lines.push(`Recorded production version: ${data.activeRecordedVersion ? 'active' : 'not confirmed'}.`);
177
+ for (const target of entries(data.provider))
178
+ lines.push(` ${string(target.target)}: ${target.activeRecordedVersion === true ? 'recorded version active' : 'recorded version not confirmed'}`);
179
+ const repository = record(data.repository);
180
+ if (string(repository.nameWithOwner))
181
+ lines.push(`Repository: ${string(repository.nameWithOwner)}`);
182
+ if (string(data.branch))
183
+ lines.push(`Branch: ${string(data.branch)}`);
184
+ for (const resource of entries(record(data.provisioning ?? data).resources))
185
+ lines.push(` ${string(resource.kind)} ${string(resource.name)}${string(resource.target) ? ` (${string(resource.target)})` : ''}`);
186
+ for (const key of ['downloadUrl', 'buildPageUrl', 'managementFile', 'file'])
187
+ if (string(data[key]))
188
+ lines.push(`${key}: ${string(data[key])}`);
189
+ if (string(release.url))
190
+ lines.push(`URL: ${string(release.url)}`);
191
+ const integration = record(data.integrations);
192
+ for (const provider of entries(integration.providers)) {
193
+ lines.push(` ${string(provider.provider)}${names(provider.missing) ? `: missing ${names(provider.missing)}` : ': configuration selected'}`);
194
+ }
195
+ for (const provider of entries(integration.results)) {
196
+ lines.push(` ${string(provider.provider)}: ${provider.ready ? 'configured' : 'setup pending'}`);
197
+ for (const action of Array.isArray(provider.nextActions) ? provider.nextActions : [])
198
+ next(action);
199
+ }
200
+ if (data.productVerification)
201
+ lines.push(`Product verification: ${string(data.productVerification)}.`);
202
+ const operation = record(data.operation);
203
+ if (string(operation.state)) {
204
+ lines.push(`Operation: ${string(operation.state)} (recorded locally).`);
205
+ for (const phase of entries(operation.phases))
206
+ lines.push(` ${string(phase.name)}: ${string(phase.state)}`);
207
+ }
208
+ for (const target of entries(data.targets)) {
209
+ if (string(target.provider)) {
210
+ const result = record(target.result);
211
+ const release = record(result.release);
212
+ lines.push(` ${string(target.provider)}: ${string(target.state ?? result.state ?? release.state) || 'planned'}`);
213
+ }
214
+ }
215
+ next(data.nextAction);
216
+ if (data.mutation === false)
217
+ lines.push('No provider resources or deployments were changed.');
218
+ else if (!data.nextAction && command === 'ship' && state === 'deployed')
219
+ next('Run anhedral verify to exercise the application’s configured acceptance checks.');
220
+ else if (!data.nextAction && command === 'connect')
221
+ next('Review and commit the connection manifest, then run anhedral ship --dry-run.');
222
+ if (!state && !data.nextAction && !Object.keys(project).length)
223
+ lines.push('Use --json for the complete recorded evidence.');
224
+ }
225
+ return lines.join('\n').trimEnd();
226
+ }
227
+ export function printResult(command, value, options = {}) {
228
+ if (options.json)
229
+ console.log(JSON.stringify(value, null, 2));
230
+ else if (!options.quiet)
231
+ console.log(formatResult(command, value));
232
+ }
233
+ export function printProgress(message, options = {}) {
234
+ if (process.stderr.isTTY && !options.json && !options.quiet)
235
+ console.error(message);
236
+ }
@@ -6,9 +6,20 @@ export interface CloudflareResponse {
6
6
  total_pages?: number;
7
7
  count?: number;
8
8
  per_page?: number;
9
+ cursor?: string;
9
10
  };
10
11
  }
11
- export type CloudflareRequest = (method: 'GET' | 'POST', endpoint: string, body?: unknown) => Promise<CloudflareResponse>;
12
- /** Credentials stay in this closure, never in returned receipts, arguments or files. */
13
- export declare function cloudflareRequest(project: ApplicationProject, directory: string, run: DeliveryRunner, env: NodeJS.ProcessEnv): Promise<CloudflareRequest>;
12
+ export type CloudflareRequest = (method: 'GET' | 'POST' | 'DELETE', endpoint: string, body?: unknown) => Promise<CloudflareResponse>;
13
+ export interface CloudflareRequestOptions {
14
+ send?: typeof fetch;
15
+ timeoutMs?: number;
16
+ analytics?: boolean;
17
+ }
18
+ export declare class CloudflareRequestError extends Error {
19
+ readonly status: number;
20
+ constructor(message: string, status: number);
21
+ }
22
+ /** Credentials stay in this closure. Fixed account paths, bounded response reads and
23
+ * a whole-request deadline apply to reads and mutations; mutations never retry. */
24
+ export declare function cloudflareRequest(project: ApplicationProject, directory: string, run: DeliveryRunner, env: NodeJS.ProcessEnv, options?: CloudflareRequestOptions): Promise<CloudflareRequest>;
14
25
  export declare function listCloudflare(request: CloudflareRequest, endpoint: string): Promise<Record<string, unknown>[]>;
@@ -1,64 +1,224 @@
1
- /** Credentials stay in this closure, never in returned receipts, arguments or files. */
2
- export async function cloudflareRequest(project, directory, run, env) {
1
+ const ORIGIN = 'https://api.cloudflare.com';
2
+ const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
3
+ export class CloudflareRequestError extends Error {
4
+ status;
5
+ constructor(message, status) {
6
+ super(message);
7
+ this.status = status;
8
+ }
9
+ }
10
+ function object(value) {
11
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
12
+ }
13
+ function cancelBody(response) {
14
+ try {
15
+ void response.body?.cancel().catch(() => undefined);
16
+ }
17
+ catch {
18
+ /* Best effort cancellation never exposes provider diagnostics. */
19
+ }
20
+ }
21
+ async function boundedJson(response, signal) {
22
+ if (signal.aborted) {
23
+ cancelBody(response);
24
+ throw new Error();
25
+ }
26
+ const reader = response.body?.getReader();
27
+ if (!reader)
28
+ throw new Error();
29
+ const cancel = () => {
30
+ void reader.cancel().catch(() => undefined);
31
+ };
32
+ signal.addEventListener('abort', cancel, { once: true });
33
+ const chunks = [];
34
+ let bytes = 0;
35
+ try {
36
+ for (;;) {
37
+ const chunk = await reader.read();
38
+ if (chunk.done)
39
+ break;
40
+ bytes += chunk.value.length;
41
+ if (bytes > MAX_RESPONSE_BYTES || signal.aborted)
42
+ throw new Error();
43
+ chunks.push(chunk.value);
44
+ }
45
+ return JSON.parse(Buffer.concat(chunks).toString('utf8'));
46
+ }
47
+ catch {
48
+ cancel();
49
+ throw new Error();
50
+ }
51
+ finally {
52
+ signal.removeEventListener('abort', cancel);
53
+ reader.releaseLock();
54
+ }
55
+ }
56
+ function responseInfo(value) {
57
+ if (value === undefined || value === null)
58
+ return undefined;
59
+ if (!object(value))
60
+ throw new Error('Cloudflare returned unsupported pagination.');
61
+ const info = {};
62
+ if (value.cursor !== undefined) {
63
+ if (typeof value.cursor !== 'string' ||
64
+ value.cursor.length > 4096 ||
65
+ /[\x00-\x1f\x7f]/.test(value.cursor))
66
+ throw new Error('Cloudflare returned an invalid pagination cursor.');
67
+ info.cursor = value.cursor;
68
+ }
69
+ for (const field of ['page', 'total_pages', 'count', 'per_page']) {
70
+ const entry = value[field];
71
+ if (entry !== undefined) {
72
+ if (typeof entry !== 'number' || !Number.isSafeInteger(entry) || entry < 0)
73
+ throw new Error('Cloudflare returned unsupported pagination.');
74
+ info[field] = entry;
75
+ }
76
+ }
77
+ return info;
78
+ }
79
+ /** Credentials stay in this closure. Fixed account paths, bounded response reads and
80
+ * a whole-request deadline apply to reads and mutations; mutations never retry. */
81
+ export async function cloudflareRequest(project, directory, run, env, options = {}) {
82
+ const account = project.accountId;
83
+ if (typeof account !== 'string' || !/^[a-f0-9]{32}$/.test(account))
84
+ throw new Error('Select a valid Cloudflare account before provider requests.');
85
+ const timeoutMs = options.timeoutMs ?? 30_000;
86
+ if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000)
87
+ throw new Error('Invalid bounded Cloudflare request deadline.');
88
+ const send = options.send ?? fetch;
3
89
  let credentials;
4
90
  try {
5
- credentials = JSON.parse(await run('pnpm', ['exec', 'wrangler', 'auth', 'token', '--json'], directory, env));
91
+ const raw = await run('pnpm', ['exec', 'wrangler', 'auth', 'token', '--json'], directory, env);
92
+ if (Buffer.byteLength(raw) > 64 * 1024)
93
+ throw new Error();
94
+ credentials = JSON.parse(raw);
6
95
  }
7
96
  catch {
8
97
  throw new Error('Cannot retrieve structured Wrangler credentials; update Wrangler and check authentication.');
9
98
  }
10
- if (!['oauth', 'api_token'].includes(credentials.type) ||
99
+ if (!object(credentials) ||
100
+ typeof credentials.type !== 'string' ||
101
+ !['oauth', 'api_token'].includes(credentials.type) ||
11
102
  typeof credentials.token !== 'string' ||
12
- !credentials.token)
103
+ !/^[\x21-\x7e]{1,16384}$/.test(credentials.token))
13
104
  throw new Error('Cloudflare operations require scoped API-token or Wrangler OAuth access.');
105
+ const token = credentials.token;
106
+ const prefix = `/client/v4/accounts/${account}`;
14
107
  return async (method, endpoint, body) => {
15
- if (!project.accountId ||
16
- !endpoint.startsWith('/') ||
17
- endpoint.includes('..') ||
18
- endpoint.includes('#'))
19
- throw new Error('Invalid account-scoped provider request.');
20
- let response;
108
+ let url;
21
109
  try {
22
- response = await fetch(`https://api.cloudflare.com/client/v4/accounts/${project.accountId}${endpoint}`, {
23
- method,
24
- headers: {
25
- Authorization: `Bearer ${credentials.token}`,
26
- 'Content-Type': 'application/json',
27
- },
28
- body: body === undefined ? undefined : JSON.stringify(body),
29
- redirect: 'error',
30
- signal: AbortSignal.timeout(30_000),
31
- });
110
+ if (typeof endpoint !== 'string')
111
+ throw new Error();
112
+ const decodedPath = decodeURIComponent(endpoint.split('?')[0]);
113
+ if (!['GET', 'POST', 'DELETE'].includes(method) ||
114
+ endpoint.length > 4096 ||
115
+ !endpoint.startsWith('/') ||
116
+ endpoint.startsWith('//') ||
117
+ /[\x00-\x20\x7f#\\]/.test(endpoint) ||
118
+ decodedPath.includes('..') ||
119
+ /[\x00-\x20\x7f#\\%]/.test(decodedPath))
120
+ throw new Error();
121
+ if (options.analytics) {
122
+ if (endpoint !== '/graphql' ||
123
+ method !== 'POST' ||
124
+ !object(body) ||
125
+ !object(body.variables) ||
126
+ body.variables.accountTag !== account)
127
+ throw new Error();
128
+ url = new URL('/client/v4/graphql', ORIGIN);
129
+ }
130
+ else {
131
+ url = new URL(`${prefix}${endpoint}`, ORIGIN);
132
+ if (url.origin !== ORIGIN || !url.pathname.startsWith(`${prefix}/`))
133
+ throw new Error();
134
+ }
32
135
  }
33
136
  catch {
34
- throw new Error('Cloudflare request failed; check connectivity and account permissions.');
137
+ throw new Error('Invalid account-scoped provider request.');
35
138
  }
36
- let data;
139
+ const controller = new AbortController();
140
+ let timer;
141
+ const timeout = new Promise((_resolve, reject) => {
142
+ timer = setTimeout(() => {
143
+ controller.abort();
144
+ reject(new Error('Cloudflare request deadline exceeded; inspect remote status before retrying.'));
145
+ }, timeoutMs);
146
+ });
37
147
  try {
38
- data = (await response.json());
148
+ return await Promise.race([
149
+ (async () => {
150
+ let response;
151
+ try {
152
+ response = await send(url.href, {
153
+ method,
154
+ headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
155
+ body: body === undefined ? undefined : JSON.stringify(body),
156
+ redirect: 'error',
157
+ signal: controller.signal,
158
+ });
159
+ }
160
+ catch {
161
+ throw new Error('Cloudflare request failed; check connectivity and account permissions.');
162
+ }
163
+ let data;
164
+ try {
165
+ data = await boundedJson(response, controller.signal);
166
+ }
167
+ catch {
168
+ throw new Error(`Cloudflare returned unsupported output (HTTP ${response.status}).`);
169
+ }
170
+ if (!object(data))
171
+ throw new Error(`Cloudflare returned unsupported output (HTTP ${response.status}).`);
172
+ if (!response.ok ||
173
+ (options.analytics
174
+ ? data.errors != null && (!Array.isArray(data.errors) || data.errors.length > 0)
175
+ : data.success !== true)) {
176
+ const codes = Array.isArray(data.errors)
177
+ ? data.errors
178
+ .slice(0, 20)
179
+ .filter(object)
180
+ .map((item) => item.code)
181
+ .filter((code) => typeof code === 'number' &&
182
+ Number.isSafeInteger(code) &&
183
+ code >= 0 &&
184
+ code <= 1_000_000)
185
+ .join(',')
186
+ : '';
187
+ throw new CloudflareRequestError(`Cloudflare operation failed (HTTP ${response.status}${codes ? `; codes ${codes}` : ''}). Check scoped permissions and service eligibility; no paid plan is activated automatically.`, response.status);
188
+ }
189
+ if (options.analytics)
190
+ return { result: data.data };
191
+ if (!Object.hasOwn(data, 'result'))
192
+ throw new Error('Cloudflare returned no operation result.');
193
+ return { result: data.result, result_info: responseInfo(data.result_info) };
194
+ })(),
195
+ timeout,
196
+ ]);
39
197
  }
40
- catch {
41
- throw new Error(`Cloudflare returned unsupported output (HTTP ${response.status}).`);
42
- }
43
- if (!response.ok || data.success !== true) {
44
- const codes = (data.errors ?? [])
45
- .map((item) => item.code)
46
- .filter((code) => typeof code === 'number')
47
- .join(',');
48
- throw new Error(`Cloudflare operation failed (HTTP ${response.status}${codes ? `; codes ${codes}` : ''}). Check scoped permissions and service eligibility; no paid plan is activated automatically.`);
198
+ finally {
199
+ clearTimeout(timer);
49
200
  }
50
- return { result: data.result, result_info: data.result_info };
51
201
  };
52
202
  }
53
203
  export async function listCloudflare(request, endpoint) {
54
204
  const result = [];
205
+ let bytes = 0;
55
206
  for (let page = 1; page <= 1000; page++) {
56
207
  const response = await request('GET', `${endpoint}${endpoint.includes('?') ? '&' : '?'}page=${page}&per_page=100`);
57
208
  if (!Array.isArray(response.result) ||
58
- response.result.some((item) => !item || typeof item !== 'object'))
209
+ response.result.length > 100 ||
210
+ response.result.some((item) => !object(item)))
59
211
  throw new Error('Unsupported provider resource list.');
212
+ try {
213
+ bytes += Buffer.byteLength(JSON.stringify(response.result));
214
+ }
215
+ catch {
216
+ throw new Error('Unsupported provider resource list.');
217
+ }
218
+ if (result.length + response.result.length > 10_000 || bytes > 10 * 1024 * 1024)
219
+ throw new Error('Provider resource listing exceeded its collection limit.');
60
220
  result.push(...response.result);
61
- const info = response.result_info;
221
+ const info = responseInfo(response.result_info);
62
222
  if (info?.total_pages !== undefined ? page >= info.total_pages : response.result.length < 100)
63
223
  return result;
64
224
  }
@@ -0,0 +1,21 @@
1
+ /** Machine-readable option semantics; help is presentation, never parser input. */
2
+ export interface CommandOption {
3
+ flag: string;
4
+ aliases?: readonly string[];
5
+ description: string;
6
+ value?: string;
7
+ arity?: 'required' | 'optional';
8
+ repeatable?: boolean;
9
+ hidden?: boolean;
10
+ }
11
+ export interface CommandDefinition {
12
+ description: string;
13
+ usage: string;
14
+ options: readonly CommandOption[];
15
+ examples: readonly string[];
16
+ note?: string;
17
+ }
18
+ export declare const GLOBAL_OPTIONS: readonly CommandOption[];
19
+ export declare function optionHelp(option: CommandOption): string;
20
+ export declare function commandDefinition(command: string | undefined): CommandDefinition | undefined;
21
+ export declare const COMMANDS: Readonly<Record<string, CommandDefinition>>;