@solidactions/cli 3.18.0 → 3.19.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.
package/README.md CHANGED
@@ -116,6 +116,9 @@ solidactions database list --kind duckdb --json
116
116
  solidactions database show analytics --json
117
117
  solidactions database ingest analytics data.parquet --table events --json
118
118
  solidactions database ingest analytics data.csv --table events --mode replace --json
119
+ solidactions database export analytics --table events --table orders --output ./snapshot
120
+ solidactions database export analytics --no-wait --json
121
+ solidactions database export analytics --resume <export-id>
119
122
  solidactions database drop-table analytics events --yes --json
120
123
  solidactions database optimize analytics --wait --json
121
124
  solidactions database connect analytics --json
@@ -134,7 +137,7 @@ for an analytical database (waits for provisioning unless `--no-wait`).
134
137
  `--from` only applies to the standard kind — `create --kind duckdb --from
135
138
  <file>` is rejected up front, before the database is created, since SQL
136
139
  import is meaningless for an analytical database; load one with `ingest`
137
- after creation. Analytical verbs — `ingest`, `drop-table`, `optimize`,
140
+ after creation. Analytical verbs — `ingest`, `export`, `drop-table`, `optimize`,
138
141
  `connect`, `wake` — only work against a `duckdb` database. `dump`, `pull`,
139
142
  `push`, `import`, and `exec` are for the standard (SQLite) kind only and
140
143
  refuse an analytical name with a one-line hint.
@@ -144,6 +147,17 @@ refuse an analytical name with a one-line hint.
144
147
  this is the normal, expected way to refresh an analytical table from an
145
148
  unattended pipeline, so it is not gated behind confirmation.
146
149
 
150
+ `database export <name>` takes a point-in-time analytical snapshot as one
151
+ ZSTD Parquet file per selected table plus `manifest.json`. With no `--table`
152
+ it exports every user table; repeat `--table` for an exact subset. The default
153
+ waits, verifies every byte length and SHA-256, and writes a new deterministic
154
+ directory. Use `--no-wait` to keep only the accepted export id, `--resume <id>`
155
+ after an interruption, `--output <directory>` to choose the target, and
156
+ `--replace` for non-interactive replacement of a non-reusable ready export.
157
+ `--json` provides machine-readable accepted or verified-terminal output.
158
+ Artifacts expire 24 hours after preparation completes. While the snapshot is prepared, new loads
159
+ pause and the awake database uses organisation credits.
160
+
147
161
  `query` is read-only SQL; use `exec` for writes. `schema`, `query`, `exec`,
148
162
  `pull --writable`, and imports use ephemeral scoped access held only in memory.
149
163
  No durable credential or credential sidecar is written locally.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "cli_name": "solidactions",
4
- "cli_version": "3.18.0",
4
+ "cli_version": "3.19.0",
5
5
  "global_options": [
6
6
  {
7
7
  "flags": "-V, --version",
@@ -1166,6 +1166,112 @@
1166
1166
  }
1167
1167
  ]
1168
1168
  },
1169
+ {
1170
+ "path": [
1171
+ "database",
1172
+ "export"
1173
+ ],
1174
+ "name": "export",
1175
+ "aliases": [],
1176
+ "description": "Export an analytical database snapshot as Parquet files and a manifest",
1177
+ "hidden": false,
1178
+ "arguments": [
1179
+ {
1180
+ "name": "name",
1181
+ "required": true,
1182
+ "variadic": false,
1183
+ "description": "Database name"
1184
+ }
1185
+ ],
1186
+ "options": [
1187
+ {
1188
+ "flags": "--table <table>",
1189
+ "long": "--table",
1190
+ "short": null,
1191
+ "description": "Export one table (repeatable)",
1192
+ "required": false,
1193
+ "value_required": true,
1194
+ "value_optional": false,
1195
+ "variadic": false,
1196
+ "negated": false,
1197
+ "hidden": false,
1198
+ "default": []
1199
+ },
1200
+ {
1201
+ "flags": "--output <directory>",
1202
+ "long": "--output",
1203
+ "short": null,
1204
+ "description": "Destination directory",
1205
+ "required": false,
1206
+ "value_required": true,
1207
+ "value_optional": false,
1208
+ "variadic": false,
1209
+ "negated": false,
1210
+ "hidden": false
1211
+ },
1212
+ {
1213
+ "flags": "--no-wait",
1214
+ "long": "--no-wait",
1215
+ "short": null,
1216
+ "description": "Print the accepted export id without waiting or downloading",
1217
+ "required": false,
1218
+ "value_required": false,
1219
+ "value_optional": false,
1220
+ "variadic": false,
1221
+ "negated": true,
1222
+ "hidden": false,
1223
+ "default": true
1224
+ },
1225
+ {
1226
+ "flags": "--resume <export-id>",
1227
+ "long": "--resume",
1228
+ "short": null,
1229
+ "description": "Resume an existing authorized export",
1230
+ "required": false,
1231
+ "value_required": true,
1232
+ "value_optional": false,
1233
+ "variadic": false,
1234
+ "negated": false,
1235
+ "hidden": false
1236
+ },
1237
+ {
1238
+ "flags": "--replace",
1239
+ "long": "--replace",
1240
+ "short": null,
1241
+ "description": "Replace a non-reusable ready export without prompting",
1242
+ "required": false,
1243
+ "value_required": false,
1244
+ "value_optional": false,
1245
+ "variadic": false,
1246
+ "negated": false,
1247
+ "hidden": false
1248
+ },
1249
+ {
1250
+ "flags": "--json",
1251
+ "long": "--json",
1252
+ "short": null,
1253
+ "description": "Output as JSON",
1254
+ "required": false,
1255
+ "value_required": false,
1256
+ "value_optional": false,
1257
+ "variadic": false,
1258
+ "negated": false,
1259
+ "hidden": false
1260
+ },
1261
+ {
1262
+ "flags": "-h, --help",
1263
+ "long": "--help",
1264
+ "short": "-h",
1265
+ "description": "display help for command",
1266
+ "required": false,
1267
+ "value_required": false,
1268
+ "value_optional": false,
1269
+ "variadic": false,
1270
+ "negated": false,
1271
+ "hidden": false
1272
+ }
1273
+ ]
1274
+ },
1169
1275
  {
1170
1276
  "path": [
1171
1277
  "database",
@@ -0,0 +1,512 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ var __importDefault = (this && this.__importDefault) || function (mod) {
36
+ return (mod && mod.__esModule) ? mod : { "default": mod };
37
+ };
38
+ Object.defineProperty(exports, "__esModule", { value: true });
39
+ exports.databaseExportWithConfig = databaseExportWithConfig;
40
+ exports.databaseExport = databaseExport;
41
+ const axios_1 = __importDefault(require("axios"));
42
+ const crypto_1 = require("crypto");
43
+ const fs_1 = __importDefault(require("fs"));
44
+ const path_1 = __importDefault(require("path"));
45
+ const readline = __importStar(require("readline"));
46
+ const promises_1 = require("stream/promises");
47
+ const stream_1 = require("stream");
48
+ const api_1 = require("../utils/api");
49
+ const database_data_plane_1 = require("../utils/database-data-plane");
50
+ const database_1 = require("./database");
51
+ function safeDownloadUrl(value) {
52
+ if (typeof value !== 'string')
53
+ return false;
54
+ try {
55
+ return ['http:', 'https:'].includes(new URL(value).protocol);
56
+ }
57
+ catch {
58
+ return false;
59
+ }
60
+ }
61
+ function refreshedDownload(listing, exportId, expected) {
62
+ if (!listing || listing.export_id !== exportId)
63
+ return null;
64
+ const fresh = expected.filename === 'manifest.json'
65
+ ? listing.manifest
66
+ : Array.isArray(listing.files) ? listing.files.find((file) => file.filename === expected.filename) : undefined;
67
+ if (!fresh || fresh.filename !== expected.filename || !safeDownloadUrl(fresh.url)
68
+ || fresh.table !== expected.table || fresh.rows !== expected.rows || fresh.bytes !== expected.bytes
69
+ || fresh.sha256 !== expected.sha256 || fresh.digest !== expected.digest)
70
+ return null;
71
+ return { ...expected, url: fresh.url };
72
+ }
73
+ class ExportCommandError extends database_data_plane_1.DatabaseOperationError {
74
+ exportId;
75
+ constructor(code, message, status, exportId) {
76
+ super(code, message, status);
77
+ this.exportId = exportId;
78
+ }
79
+ }
80
+ function normalizeTables(tables) {
81
+ if (!tables || tables.length === 0)
82
+ return undefined;
83
+ const normalized = [...new Set(tables.map((table) => table.trim().toLowerCase()))].sort();
84
+ for (const table of normalized) {
85
+ if (!/^[a-z][a-z0-9_]{0,62}$/.test(table)) {
86
+ throw new ExportCommandError('table_not_found', `Table "${table}" does not exist.`);
87
+ }
88
+ }
89
+ return normalized;
90
+ }
91
+ function stableMetadata(value) {
92
+ const row = value;
93
+ if (!row || typeof row.export_id !== 'string'
94
+ || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(row.export_id)
95
+ || typeof row.state !== 'string' || !['queued', 'running', 'finalizing', 'ready', 'failed', 'expired'].includes(row.state)
96
+ || typeof row.created_at !== 'string' || !Number.isFinite(Date.parse(row.created_at))
97
+ || (row.manifest_digest != null && (typeof row.manifest_digest !== 'string' || !/^[0-9a-f]{64}$/.test(row.manifest_digest)))) {
98
+ throw new ExportCommandError('upstream_unavailable', 'The export response was invalid.');
99
+ }
100
+ return row;
101
+ }
102
+ function applyRetryAfter(data, retryAfter) {
103
+ if (!data || typeof data !== 'object' || Array.isArray(data) || retryAfter === undefined)
104
+ return data;
105
+ const seconds = Number(retryAfter);
106
+ const retryAfterMs = Number.isFinite(seconds)
107
+ ? Math.max(0, seconds * 1_000)
108
+ : Math.max(0, Date.parse(String(retryAfter)) - Date.now());
109
+ if (Number.isFinite(retryAfterMs))
110
+ data.retry_after_ms = retryAfterMs;
111
+ return data;
112
+ }
113
+ function safeStem(name) {
114
+ return name.normalize('NFKD').replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'database';
115
+ }
116
+ function timestamp(createdAt) {
117
+ const parsed = new Date(createdAt);
118
+ if (!Number.isFinite(parsed.getTime()))
119
+ throw new ExportCommandError('upstream_unavailable', 'The export response was invalid.');
120
+ return parsed.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
121
+ }
122
+ function defaultDirectory(cwd, database, metadata) {
123
+ return path_1.default.join(cwd, `${safeStem(database)}-${timestamp(metadata.created_at)}-${metadata.export_id.replace(/-/g, '').slice(0, 8)}`);
124
+ }
125
+ async function directoryIsEmpty(directory) {
126
+ try {
127
+ return (await fs_1.default.promises.readdir(directory)).length === 0;
128
+ }
129
+ catch (error) {
130
+ if (error?.code === 'ENOENT')
131
+ return true;
132
+ throw error;
133
+ }
134
+ }
135
+ async function assertSafeDirectory(directory) {
136
+ const absolute = path_1.default.resolve(directory);
137
+ const parsed = path_1.default.parse(absolute);
138
+ let cursor = parsed.root;
139
+ for (const segment of absolute.slice(parsed.root.length).split(path_1.default.sep).filter(Boolean)) {
140
+ cursor = path_1.default.join(cursor, segment);
141
+ try {
142
+ const stat = await fs_1.default.promises.lstat(cursor);
143
+ if (stat.isSymbolicLink() || !stat.isDirectory()) {
144
+ throw new ExportCommandError('unsafe_destination', `Export destination is unsafe: ${directory}`);
145
+ }
146
+ }
147
+ catch (error) {
148
+ if (error?.code === 'ENOENT')
149
+ return;
150
+ throw error;
151
+ }
152
+ }
153
+ }
154
+ async function confirm(message) {
155
+ const input = readline.createInterface({ input: process.stdin, output: process.stdout });
156
+ return await new Promise((resolve) => input.question(`${message} [y/N] `, (answer) => {
157
+ input.close();
158
+ resolve(/^y(?:es)?$/i.test(answer.trim()));
159
+ }));
160
+ }
161
+ function teachingError(error) {
162
+ const value = error;
163
+ const id = value.exportId;
164
+ if (value.code === 'export_expired') {
165
+ throw new ExportCommandError('export_expired', 'This export has expired. Start a new export without --resume.', value.status, id);
166
+ }
167
+ if (value.code === 'export_in_progress') {
168
+ throw new ExportCommandError(value.code, `${value.message ?? 'An export is already being prepared.'}${id ? ` Rerun with --resume ${id}.` : ''}`, value.status, id);
169
+ }
170
+ throw error;
171
+ }
172
+ async function operation(config, body) {
173
+ try {
174
+ const response = await axios_1.default.post(`${config.host}/api/v1/databases`, body, {
175
+ headers: (0, api_1.getApiHeaders)(config, 'application/json'),
176
+ timeout: 30_000,
177
+ });
178
+ return applyRetryAfter(response.data, response.headers['retry-after']);
179
+ }
180
+ catch (error) {
181
+ const response = error?.response;
182
+ const code = typeof response?.data?.code === 'string' ? response.data.code : 'upstream_unavailable';
183
+ const message = typeof response?.data?.message === 'string' ? response.data.message : 'Database request failed.';
184
+ const id = response?.data?.export_id ?? response?.data?.current_export_id;
185
+ throw new ExportCommandError(code, message, response?.status, typeof id === 'string' ? id : undefined);
186
+ }
187
+ }
188
+ async function startExport(config, name, tables, replace, requestId) {
189
+ // This call is kept local instead of going through requestDatabaseOperation
190
+ // because replacement errors carry the authorized current export id needed
191
+ // for an actionable CLI decision.
192
+ try {
193
+ const response = await axios_1.default.post(`${config.host}/api/v1/databases`, {
194
+ operation: 'export', name, request_id: requestId, ...(tables ? { tables } : {}), replace,
195
+ }, { headers: (0, api_1.getApiHeaders)(config, 'application/json'), timeout: 30_000 });
196
+ return stableMetadata(applyRetryAfter(response.data, response.headers['retry-after']));
197
+ }
198
+ catch (error) {
199
+ const data = error?.response?.data;
200
+ const code = typeof data?.code === 'string' ? data.code : 'upstream_unavailable';
201
+ const message = typeof data?.message === 'string' ? data.message : 'Database request failed.';
202
+ const exportId = data?.current_export_id ?? data?.export_id;
203
+ throw new ExportCommandError(code, message, error?.response?.status, typeof exportId === 'string' ? exportId : undefined);
204
+ }
205
+ }
206
+ async function hashFile(file) {
207
+ try {
208
+ const stat = await fs_1.default.promises.lstat(file);
209
+ if (stat.isSymbolicLink() || !stat.isFile()) {
210
+ throw new ExportCommandError('unsafe_destination', `Existing export target is unsafe: ${file}`);
211
+ }
212
+ const hash = (0, crypto_1.createHash)('sha256');
213
+ let bytes = 0;
214
+ for await (const chunk of fs_1.default.createReadStream(file)) {
215
+ const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
216
+ bytes += buffer.length;
217
+ hash.update(buffer);
218
+ }
219
+ return { bytes, sha256: hash.digest('hex') };
220
+ }
221
+ catch (error) {
222
+ if (error?.code === 'ENOENT')
223
+ return null;
224
+ throw error;
225
+ }
226
+ }
227
+ async function assertResumeOwnership(directory, exportId) {
228
+ if (await directoryIsEmpty(directory))
229
+ return;
230
+ const manifestPath = path_1.default.join(directory, 'manifest.json');
231
+ try {
232
+ const stat = await fs_1.default.promises.lstat(manifestPath);
233
+ if (stat.isSymbolicLink() || !stat.isFile()) {
234
+ throw new ExportCommandError('unsafe_destination', `Existing export target is unsafe: ${manifestPath}`);
235
+ }
236
+ const manifest = JSON.parse(await fs_1.default.promises.readFile(manifestPath, 'utf8'));
237
+ if (manifest.export_id === exportId)
238
+ return;
239
+ }
240
+ catch (error) {
241
+ if (error instanceof ExportCommandError)
242
+ throw error;
243
+ // A non-empty directory is owned only by its verified export manifest.
244
+ }
245
+ throw new ExportCommandError('resume_destination_mismatch', `Export destination is not owned by ${exportId}: ${directory}`);
246
+ }
247
+ function manifestMismatch() {
248
+ throw new ExportCommandError('manifest_mismatch', 'The verified export manifest does not match the authenticated download listing.');
249
+ }
250
+ async function verifyManifestListing(manifestPath, exportId, downloads) {
251
+ let document;
252
+ try {
253
+ document = JSON.parse(await fs_1.default.promises.readFile(manifestPath, 'utf8'));
254
+ }
255
+ catch {
256
+ manifestMismatch();
257
+ }
258
+ const manifest = document;
259
+ if (!manifest || manifest.version !== 1 || manifest.export_id !== exportId || !Array.isArray(manifest.files))
260
+ manifestMismatch();
261
+ const apiFiles = new Map();
262
+ for (const file of downloads) {
263
+ if (apiFiles.has(file.filename))
264
+ manifestMismatch();
265
+ apiFiles.set(file.filename, file);
266
+ }
267
+ const manifestFiles = new Map();
268
+ for (const value of manifest.files) {
269
+ const file = value;
270
+ if (!file || typeof file.table !== 'string' || typeof file.filename !== 'string'
271
+ || !Number.isSafeInteger(file.rows) || (file.rows ?? -1) < 0
272
+ || !Number.isSafeInteger(file.bytes) || (file.bytes ?? -1) < 0
273
+ || typeof file.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(file.sha256)
274
+ || manifestFiles.has(file.filename))
275
+ manifestMismatch();
276
+ manifestFiles.set(file.filename, file);
277
+ }
278
+ if (manifestFiles.size !== apiFiles.size)
279
+ manifestMismatch();
280
+ for (const [filename, file] of manifestFiles) {
281
+ const api = apiFiles.get(filename);
282
+ if (!api || api.table !== file.table || api.filename !== file.filename || api.rows !== file.rows || api.bytes !== file.bytes || api.sha256 !== file.sha256)
283
+ manifestMismatch();
284
+ }
285
+ }
286
+ async function download(download, target, replace) {
287
+ const partial = `${target}.tmp-${(0, crypto_1.randomUUID)()}`;
288
+ const response = await axios_1.default.get(download.url, { responseType: 'stream', validateStatus: () => true });
289
+ if (response.status === 403) {
290
+ response.data.destroy?.();
291
+ const error = new Error('The download URL expired.');
292
+ error.status = 403;
293
+ throw error;
294
+ }
295
+ if (response.status < 200 || response.status >= 300) {
296
+ response.data.destroy?.();
297
+ throw new ExportCommandError('download_failed', `Download failed with HTTP ${response.status}.`);
298
+ }
299
+ const hash = (0, crypto_1.createHash)('sha256');
300
+ let bytes = 0;
301
+ const meter = new stream_1.Transform({ transform(chunk, _encoding, callback) {
302
+ bytes += chunk.length;
303
+ hash.update(chunk);
304
+ callback(null, chunk);
305
+ } });
306
+ try {
307
+ await (0, promises_1.pipeline)(response.data, meter, fs_1.default.createWriteStream(partial, { flags: 'wx' }));
308
+ const sha256 = hash.digest('hex');
309
+ // Content-Length describes the encoded wire body while Axios hands the
310
+ // stream to us after transport decompression. It is also absent for
311
+ // chunked responses, so it is not an integrity signal here.
312
+ if (download.bytes !== undefined && download.bytes !== bytes)
313
+ throw new ExportCommandError('download_corrupt', `Byte-length verification failed for ${download.filename}.`);
314
+ const expectedDigest = download.sha256 ?? download.digest;
315
+ if (!expectedDigest || !/^[0-9a-f]{64}$/.test(expectedDigest) || sha256 !== expectedDigest)
316
+ throw new ExportCommandError('download_corrupt', `SHA-256 verification failed for ${download.filename}.`);
317
+ if (!replace) {
318
+ try {
319
+ await fs_1.default.promises.lstat(target);
320
+ throw new ExportCommandError('output_exists', `The CLI will not overwrite ${target}.`);
321
+ }
322
+ catch (error) {
323
+ if (error?.code !== 'ENOENT')
324
+ throw error;
325
+ }
326
+ }
327
+ await fs_1.default.promises.rename(partial, target);
328
+ return { bytes, sha256 };
329
+ }
330
+ catch (error) {
331
+ await fs_1.default.promises.rm(partial, { force: true });
332
+ throw error;
333
+ }
334
+ }
335
+ async function databaseExportWithConfig(name, options, config, dependencies = {}) {
336
+ const stdout = dependencies.stdout ?? console.log;
337
+ const stderr = dependencies.stderr ?? console.error;
338
+ const cwd = dependencies.cwd ?? process.cwd();
339
+ const tables = normalizeTables(options.table);
340
+ if (options.resume && tables)
341
+ throw new ExportCommandError('invalid_arguments', '--table cannot be combined with --resume. A resumed shared export downloads the full artifact.');
342
+ if (options.resume && options.replace)
343
+ throw new ExportCommandError('invalid_arguments', '--replace cannot be combined with --resume. Resume never creates or replaces an export.');
344
+ if (options.resume && options.wait === false)
345
+ throw new ExportCommandError('invalid_arguments', '--no-wait cannot be combined with --resume. Resume waits for and downloads the existing export.');
346
+ const database = await (0, database_1.requestDatabaseRecord)(name, config);
347
+ if (database.kind !== 'duckdb')
348
+ throw new ExportCommandError('kind_mismatch', `"${name}" is not an analytical database — \`database export\` only works on analytical (duckdb) databases.`);
349
+ let metadata;
350
+ if (options.resume) {
351
+ try {
352
+ metadata = stableMetadata(await operation(config, { operation: 'export_status', name, export_id: options.resume }));
353
+ }
354
+ catch (error) {
355
+ teachingError(error);
356
+ }
357
+ }
358
+ else {
359
+ const requestId = (0, crypto_1.randomUUID)();
360
+ if (!options.json)
361
+ stderr('Preparing export… New loads pause while the snapshot is prepared and compute uses organisation credits.');
362
+ try {
363
+ metadata = await startExport(config, name, tables, options.replace === true, requestId);
364
+ }
365
+ catch (error) {
366
+ const value = error;
367
+ if (value.code === 'export_replace_required') {
368
+ if (options.replace)
369
+ throw error;
370
+ if (!(dependencies.isTTY ?? process.stdin.isTTY === true)) {
371
+ throw new ExportCommandError(value.code, `A ready export must be replaced. Rerun with --replace.${value.exportId ? ` Current export: ${value.exportId}.` : ''}`, value.status, value.exportId);
372
+ }
373
+ if (!await (dependencies.confirm ?? confirm)('This replaces your current export. Continue?')) {
374
+ stdout('Cancelled.');
375
+ return { export_id: value.exportId ?? '', state: 'cancelled', created_at: '', directory: '', files: [] };
376
+ }
377
+ metadata = await startExport(config, name, tables, true, requestId);
378
+ }
379
+ else {
380
+ teachingError(error);
381
+ }
382
+ }
383
+ }
384
+ if (options.wait === false) {
385
+ if (options.json)
386
+ stdout(JSON.stringify(metadata, null, 2));
387
+ else
388
+ stdout(`Export accepted: ${metadata.export_id}`);
389
+ return { ...metadata, directory: '', files: [] };
390
+ }
391
+ while (!['ready', 'failed', 'expired'].includes(metadata.state)) {
392
+ await (dependencies.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(metadata.retry_after_ms ?? 5_000);
393
+ try {
394
+ metadata = stableMetadata(await operation(config, { operation: 'export_status', name, export_id: metadata.export_id }));
395
+ }
396
+ catch (error) {
397
+ teachingError(error);
398
+ }
399
+ }
400
+ if (metadata.state === 'expired')
401
+ throw new ExportCommandError('export_expired', 'This export has expired. Start a new export without --resume.', 410, metadata.export_id);
402
+ if (metadata.state === 'failed')
403
+ throw new ExportCommandError(metadata.error_code ?? 'export_failed', `${metadata.error_message ?? 'The export failed.'} Start a new export without --resume.`, undefined, metadata.export_id);
404
+ if (!metadata.manifest_digest) {
405
+ metadata = stableMetadata(await operation(config, { operation: 'export_status', name, export_id: metadata.export_id }));
406
+ }
407
+ if (!metadata.manifest_digest || !/^[0-9a-f]{64}$/.test(metadata.manifest_digest))
408
+ throw new ExportCommandError('upstream_unavailable', 'The ready export response was invalid.');
409
+ let listing;
410
+ try {
411
+ listing = await operation(config, { operation: 'export_downloads', name, export_id: metadata.export_id, ...(tables ? { tables } : {}) });
412
+ }
413
+ catch (error) {
414
+ teachingError(error);
415
+ }
416
+ if (!listing || listing.export_id !== metadata.export_id || !listing.manifest
417
+ || listing.manifest.filename !== 'manifest.json'
418
+ || listing.manifest.digest !== metadata.manifest_digest
419
+ || !safeDownloadUrl(listing.manifest.url) || !Array.isArray(listing.files))
420
+ throw new ExportCommandError('upstream_unavailable', 'The export download response was invalid.');
421
+ for (const file of listing.files) {
422
+ if (typeof file.table !== 'string' || !/^[a-z][a-z0-9_]{0,62}$/.test(file.table)
423
+ || file.filename !== `${file.table}.parquet`
424
+ || !safeDownloadUrl(file.url) || !Number.isSafeInteger(file.bytes) || (file.bytes ?? -1) < 0
425
+ || !Number.isSafeInteger(file.rows) || (file.rows ?? -1) < 0
426
+ || typeof file.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(file.sha256))
427
+ throw new ExportCommandError('upstream_unavailable', 'The export download response was invalid.');
428
+ }
429
+ const wanted = [{ ...listing.manifest, digest: metadata.manifest_digest }, ...listing.files];
430
+ const directory = options.output ? path_1.default.resolve(cwd, options.output) : defaultDirectory(cwd, database.name, metadata);
431
+ await assertSafeDirectory(directory);
432
+ if (!options.resume && !await directoryIsEmpty(directory))
433
+ throw new ExportCommandError('output_not_empty', `Export destination must be absent or empty: ${directory}`);
434
+ if (options.resume)
435
+ await assertResumeOwnership(directory, metadata.export_id);
436
+ await fs_1.default.promises.mkdir(directory, { recursive: true });
437
+ await assertSafeDirectory(directory);
438
+ if (options.resume) {
439
+ for (const item of wanted)
440
+ await fs_1.default.promises.rm(path_1.default.join(directory, `${item.filename}.part`), { force: true });
441
+ }
442
+ const completed = [];
443
+ for (const item of wanted) {
444
+ if (!/^[a-z][a-z0-9_]{0,62}\.parquet$/.test(item.filename) && item.filename !== 'manifest.json')
445
+ throw new ExportCommandError('unsafe_filename', 'The export contained an unsafe filename.');
446
+ const target = path_1.default.join(directory, item.filename);
447
+ const expected = item.sha256 ?? item.digest;
448
+ const existing = options.resume ? await hashFile(target) : null;
449
+ if (existing && existing.bytes === (item.bytes ?? existing.bytes) && existing.sha256 === expected) {
450
+ completed.push({ ...(item.table ? { table: item.table } : {}), filename: item.filename, path: target, ...existing });
451
+ if (!options.json)
452
+ stdout(`Verified ${item.filename} (${existing.bytes} bytes)`);
453
+ if (item.filename === 'manifest.json')
454
+ await verifyManifestListing(target, metadata.export_id, wanted.slice(1));
455
+ continue;
456
+ }
457
+ if (!options.json)
458
+ stderr(`Downloading ${item.filename}…`);
459
+ // Mint immediately before each object, never batch URLs ahead of a long download.
460
+ try {
461
+ listing = await operation(config, { operation: 'export_downloads', name, export_id: metadata.export_id, ...(tables ? { tables } : {}) });
462
+ }
463
+ catch (error) {
464
+ if (error?.code === 'export_expired')
465
+ throw new ExportCommandError('export_superseded', 'This export expired or was superseded while downloading. Start a new export.', 409, metadata.export_id);
466
+ throw error;
467
+ }
468
+ const fresh = refreshedDownload(listing, metadata.export_id, item);
469
+ if (!fresh)
470
+ throw new ExportCommandError('export_superseded', 'This export was superseded while downloading. Start a new export.', 409, metadata.export_id);
471
+ try {
472
+ const verified = await download(fresh, target, options.resume !== undefined);
473
+ completed.push({ ...(item.table ? { table: item.table } : {}), filename: item.filename, path: target, ...verified });
474
+ if (!options.json)
475
+ stdout(`Downloaded ${item.filename} (${verified.bytes} bytes)`);
476
+ if (item.filename === 'manifest.json')
477
+ await verifyManifestListing(target, metadata.export_id, wanted.slice(1));
478
+ }
479
+ catch (error) {
480
+ if (error?.status !== 403)
481
+ throw new ExportCommandError(error.code ?? 'download_failed', `${error.message ?? 'Download failed.'} Completed files were kept. Rerun with --resume ${metadata.export_id}.`, error.status, metadata.export_id);
482
+ try {
483
+ const refreshed = await operation(config, { operation: 'export_downloads', name, export_id: metadata.export_id, ...(tables ? { tables } : {}) });
484
+ const retry = refreshedDownload(refreshed, metadata.export_id, item);
485
+ if (!retry)
486
+ throw new ExportCommandError('export_superseded', 'This export was superseded while downloading. Start a new export.', 409, metadata.export_id);
487
+ const verified = await download(retry, target, options.resume !== undefined);
488
+ completed.push({ ...(item.table ? { table: item.table } : {}), filename: item.filename, path: target, ...verified });
489
+ if (!options.json)
490
+ stdout(`Downloaded ${item.filename} (${verified.bytes} bytes)`);
491
+ if (item.filename === 'manifest.json')
492
+ await verifyManifestListing(target, metadata.export_id, wanted.slice(1));
493
+ }
494
+ catch (refreshError) {
495
+ if (refreshError?.code === 'export_expired')
496
+ throw new ExportCommandError('export_superseded', 'This export expired or was superseded while downloading. Start a new export.', 409, metadata.export_id);
497
+ throw refreshError;
498
+ }
499
+ }
500
+ }
501
+ const result = { ...metadata, directory, files: completed };
502
+ if (options.json)
503
+ stdout(JSON.stringify(result, null, 2));
504
+ else {
505
+ stdout(`Export ready until ${metadata.expires_at ?? 'unknown'}.`);
506
+ stdout(`Saved to ${directory}`);
507
+ }
508
+ return result;
509
+ }
510
+ async function databaseExport(name, options) {
511
+ await databaseExportWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)());
512
+ }
package/dist/index.js CHANGED
@@ -94,6 +94,7 @@ const state_1 = require("./commands/state");
94
94
  const workflow_view_1 = require("./commands/workflow-view");
95
95
  const database_1 = require("./commands/database");
96
96
  const database_push_1 = require("./commands/database-push");
97
+ const database_export_1 = require("./commands/database-export");
97
98
  const config_1 = require("./utils/config");
98
99
  const mutating_commands_1 = require("./utils/mutating-commands");
99
100
  const agent_freshness_1 = require("./utils/agent-freshness");
@@ -379,6 +380,23 @@ database
379
380
  .action(async (name, file, options) => {
380
381
  await (0, database_1.databaseIngest)(name, file, { table: options.table, mode: options.mode, batchId: options.batchId, json: options.json });
381
382
  });
383
+ database
384
+ .command('export')
385
+ .description('Export an analytical database snapshot as Parquet files and a manifest')
386
+ .argument('<name>', 'Database name')
387
+ .option('--table <table>', 'Export one table (repeatable)', (value, previous = []) => [...previous, value], [])
388
+ .option('--output <directory>', 'Destination directory')
389
+ .option('--no-wait', 'Print the accepted export id without waiting or downloading')
390
+ .option('--resume <export-id>', 'Resume an existing authorized export')
391
+ .option('--replace', 'Replace a non-reusable ready export without prompting')
392
+ .option('--json', 'Output as JSON')
393
+ .addHelpText('after', `
394
+ Exports contain Parquet files and manifest.json only. New exports require an absent or empty destination; downloads never overwrite files.
395
+ Downloads verify the manifest against the authenticated API manifest digest, then verify each file byte length and SHA-256. Signed links are refreshed once on expiry.
396
+ Resume an interrupted download with --resume <export-id>. JSON output never includes signed URLs.`)
397
+ .action(async (name, options) => {
398
+ await (0, database_export_1.databaseExport)(name, options);
399
+ });
382
400
  database
383
401
  .command('drop-table')
384
402
  .description('Delete one table from an analytical database and free its space')
@@ -50,6 +50,9 @@ exports.MUTATING_COMMANDS = new Set([
50
50
  'database import',
51
51
  'database push',
52
52
  'database ingest',
53
+ // Export creates durable operation rows and temporary R2 objects and may
54
+ // wake billed compute, even though authorization is read-capability based.
55
+ 'database export',
53
56
  'database drop-table',
54
57
  // `optimize` dispatches a real server-side operation that rewrites the
55
58
  // database's stored files (`StartOptimizeOperation` — a job, not just a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solidactions/cli",
3
- "version": "3.18.0",
3
+ "version": "3.19.0",
4
4
  "description": "SolidActions CLI - Deploy and manage workflow automation",
5
5
  "main": "dist/index.js",
6
6
  "bin": {