@solidactions/cli 3.16.0 → 3.17.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.
@@ -37,8 +37,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
37
37
  };
38
38
  Object.defineProperty(exports, "__esModule", { value: true });
39
39
  exports.parseDatabaseImportSql = void 0;
40
+ exports.formatByteSize = formatByteSize;
40
41
  exports.databaseListWithConfig = databaseListWithConfig;
41
42
  exports.databaseCreateWithConfig = databaseCreateWithConfig;
43
+ exports.requestDatabaseRecord = requestDatabaseRecord;
44
+ exports.refuseIfAnalytical = refuseIfAnalytical;
45
+ exports.databaseShowWithConfig = databaseShowWithConfig;
42
46
  exports.databaseImportWithConfig = databaseImportWithConfig;
43
47
  exports.databaseDeleteWithConfig = databaseDeleteWithConfig;
44
48
  exports.databaseUndeleteWithConfig = databaseUndeleteWithConfig;
@@ -49,6 +53,7 @@ exports.databaseDumpWithConfig = databaseDumpWithConfig;
49
53
  exports.databasePullWithConfig = databasePullWithConfig;
50
54
  exports.databaseList = databaseList;
51
55
  exports.databaseCreate = databaseCreate;
56
+ exports.databaseShow = databaseShow;
52
57
  exports.databaseDelete = databaseDelete;
53
58
  exports.databaseUndelete = databaseUndelete;
54
59
  exports.databaseSchema = databaseSchema;
@@ -57,6 +62,17 @@ exports.databaseExec = databaseExec;
57
62
  exports.databaseDump = databaseDump;
58
63
  exports.databasePull = databasePull;
59
64
  exports.databaseImport = databaseImport;
65
+ exports.databaseIngestWithConfig = databaseIngestWithConfig;
66
+ exports.databaseIngest = databaseIngest;
67
+ exports.databaseDropTableWithConfig = databaseDropTableWithConfig;
68
+ exports.databaseDropTable = databaseDropTable;
69
+ exports.databaseOptimizeWithConfig = databaseOptimizeWithConfig;
70
+ exports.databaseOptimize = databaseOptimize;
71
+ exports.databaseConnectWithConfig = databaseConnectWithConfig;
72
+ exports.databaseConnect = databaseConnect;
73
+ exports.databaseWakeWithConfig = databaseWakeWithConfig;
74
+ exports.databaseWake = databaseWake;
75
+ const axios_1 = __importDefault(require("axios"));
60
76
  const fs_1 = __importDefault(require("fs"));
61
77
  const path_1 = __importDefault(require("path"));
62
78
  const readline = __importStar(require("readline"));
@@ -70,6 +86,7 @@ var database_sql_import_2 = require("../utils/database-sql-import");
70
86
  Object.defineProperty(exports, "parseDatabaseImportSql", { enumerable: true, get: function () { return database_sql_import_2.parseDatabaseImportSql; } });
71
87
  const database_sql_import_runner_1 = require("../utils/database-sql-import-runner");
72
88
  const table_1 = require("../utils/table");
89
+ const database_ingest_digest_1 = require("../utils/database-ingest-digest");
73
90
  function defaultConfirmation(message) {
74
91
  const input = readline.createInterface({ input: process.stdin, output: process.stdout });
75
92
  return new Promise((resolve) => {
@@ -108,6 +125,7 @@ function resolveDependencies(dependencies) {
108
125
  sleep: dependencies.sleep ?? ((milliseconds) => new Promise((resolve) => {
109
126
  setTimeout(resolve, milliseconds);
110
127
  })),
128
+ put: dependencies.put ?? axios_1.default.put,
111
129
  };
112
130
  }
113
131
  function requestDependencies(dependencies) {
@@ -131,47 +149,89 @@ function stableDatabaseRecord(database) {
131
149
  || typeof database.status !== 'string'
132
150
  || typeof database.size_bytes !== 'number'
133
151
  || (database.deleted_at !== null && typeof database.deleted_at !== 'string')
134
- || (database.purge_at !== null && typeof database.purge_at !== 'string')) {
152
+ || (database.purge_at !== null && typeof database.purge_at !== 'string')
153
+ || (database.kind !== 'libsql' && database.kind !== 'duckdb')
154
+ || (database.activity !== undefined && typeof database.activity !== 'string')
155
+ || (database.size_limit_bytes !== undefined && typeof database.size_limit_bytes !== 'number')
156
+ || (database.over_cap !== undefined && typeof database.over_cap !== 'boolean')
157
+ || (database.table_count !== undefined && typeof database.table_count !== 'number')
158
+ || (database.last_loaded_at !== undefined
159
+ && database.last_loaded_at !== null
160
+ && typeof database.last_loaded_at !== 'string')
161
+ || (database.last_optimized_at !== undefined
162
+ && database.last_optimized_at !== null
163
+ && typeof database.last_optimized_at !== 'string')
164
+ || (database.created_at !== undefined && typeof database.created_at !== 'string')
165
+ || (database.updated_at !== undefined && typeof database.updated_at !== 'string')) {
135
166
  throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
136
167
  }
168
+ // A missing or unrecognized `kind` is rejected above (upstream_unavailable)
169
+ // rather than defaulted — silently treating an unknown kind as 'libsql'
170
+ // would make analytical-only refusals (read-only, dump) fail open (#1700 R10).
171
+ const kind = database.kind;
137
172
  return {
138
173
  ...(database.id === undefined ? {} : { id: database.id }),
139
174
  name: database.name,
175
+ kind,
140
176
  status: database.status,
177
+ ...(database.activity === undefined ? {} : { activity: database.activity }),
141
178
  deleted_at: database.deleted_at,
142
179
  purge_at: database.purge_at,
143
180
  size_bytes: database.size_bytes,
181
+ ...(database.size_limit_bytes === undefined ? {} : { size_limit_bytes: database.size_limit_bytes }),
182
+ ...(database.over_cap === undefined ? {} : { over_cap: database.over_cap }),
183
+ ...(database.table_count === undefined ? {} : { table_count: database.table_count }),
184
+ ...(database.last_loaded_at === undefined ? {} : { last_loaded_at: database.last_loaded_at }),
185
+ ...(database.last_optimized_at === undefined ? {} : { last_optimized_at: database.last_optimized_at }),
186
+ ...(database.created_at === undefined ? {} : { created_at: database.created_at }),
187
+ ...(database.updated_at === undefined ? {} : { updated_at: database.updated_at }),
144
188
  };
145
189
  }
146
190
  function stableDatabaseResponse(data) {
147
191
  return { database: stableDatabaseRecord(data?.database) };
148
192
  }
193
+ function stableQuota(quota) {
194
+ if (!quota
195
+ || typeof quota.used !== 'number'
196
+ || typeof quota.limit !== 'number'
197
+ || (quota.scope !== 'workspace' && quota.scope !== 'org')) {
198
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
199
+ }
200
+ return { used: quota.used, limit: quota.limit, scope: quota.scope };
201
+ }
149
202
  function stableListResponse(data) {
150
- if (!data
151
- || !Array.isArray(data.databases)
152
- || typeof data.quota?.used !== 'number'
153
- || typeof data.quota?.limit !== 'number') {
203
+ if (!data || !Array.isArray(data.databases)) {
154
204
  throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
155
205
  }
156
206
  return {
157
207
  databases: data.databases.map(stableDatabaseRecord),
158
208
  quota: {
159
- used: data.quota.used,
160
- limit: data.quota.limit,
209
+ libsql: stableQuota(data.quota?.libsql),
210
+ duckdb: stableQuota(data.quota?.duckdb),
161
211
  },
162
212
  };
163
213
  }
164
214
  function databaseRows(databases) {
165
215
  return databases.map((database) => [
166
216
  database.name,
217
+ database.kind,
167
218
  database.status,
168
- String(database.size_bytes),
219
+ database.kind === 'duckdb' ? (database.activity ?? '-') : '-',
220
+ database.kind === 'duckdb'
221
+ ? `${formatByteSize(database.size_bytes)} / ${formatByteSize(database.size_limit_bytes ?? 0)}`
222
+ : String(database.size_bytes),
169
223
  database.deleted_at ?? '-',
170
224
  database.purge_at ?? '-',
171
225
  ]);
172
226
  }
173
227
  function renderDatabaseTable(databases) {
174
- return (0, table_1.renderTable)(['NAME', 'STATUS', 'SIZE (BYTES)', 'DELETED AT', 'PURGE AT'], databaseRows(databases)).join('\n');
228
+ return (0, table_1.renderTable)(['NAME', 'KIND', 'STATUS', 'ACTIVITY', 'SIZE', 'DELETED AT', 'PURGE AT'], databaseRows(databases)).join('\n');
229
+ }
230
+ function renderQuota(quota) {
231
+ return [
232
+ `Quota: libsql ${quota.libsql.used} / ${quota.libsql.limit} (${quota.libsql.scope})`,
233
+ ` duckdb ${quota.duckdb.used} / ${quota.duckdb.limit} (${quota.duckdb.scope})`,
234
+ ].join('\n');
175
235
  }
176
236
  function renderMutation(operation, database) {
177
237
  const verb = operation === 'create'
@@ -331,6 +391,81 @@ function renderSchema(schema) {
331
391
  }
332
392
  return sections.join('\n\n');
333
393
  }
394
+ function stableAnalyticalSchemaColumn(column) {
395
+ if (!column || typeof column.name !== 'string' || typeof column.type !== 'string') {
396
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
397
+ }
398
+ return { name: column.name, type: column.type };
399
+ }
400
+ function stableAnalyticalSchema(data) {
401
+ if (!data || !Array.isArray(data.tables)) {
402
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
403
+ }
404
+ return {
405
+ tables: data.tables.map((table) => {
406
+ if (!table
407
+ || typeof table.name !== 'string'
408
+ || !Array.isArray(table.columns)
409
+ || typeof table.row_count !== 'number'
410
+ || (table.last_loaded_at !== null && typeof table.last_loaded_at !== 'string')) {
411
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
412
+ }
413
+ return {
414
+ name: table.name,
415
+ columns: table.columns.map(stableAnalyticalSchemaColumn),
416
+ row_count: table.row_count,
417
+ last_loaded_at: table.last_loaded_at,
418
+ };
419
+ }),
420
+ };
421
+ }
422
+ function renderAnalyticalSchema(schema) {
423
+ if (schema.tables.length === 0) {
424
+ return 'No tables.';
425
+ }
426
+ return schema.tables.map((table) => {
427
+ const columns = table.columns.map((column) => `${column.name} (${column.type})`).join(', ');
428
+ return `${table.name} — ${table.row_count} rows, last loaded ${table.last_loaded_at ?? 'never'}\n ${columns}`;
429
+ }).join('\n\n');
430
+ }
431
+ /** "1.2 GiB", "512.0 MiB", "900 B" — used by `show`, `list`, and `ingest`. */
432
+ function formatByteSize(bytes) {
433
+ // Binary (1024-based) division — the units must say Gi/Mi/Ki, not G/M/K
434
+ // (spec:451 writes "1 GiB"; the old "GB"/"MB"/"KB" labels rendered the
435
+ // 1 GiB cap as "1.0 GB", which is the SI-decimal unit for a different
436
+ // number of bytes).
437
+ if (bytes >= 1_073_741_824)
438
+ return `${(bytes / 1_073_741_824).toFixed(1)} GiB`;
439
+ if (bytes >= 1_048_576)
440
+ return `${(bytes / 1_048_576).toFixed(1)} MiB`;
441
+ if (bytes >= 1024)
442
+ return `${(bytes / 1024).toFixed(1)} KiB`;
443
+ return `${bytes} B`;
444
+ }
445
+ // The analytical (DuckDB) kind is Beta on every surface — this label is the
446
+ // canonical rendering; standard (libSQL) rows keep the plain kind value.
447
+ function kindLabel(kind) {
448
+ return kind === 'duckdb' ? 'Analytical · DuckDB (Beta)' : kind;
449
+ }
450
+ function renderShow(database) {
451
+ const lines = [
452
+ `Name: ${database.name}`,
453
+ `Kind: ${kindLabel(database.kind)}`,
454
+ `Status: ${database.status}`,
455
+ ];
456
+ if (database.kind === 'duckdb') {
457
+ lines.push(`Activity: ${database.activity ?? 'unknown'}`);
458
+ lines.push(`Size: ${formatByteSize(database.size_bytes)} of ${formatByteSize(database.size_limit_bytes ?? 0)}`);
459
+ lines.push(`Tables: ${database.table_count ?? 0}`);
460
+ lines.push(`Last loaded: ${database.last_loaded_at ?? 'never'}`);
461
+ lines.push(`Last optimized: ${database.last_optimized_at ?? 'never'}`);
462
+ }
463
+ else {
464
+ lines.push(`Size: ${formatByteSize(database.size_bytes)}`);
465
+ }
466
+ lines.push(`Created: ${database.created_at ?? '-'}`);
467
+ return lines.join('\n');
468
+ }
334
469
  const INCOMPLETE_DUMP_MARKER = '-- DOWNLOAD INCOMPLETE';
335
470
  const DUMP_TAIL_BYTES = 4096;
336
471
  const PULL_ATTEMPTS = 3;
@@ -684,19 +819,60 @@ async function finalizeReplica(io, temp, target, createClient) {
684
819
  }
685
820
  async function databaseListWithConfig(options, config, dependencies = {}) {
686
821
  const io = resolveDependencies(dependencies);
822
+ // The server's `list` operation takes no `kind` parameter — CliDatabaseRequest
823
+ // prohibits it on anything but `create` — so the filter is applied here,
824
+ // client-side, against the full row set.
825
+ if (options.kind !== undefined && options.kind !== 'libsql' && options.kind !== 'duckdb') {
826
+ throw new database_data_plane_1.DatabaseOperationError('invalid_kind', `--kind must be "libsql" or "duckdb" (received "${options.kind}").`);
827
+ }
687
828
  const data = stableListResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'list' }, requestDependencies(io)));
829
+ const databases = options.kind
830
+ ? data.databases.filter((database) => database.kind === options.kind)
831
+ : data.databases;
688
832
  if (options.json) {
689
- writeJson(io.stdout, data);
833
+ writeJson(io.stdout, options.kind ? { ...data, databases } : data);
690
834
  return;
691
835
  }
692
- io.stdout(`${renderDatabaseTable(data.databases)}\nQuota: ${data.quota.used} / ${data.quota.limit}`);
836
+ io.stdout(`${renderDatabaseTable(databases)}\n${renderQuota(data.quota)}`);
693
837
  }
838
+ const CREATE_POLL_INTERVAL_MS = 2_000;
839
+ const CREATE_POLL_TIMEOUT_MS = 5 * 60_000;
694
840
  async function databaseCreateWithConfig(name, options, config, dependencies = {}) {
695
841
  const io = resolveDependencies(dependencies);
842
+ if (options.kind !== undefined && options.kind !== 'libsql' && options.kind !== 'duckdb') {
843
+ throw new database_data_plane_1.DatabaseOperationError('invalid_kind', `--kind must be "libsql" or "duckdb" (received "${options.kind}").`);
844
+ }
845
+ const kind = options.kind === 'duckdb' ? 'duckdb' : 'libsql';
846
+ if (kind === 'duckdb' && options.from) {
847
+ // C-2: reject before the create POST. An analytical database is a
848
+ // billable, org-quota-scoped resource (1 per org on Free) — letting
849
+ // this combination reach the server means it gets created, waits on
850
+ // provisioning, and only then fails the SQL import with a generic
851
+ // `import_failed`, leaving the database behind consuming quota.
852
+ throw new database_data_plane_1.DatabaseOperationError('invalid_flag_combination', '--from is not supported with --kind duckdb; SQL import only applies to libsql databases. Create the database, then load data with `solidactions database ingest`.');
853
+ }
696
854
  const preparedSource = options.from && !io.importDatabase
697
855
  ? await (0, database_sql_import_runner_1.prepareDatabaseImportSource)(options.from, io.cwd, io.filesystem)
698
856
  : undefined;
699
- const data = stableDatabaseResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'create', name }, requestDependencies(io)));
857
+ let data = stableDatabaseResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'create', name, kind }, requestDependencies(io)));
858
+ if (kind === 'duckdb' && options.wait !== false && data.database.status === 'provisioning') {
859
+ if (!options.json) {
860
+ io.stdout(`Provisioning ${kindLabel(kind)} database "${data.database.name}"… this can take about a minute.`);
861
+ }
862
+ const deadline = io.now() + CREATE_POLL_TIMEOUT_MS;
863
+ let record = data.database;
864
+ while (record.status === 'provisioning' && io.now() < deadline) {
865
+ await io.sleep(CREATE_POLL_INTERVAL_MS);
866
+ record = await requestDatabaseRecord(name, config, dependencies);
867
+ }
868
+ data = { database: record };
869
+ if (record.status !== 'ready') {
870
+ if (record.status === 'provisioning') {
871
+ throw new database_data_plane_1.DatabaseOperationError('provisioning_timeout', `Database "${name}" is still provisioning after ${Math.round(CREATE_POLL_TIMEOUT_MS / 60_000)} minute(s). It remains in place; check status with \`solidactions database show ${name}\`.`);
872
+ }
873
+ throw new database_data_plane_1.DatabaseOperationError('provisioning_failed', `Database "${name}" failed to provision (status: ${record.status}). Check \`solidactions database show ${name}\` for details.`);
874
+ }
875
+ }
700
876
  if (options.from) {
701
877
  try {
702
878
  if (io.importDatabase) {
@@ -732,8 +908,39 @@ async function databaseCreateWithConfig(name, options, config, dependencies = {}
732
908
  }
733
909
  io.stdout(renderMutation('create', data.database));
734
910
  }
911
+ // The "call show first, branch on `.kind`" helper every later analytical verb
912
+ // (schema/query/exec/dump/pull/push/import/ingest) reuses to learn a
913
+ // database's kind before dispatching to the libsql or duckdb code path.
914
+ async function requestDatabaseRecord(name, config, dependencies = {}) {
915
+ const io = resolveDependencies(dependencies);
916
+ return stableDatabaseResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'show', name }, requestDependencies(io))).database;
917
+ }
918
+ // Refuses an analytical (duckdb) name for the SQLite-only verbs (exec, dump,
919
+ // pull, push, import), reusing the same `show`-first lookup as `schema` and
920
+ // `query` above. The server (`HandleCliDatabaseOperation`) already refuses
921
+ // these operations with `kind_mismatch`; this guard only makes the refusal
922
+ // fast (before any file read, temp file, or data-plane mint) and legible.
923
+ async function refuseIfAnalytical(config, name, verb, dependencies = {}) {
924
+ const row = await requestDatabaseRecord(name, config, dependencies);
925
+ if (row.kind !== 'duckdb')
926
+ return;
927
+ if (verb === 'exec') {
928
+ throw new database_data_plane_1.DatabaseOperationError('read_only', "read-only: this is an analytical database — load data with `solidactions database ingest` or your workflow's ingest step");
929
+ }
930
+ throw new database_data_plane_1.DatabaseOperationError('kind_mismatch', `"${name}" is an analytical database — use \`database ingest\` to load data and \`database query\` to read it`);
931
+ }
932
+ async function databaseShowWithConfig(name, options, config, dependencies = {}) {
933
+ const io = resolveDependencies(dependencies);
934
+ const database = await requestDatabaseRecord(name, config, dependencies);
935
+ if (options.json) {
936
+ writeJson(io.stdout, { database });
937
+ return;
938
+ }
939
+ io.stdout(renderShow(database));
940
+ }
735
941
  async function databaseImportWithConfig(name, file, options, config, dependencies = {}) {
736
942
  const io = resolveDependencies(dependencies);
943
+ await refuseIfAnalytical(config, name, 'sqlite-only', io);
737
944
  const prepared = await (0, database_sql_import_runner_1.prepareDatabaseImport)(name, file, options.resume, io.cwd, io.filesystem);
738
945
  if (!options.yes) {
739
946
  if (!io.isTTY) {
@@ -785,6 +992,18 @@ async function databaseUndeleteWithConfig(name, options, config, dependencies =
785
992
  }
786
993
  async function databaseSchemaWithConfig(name, options, config, dependencies = {}) {
787
994
  const io = resolveDependencies(dependencies);
995
+ const row = await requestDatabaseRecord(name, config, dependencies);
996
+ if (row.kind === 'duckdb') {
997
+ // Read-intent, served from the cached catalog — never wakes a
998
+ // paused database (spec:568/598).
999
+ const schema = stableAnalyticalSchema(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'schema', name }, requestDependencies(io)));
1000
+ if (options.json) {
1001
+ writeJson(io.stdout, schema);
1002
+ return;
1003
+ }
1004
+ io.stdout(renderAnalyticalSchema(schema));
1005
+ return;
1006
+ }
788
1007
  const schema = await (0, database_data_plane_1.withDatabaseClient)(config, name, 'read', (client) => readDatabaseSchema(client, name), clientDependencies(io));
789
1008
  if (options.json) {
790
1009
  writeJson(io.stdout, schema);
@@ -792,8 +1011,93 @@ async function databaseSchemaWithConfig(name, options, config, dependencies = {}
792
1011
  }
793
1012
  io.stdout(renderSchema(schema));
794
1013
  }
1014
+ function isAnalyticalWaking(value) {
1015
+ const candidate = value;
1016
+ return candidate?.code === 'waking';
1017
+ }
1018
+ function stableAnalyticalQueryResult(data) {
1019
+ if (!data
1020
+ || !Array.isArray(data.columns)
1021
+ || !data.columns.every((column) => typeof column === 'string')
1022
+ || !Array.isArray(data.rows)
1023
+ || !data.rows.every((row) => Array.isArray(row))
1024
+ || typeof data.truncated !== 'boolean'
1025
+ || typeof data.elapsed_ms !== 'number') {
1026
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1027
+ }
1028
+ return {
1029
+ columns: [...data.columns],
1030
+ rows: data.rows.map((row) => [...row]),
1031
+ truncated: data.truncated,
1032
+ elapsed_ms: data.elapsed_ms,
1033
+ };
1034
+ }
1035
+ // CLI-surface cap (`services.analytical.query_row_limit_cli` on the server;
1036
+ // `config/services.php`) — the server clamps to the same value when
1037
+ // `row_limit` is omitted, so this is both the client-side validation bound
1038
+ // and the number shown for an un-limited truncation.
1039
+ const ANALYTICAL_QUERY_ROW_LIMIT_CLI_MAX = 10_000;
1040
+ // Bounds how long the CLI itself waits out a `waking` database before giving
1041
+ // up and surfacing the condition as an error; the server keeps retrying on
1042
+ // its own schedule via `retry_after_ms`.
1043
+ const ANALYTICAL_QUERY_MAX_WAIT_MS = 60_000;
1044
+ async function requestAnalyticalQuery(config, name, sql, rowLimit, io) {
1045
+ const body = { operation: 'query', name, sql };
1046
+ if (rowLimit !== undefined) {
1047
+ body.row_limit = rowLimit;
1048
+ }
1049
+ const deadline = io.now() + ANALYTICAL_QUERY_MAX_WAIT_MS;
1050
+ let announced = false;
1051
+ for (;;) {
1052
+ const response = await (0, database_data_plane_1.requestDatabaseOperation)(config, body, requestDependencies(io));
1053
+ if (!isAnalyticalWaking(response)) {
1054
+ return stableAnalyticalQueryResult(response);
1055
+ }
1056
+ if (io.now() >= deadline) {
1057
+ throw new database_data_plane_1.DatabaseOperationError('waking', response.message ?? `${name} is still waking up — try again in a moment.`);
1058
+ }
1059
+ if (!announced) {
1060
+ io.stderr(`Waking ${name}…`);
1061
+ announced = true;
1062
+ }
1063
+ await io.sleep(response.retry_after_ms ?? 3_000);
1064
+ }
1065
+ }
1066
+ /**
1067
+ * Render one analytical query cell for the human table. Unlike the libsql
1068
+ * path's `formatDatabaseTableValue` (which exists for driver-native
1069
+ * bigint/blob values), analytical rows arrive as plain JSON over the wire —
1070
+ * so a bare `String(value)` rendered SQL NULL as the literal text "null"
1071
+ * (indistinguishable from the string "null") and a JSON/STRUCT column as
1072
+ * "[object Object]".
1073
+ */
1074
+ function formatAnalyticalQueryValue(value) {
1075
+ if (value === null)
1076
+ return 'NULL';
1077
+ if (typeof value === 'object')
1078
+ return JSON.stringify(value);
1079
+ return String(value);
1080
+ }
795
1081
  async function databaseQueryWithConfig(name, sql, options, config, dependencies = {}) {
796
1082
  const io = resolveDependencies(dependencies);
1083
+ const row = await requestDatabaseRecord(name, config, dependencies);
1084
+ if (row.kind === 'duckdb') {
1085
+ if (options.limit !== undefined && (Number.isNaN(options.limit) || options.limit < 1 || options.limit > ANALYTICAL_QUERY_ROW_LIMIT_CLI_MAX)) {
1086
+ throw new database_data_plane_1.DatabaseOperationError('invalid_limit', `--limit must be between 1 and ${ANALYTICAL_QUERY_ROW_LIMIT_CLI_MAX} (received "${options.limit}").`);
1087
+ }
1088
+ const result = await requestAnalyticalQuery(config, name, sql, options.limit, io);
1089
+ if (options.json) {
1090
+ writeJson(io.stdout, result);
1091
+ return;
1092
+ }
1093
+ io.stdout(result.columns.length > 0
1094
+ ? (0, table_1.renderTable)(result.columns, result.rows.map((resultRow) => resultRow.map(formatAnalyticalQueryValue))).join('\n')
1095
+ : 'No rows returned.');
1096
+ if (result.truncated) {
1097
+ io.stdout(`(truncated at ${options.limit ?? ANALYTICAL_QUERY_ROW_LIMIT_CLI_MAX} rows)`);
1098
+ }
1099
+ return;
1100
+ }
797
1101
  const result = await (0, database_data_plane_1.withDatabaseClient)(config, name, 'read', async (client) => stableDirectResult(await client.execute(sql)), clientDependencies(io));
798
1102
  if (options.json) {
799
1103
  writeJson(io.stdout, {
@@ -807,6 +1111,7 @@ async function databaseQueryWithConfig(name, sql, options, config, dependencies
807
1111
  }
808
1112
  async function databaseExecWithConfig(name, sql, options, config, dependencies = {}) {
809
1113
  const io = resolveDependencies(dependencies);
1114
+ await refuseIfAnalytical(config, name, 'exec', io);
810
1115
  if (!options.yes) {
811
1116
  if (options.json || !io.isTTY) {
812
1117
  throw new database_data_plane_1.DatabaseOperationError('confirmation_required', 'Database execution requires --yes in JSON or non-interactive mode.');
@@ -835,6 +1140,7 @@ async function databaseExecWithConfig(name, sql, options, config, dependencies =
835
1140
  }
836
1141
  async function databaseDumpWithConfig(name, file, options, config, dependencies = {}) {
837
1142
  const io = resolveDependencies(dependencies);
1143
+ await refuseIfAnalytical(config, name, 'sqlite-only', io);
838
1144
  const target = resolveDatabaseDestination(io, file, `${safeDatabaseStem(name)}.sql`);
839
1145
  let temp;
840
1146
  let handle;
@@ -1150,6 +1456,7 @@ async function databaseWritablePullWithConfig(name, destination, options, config
1150
1456
  }
1151
1457
  async function databasePullWithConfig(name, destination, options, config, dependencies = {}) {
1152
1458
  const io = resolveDependencies(dependencies);
1459
+ await refuseIfAnalytical(config, name, 'sqlite-only', io);
1153
1460
  if (options.writable) {
1154
1461
  return databaseWritablePullWithConfig(name, destination, options, config, io);
1155
1462
  }
@@ -1288,6 +1595,9 @@ async function databaseList(options, dependencies = {}) {
1288
1595
  async function databaseCreate(name, options, dependencies = {}) {
1289
1596
  await databaseCreateWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1290
1597
  }
1598
+ async function databaseShow(name, options, dependencies = {}) {
1599
+ await databaseShowWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1600
+ }
1291
1601
  async function databaseDelete(name, options, dependencies = {}) {
1292
1602
  await databaseDeleteWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1293
1603
  }
@@ -1312,3 +1622,428 @@ async function databasePull(name, destination, options, dependencies = {}) {
1312
1622
  async function databaseImport(name, file, options, dependencies = {}) {
1313
1623
  await databaseImportWithConfig(name, file, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1314
1624
  }
1625
+ const INGEST_OUTCOME_STATES = ['prepared', 'copying', 'dispatching', 'applying', 'acked', 'failed', 'outcome_unknown'];
1626
+ // `ingest`'s `--json` body was the only new-verb response never run through a
1627
+ // stable normalizer (every other mutation/operation response is) — validate
1628
+ // and narrow it the same way `stableOptimizeOperation` does, instead of
1629
+ // writing the raw server payload (or an unchecked `prepared as IngestOutcome`
1630
+ // cast) straight to stdout.
1631
+ function stableIngestOutcome(data) {
1632
+ if (!data
1633
+ || typeof data.batch_id !== 'string'
1634
+ || !INGEST_OUTCOME_STATES.includes(data.state)
1635
+ || (data.rows !== undefined && typeof data.rows !== 'number')
1636
+ || (data.durable !== undefined && typeof data.durable !== 'boolean')
1637
+ || (data.live_bytes !== undefined && typeof data.live_bytes !== 'number')
1638
+ || (data.acked_at !== undefined && typeof data.acked_at !== 'string')
1639
+ || (data.error_code !== undefined && typeof data.error_code !== 'string')
1640
+ || (data.message !== undefined && typeof data.message !== 'string')) {
1641
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1642
+ }
1643
+ return {
1644
+ batch_id: data.batch_id,
1645
+ state: data.state,
1646
+ ...(data.rows === undefined ? {} : { rows: data.rows }),
1647
+ ...(data.durable === undefined ? {} : { durable: data.durable }),
1648
+ ...(data.live_bytes === undefined ? {} : { live_bytes: data.live_bytes }),
1649
+ ...(data.acked_at === undefined ? {} : { acked_at: data.acked_at }),
1650
+ ...(data.error_code === undefined ? {} : { error_code: data.error_code }),
1651
+ ...(data.message === undefined ? {} : { message: data.message }),
1652
+ };
1653
+ }
1654
+ const INGEST_POLL_INTERVAL_MS = 1_000;
1655
+ const INGEST_POLL_TIMEOUT_MS = 5 * 60_000;
1656
+ async function sha256OfFile(filePath) {
1657
+ const hash = (0, crypto_1.createHash)('sha256');
1658
+ for await (const chunk of fs_1.default.createReadStream(filePath))
1659
+ hash.update(chunk);
1660
+ return hash.digest('hex');
1661
+ }
1662
+ function terminalIngestOutcome(outcome) {
1663
+ return outcome.state === 'acked' || outcome.state === 'failed' || outcome.state === 'outcome_unknown';
1664
+ }
1665
+ /**
1666
+ * A terminal `acked` outcome's `live_bytes` is read from the database's own
1667
+ * column at response time; the server refreshes that column from the
1668
+ * guest's `/stats` only *after* the ack itself lands (spec:1680-1681,
1669
+ * `AnalyticalIngestBatchAcker::finalizeAck()`), so a fresh apply can go
1670
+ * terminal before that refresh has landed. Printing `0 B` right after rows
1671
+ * were genuinely just loaded reads as "nothing was loaded" rather than "not
1672
+ * measured yet" (#1700 cleanroom finding) — zero rows legitimately means
1673
+ * zero bytes, but zero bytes alongside reported rows does not.
1674
+ */
1675
+ function liveSizeClause(outcome) {
1676
+ const bytes = outcome.live_bytes;
1677
+ if (bytes === undefined || (bytes === 0 && (outcome.rows ?? 0) > 0)) {
1678
+ return 'live size still settling';
1679
+ }
1680
+ return `live size now ${formatByteSize(bytes)}`;
1681
+ }
1682
+ function throwOnFailedIngest(outcome) {
1683
+ if (outcome.state === 'failed') {
1684
+ throw new database_data_plane_1.DatabaseOperationError(outcome.error_code ?? 'ingest_failed', outcome.message ?? 'Ingest failed.');
1685
+ }
1686
+ if (outcome.state === 'outcome_unknown') {
1687
+ throw new database_data_plane_1.DatabaseOperationError('outcome_unknown', outcome.message
1688
+ ?? `Ingest batch "${outcome.batch_id}" outcome is unknown — re-run this same command (same file, table, and mode) to check its current status; it will not re-upload.`);
1689
+ }
1690
+ }
1691
+ /**
1692
+ * Loads a local Parquet/CSV/JSONL file into an analytical (duckdb) database
1693
+ * table: hashes the file, derives the §6.4 canonical batch id (unless
1694
+ * `--batch-id` overrides it), calls `ingest_prepare`, PUTs the file to the
1695
+ * presigned URL with exactly the signed `Content-Length`/
1696
+ * `x-amz-checksum-sha256` headers the server returned, calls `ingest_commit`,
1697
+ * then polls `ingest_status` to a terminal state. `ingest_prepare`'s
1698
+ * same-digest replay response omits `upload_url` for an in-progress or
1699
+ * terminal batch — that response IS the outcome, so upload/commit are
1700
+ * skipped and the CLI goes straight to polling it.
1701
+ */
1702
+ async function databaseIngestWithConfig(name, file, options, config, dependencies = {}) {
1703
+ const io = resolveDependencies(dependencies);
1704
+ const mode = options.mode ?? 'append';
1705
+ if (mode !== 'append' && mode !== 'replace') {
1706
+ throw new database_data_plane_1.DatabaseOperationError('invalid_mode', `--mode must be "append" or "replace" (received "${mode}").`);
1707
+ }
1708
+ const format = (0, database_ingest_digest_1.ingestFormatFromExtension)(file);
1709
+ const row = await requestDatabaseRecord(name, config, dependencies);
1710
+ if (row.kind !== 'duckdb') {
1711
+ throw new database_data_plane_1.DatabaseOperationError('kind_mismatch', `"${name}" is not an analytical database — \`database ingest\` only loads data into analytical (duckdb) databases.`);
1712
+ }
1713
+ if (!row.id) {
1714
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was missing its id.');
1715
+ }
1716
+ const stat = await io.filesystem.stat(file);
1717
+ const contentSha256 = await sha256OfFile(file);
1718
+ const batchId = options.batchId ?? (0, database_ingest_digest_1.defaultIngestBatchId)({
1719
+ databaseId: row.id,
1720
+ table: options.table,
1721
+ mode,
1722
+ format,
1723
+ contentSha256,
1724
+ });
1725
+ let prepared;
1726
+ try {
1727
+ prepared = await (0, database_data_plane_1.requestDatabaseOperation)(config, {
1728
+ operation: 'ingest_prepare',
1729
+ name,
1730
+ table: options.table,
1731
+ mode,
1732
+ batch_id: batchId,
1733
+ format,
1734
+ declared_bytes: stat.size,
1735
+ content_sha256: contentSha256,
1736
+ }, requestDependencies(io));
1737
+ }
1738
+ catch (error) {
1739
+ // Controller ruling (spec/#1700): a `size_limit_exceeded` refusal
1740
+ // must surface the limit, not just the generic server message —
1741
+ // `safeDatabaseRequestError` already lifts `size_limit_bytes` onto
1742
+ // the thrown error for exactly this.
1743
+ if (error instanceof database_data_plane_1.DatabaseOperationError && error.code === 'size_limit_exceeded' && error.sizeLimitBytes !== undefined) {
1744
+ throw new database_data_plane_1.DatabaseOperationError(error.code, `${error.message} (limit ${formatByteSize(error.sizeLimitBytes)})`, error.status, error.sizeLimitBytes);
1745
+ }
1746
+ throw error;
1747
+ }
1748
+ // `ingest_prepare` omits `upload_url` only on a same-digest replay of an
1749
+ // already-known batch (spec:571) — the branch taken here is the CLI's
1750
+ // one authoritative signal of "the front door was actually called with
1751
+ // new bytes" versus "this exact batch was already recognized", so it
1752
+ // drives the human-readable wording below (#1700 cleanroom finding: a
1753
+ // replay printed the identical "Ingested N row(s)" sentence as a fresh
1754
+ // apply, with no way to tell them apart short of --json).
1755
+ let outcome;
1756
+ const isReplay = !('upload_url' in prepared && prepared.upload_url);
1757
+ if ('upload_url' in prepared && prepared.upload_url) {
1758
+ const headers = prepared.upload_headers;
1759
+ if (!headers) {
1760
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The ingest prepare response was missing upload headers.');
1761
+ }
1762
+ let uploaded;
1763
+ try {
1764
+ uploaded = await io.put(prepared.upload_url, fs_1.default.createReadStream(file), {
1765
+ // Only the two signed headers R2 verified go on the wire —
1766
+ // never re-derive or reshape them (they are part of the
1767
+ // signature).
1768
+ headers: {
1769
+ 'Content-Length': headers['Content-Length'],
1770
+ 'x-amz-checksum-sha256': headers['x-amz-checksum-sha256'],
1771
+ },
1772
+ // C-3: every other network call on this surface is
1773
+ // deadline-bounded (runWithDeadline/positiveTimeout); this
1774
+ // presigned R2 PUT was the one bare call with no timeout, so
1775
+ // a black-holed upload hung `ingest` forever. Re-issuing the
1776
+ // presigned URL for a `prepared` row (ingestPrepareReplay)
1777
+ // already recovers from this once it throws.
1778
+ timeout: io.dataPlaneTimeoutMs,
1779
+ });
1780
+ }
1781
+ catch {
1782
+ throw new database_data_plane_1.DatabaseOperationError('upload_failed', 'The file upload to staging storage failed; the ingest batch was not committed.');
1783
+ }
1784
+ if (uploaded.status !== undefined && (uploaded.status < 200 || uploaded.status > 299)) {
1785
+ throw new database_data_plane_1.DatabaseOperationError('upload_failed', 'The file upload to staging storage failed; the ingest batch was not committed.');
1786
+ }
1787
+ outcome = stableIngestOutcome(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'ingest_commit', name, batch_id: batchId }, requestDependencies(io)));
1788
+ }
1789
+ else {
1790
+ outcome = stableIngestOutcome(prepared);
1791
+ }
1792
+ // The row's state machine (`copying` → `dispatching` → `applying` →
1793
+ // terminal) already absorbs a paused database transparently — the async
1794
+ // `AdvanceIngestBatch` job self-redispatches on a `waking` admission
1795
+ // refusal without ever surfacing `waking` on this poll (unlike
1796
+ // `query`'s synchronous admission gate) — so this loop only needs to
1797
+ // keep polling until a terminal state or its own give-up deadline.
1798
+ const deadline = io.now() + INGEST_POLL_TIMEOUT_MS;
1799
+ while (!terminalIngestOutcome(outcome) && io.now() < deadline) {
1800
+ await io.sleep(INGEST_POLL_INTERVAL_MS);
1801
+ outcome = stableIngestOutcome(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'ingest_status', name, batch_id: batchId }, requestDependencies(io)));
1802
+ }
1803
+ if (!terminalIngestOutcome(outcome)) {
1804
+ throw new database_data_plane_1.DatabaseOperationError('ingest_timeout', `Ingest batch "${batchId}" did not reach a final state within the CLI's wait window — re-run this same command to check its status (it will not re-upload).`);
1805
+ }
1806
+ if (options.json) {
1807
+ writeJson(io.stdout, outcome);
1808
+ throwOnFailedIngest(outcome);
1809
+ return;
1810
+ }
1811
+ throwOnFailedIngest(outcome);
1812
+ io.stdout(isReplay
1813
+ ? `Batch "${batchId}" was already ingested into "${options.table}" — ${outcome.rows ?? 0} row(s) recognized from a previous run, nothing re-loaded (${liveSizeClause(outcome)}).`
1814
+ : `Ingested ${outcome.rows ?? 0} row(s) into "${options.table}" (${liveSizeClause(outcome)}).`);
1815
+ }
1816
+ async function databaseIngest(name, file, options, dependencies = {}) {
1817
+ await databaseIngestWithConfig(name, file, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1818
+ }
1819
+ // Analytical-only guard shared by drop-table/optimize/connect/wake (mirrors
1820
+ // `databaseIngestWithConfig`'s own check): unlike `refuseIfAnalytical`, which
1821
+ // refuses an analytical name on the SQLite-only verbs, these four verbs only
1822
+ // ever operate on the analytical (duckdb) kind, so a libsql name is the
1823
+ // refusal — before any operation-specific request goes out.
1824
+ function refuseUnlessAnalytical(name, row, verb) {
1825
+ if (row.kind === 'duckdb')
1826
+ return;
1827
+ throw new database_data_plane_1.DatabaseOperationError('kind_mismatch', `"${name}" is not an analytical database — \`database ${verb}\` only works on analytical (duckdb) databases.`);
1828
+ }
1829
+ /**
1830
+ * Shared by `drop-table` and `optimize`: `admit()` on the server — the same
1831
+ * gate `query` goes through (`requestAnalyticalQuery` above) — can answer
1832
+ * either op with a `waking` refusal (202) if the database is still coming up
1833
+ * after its own internal wait. `wake` itself is this same admission call, so
1834
+ * it reuses this loop directly. Bounded by the same
1835
+ * `ANALYTICAL_QUERY_MAX_WAIT_MS` `query` uses to give up on a `waking`
1836
+ * database.
1837
+ */
1838
+ async function requestAnalyticalOperationAwaitingWake(config, body, name, io) {
1839
+ const deadline = io.now() + ANALYTICAL_QUERY_MAX_WAIT_MS;
1840
+ let announced = false;
1841
+ for (;;) {
1842
+ const response = await (0, database_data_plane_1.requestDatabaseOperation)(config, body, requestDependencies(io));
1843
+ if (!isAnalyticalWaking(response)) {
1844
+ return response;
1845
+ }
1846
+ if (io.now() >= deadline) {
1847
+ throw new database_data_plane_1.DatabaseOperationError('waking', response.message ?? `${name} is still waking up — try again in a moment.`);
1848
+ }
1849
+ if (!announced) {
1850
+ io.stderr(`Waking ${name}…`);
1851
+ announced = true;
1852
+ }
1853
+ await io.sleep(response.retry_after_ms ?? 3_000);
1854
+ }
1855
+ }
1856
+ /**
1857
+ * Appendix A.6 — deletes one table and frees its space. Destructive, so it
1858
+ * follows the same `--yes`/confirm convention as `delete`/`exec`. Reachable
1859
+ * server error codes (`HandleAnalyticalDatabaseOperation::dropTable()` /
1860
+ * `mapDropTableError()`): `reserved_table` (a `_`-prefixed name, refused
1861
+ * before admission), `table_not_found`, `fenced` (concurrent generation
1862
+ * change — retry), and a draining guest's bare `unavailable` — all passed
1863
+ * through verbatim by `safeDatabaseRequestError`, nothing to translate here.
1864
+ * `dropTable()` DOES call `admit()` before reaching the front door, so a
1865
+ * `waking` refusal is genuinely reachable — unlike `ingest_prepare`/
1866
+ * `ingest_commit`/`ingest_status` (Task 6), which never call it.
1867
+ */
1868
+ async function databaseDropTableWithConfig(name, table, options, config, dependencies = {}) {
1869
+ const io = resolveDependencies(dependencies);
1870
+ const row = await requestDatabaseRecord(name, config, dependencies);
1871
+ refuseUnlessAnalytical(name, row, 'drop-table');
1872
+ if (!options.yes) {
1873
+ if (options.json || !io.isTTY) {
1874
+ throw new database_data_plane_1.DatabaseOperationError('confirmation_required', 'Dropping a table requires --yes in JSON or non-interactive mode.');
1875
+ }
1876
+ if (!await io.confirm(`Delete table "${table}" from "${name}"? Its rows are removed and the space is freed. This cannot be undone.`)) {
1877
+ io.stdout('Cancelled.');
1878
+ return;
1879
+ }
1880
+ }
1881
+ const data = stableDatabaseResponse(await requestAnalyticalOperationAwaitingWake(config, { operation: 'drop_table', name, table }, name, io));
1882
+ if (options.json) {
1883
+ writeJson(io.stdout, data);
1884
+ return;
1885
+ }
1886
+ io.stdout(`Dropped table "${table}" from "${name}". Size is now ${formatByteSize(data.database.size_bytes)}.`);
1887
+ }
1888
+ async function databaseDropTable(name, table, options, dependencies = {}) {
1889
+ await databaseDropTableWithConfig(name, table, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1890
+ }
1891
+ function stableOptimizeOperation(data) {
1892
+ if (!data
1893
+ || typeof data.operation_id !== 'string'
1894
+ || (data.state !== 'running' && data.state !== 'done' && data.state !== 'failed')
1895
+ || (data.started_at !== undefined && typeof data.started_at !== 'string')
1896
+ || (data.files_before !== undefined && typeof data.files_before !== 'number')
1897
+ || (data.files_after !== undefined && typeof data.files_after !== 'number')
1898
+ || (data.finished_at !== undefined && typeof data.finished_at !== 'string')
1899
+ || (data.error_code !== undefined && typeof data.error_code !== 'string')
1900
+ || (data.message !== undefined && typeof data.message !== 'string')) {
1901
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1902
+ }
1903
+ return {
1904
+ operation_id: data.operation_id,
1905
+ state: data.state,
1906
+ ...(data.started_at === undefined ? {} : { started_at: data.started_at }),
1907
+ ...(data.files_before === undefined ? {} : { files_before: data.files_before }),
1908
+ ...(data.files_after === undefined ? {} : { files_after: data.files_after }),
1909
+ ...(data.finished_at === undefined ? {} : { finished_at: data.finished_at }),
1910
+ ...(data.error_code === undefined ? {} : { error_code: data.error_code }),
1911
+ ...(data.message === undefined ? {} : { message: data.message }),
1912
+ };
1913
+ }
1914
+ const OPTIMIZE_POLL_INTERVAL_MS = 2_000;
1915
+ const OPTIMIZE_POLL_TIMEOUT_MS = 15 * 60_000;
1916
+ // A freshly-started operation and one already running elsewhere return the
1917
+ // identical wire shape (Appendix A.7) — mirrors the web dialog's own
1918
+ // `ALREADY_RUNNING_THRESHOLD_MS` heuristic (analytical-optimize-dialog.tsx):
1919
+ // compare this call's own pre-request timestamp against the operation's
1920
+ // `started_at`; a gap this large means the operation predates the call.
1921
+ const OPTIMIZE_ALREADY_RUNNING_THRESHOLD_MS = 3_000;
1922
+ /**
1923
+ * Appendix A.7 — `optimize` is idempotent: a database already mid-optimize
1924
+ * returns its running operation instead of starting a second one. Since the
1925
+ * server's `running` reply is identical either way, the CLI distinguishes
1926
+ * "just started" from "already running" the same way the web dialog does:
1927
+ * by comparing `started_at` against a timestamp captured immediately before
1928
+ * the request. `--wait` polls `optimize_status` (read-intent, never calls
1929
+ * `admit()`, so no `waking` handling there) to a terminal state, bounded by
1930
+ * `OPTIMIZE_POLL_TIMEOUT_MS` — exiting non-zero if that deadline passes
1931
+ * while still `running`, mirroring `provisioning_timeout` (Task 2) and
1932
+ * `ingest_timeout` (Task 6).
1933
+ */
1934
+ async function databaseOptimizeWithConfig(name, options, config, dependencies = {}) {
1935
+ const io = resolveDependencies(dependencies);
1936
+ const row = await requestDatabaseRecord(name, config, dependencies);
1937
+ refuseUnlessAnalytical(name, row, 'optimize');
1938
+ const requestedAt = io.now();
1939
+ let operation = stableOptimizeOperation(await requestAnalyticalOperationAwaitingWake(config, { operation: 'optimize', name }, name, io));
1940
+ if (options.wait) {
1941
+ const deadline = io.now() + OPTIMIZE_POLL_TIMEOUT_MS;
1942
+ while (operation.state === 'running' && io.now() < deadline) {
1943
+ await io.sleep(OPTIMIZE_POLL_INTERVAL_MS);
1944
+ operation = stableOptimizeOperation(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'optimize_status', name, operation_id: operation.operation_id }, requestDependencies(io)));
1945
+ }
1946
+ if (operation.state === 'running') {
1947
+ throw new database_data_plane_1.DatabaseOperationError('optimize_timeout', `Optimize for "${name}" did not finish within the CLI's wait window — re-run \`solidactions database optimize ${name} --wait\` to check its status.`);
1948
+ }
1949
+ }
1950
+ if (options.json) {
1951
+ writeJson(io.stdout, operation);
1952
+ if (operation.state === 'failed') {
1953
+ throw new database_data_plane_1.DatabaseOperationError(operation.error_code ?? 'optimize_failed', operation.message ?? 'Optimize failed.');
1954
+ }
1955
+ return;
1956
+ }
1957
+ if (operation.state === 'failed') {
1958
+ throw new database_data_plane_1.DatabaseOperationError(operation.error_code ?? 'optimize_failed', operation.message ?? 'Optimize failed.');
1959
+ }
1960
+ if (operation.state === 'done') {
1961
+ io.stdout(`Optimized "${name}" (${operation.files_before} files → ${operation.files_after}).`);
1962
+ return;
1963
+ }
1964
+ const startedAtMs = operation.started_at ? new Date(operation.started_at).getTime() : NaN;
1965
+ const alreadyRunning = Number.isFinite(startedAtMs)
1966
+ && requestedAt - startedAtMs > OPTIMIZE_ALREADY_RUNNING_THRESHOLD_MS;
1967
+ io.stdout(alreadyRunning
1968
+ ? `Optimize already running for "${name}" (started ${operation.started_at}).`
1969
+ : `Optimize started for "${name}" (started ${operation.started_at}).`);
1970
+ }
1971
+ async function databaseOptimize(name, options, dependencies = {}) {
1972
+ await databaseOptimizeWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1973
+ }
1974
+ function stableConnectResponse(data) {
1975
+ if (!data
1976
+ || typeof data.external_read !== 'boolean'
1977
+ || !data.cli
1978
+ || typeof data.cli.query !== 'string'
1979
+ || typeof data.cli.ingest !== 'string'
1980
+ || typeof data.mcp !== 'string'
1981
+ || typeof data.yaml !== 'string') {
1982
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1983
+ }
1984
+ return {
1985
+ external_read: data.external_read,
1986
+ cli: { query: data.cli.query, ingest: data.cli.ingest },
1987
+ mcp: data.mcp,
1988
+ yaml: data.yaml,
1989
+ };
1990
+ }
1991
+ function renderConnect(connect) {
1992
+ return [
1993
+ 'CLI:',
1994
+ ` ${connect.cli.query}`,
1995
+ ` ${connect.cli.ingest}`,
1996
+ '',
1997
+ 'Ask your AI:',
1998
+ ` ${connect.mcp}`,
1999
+ '',
2000
+ 'solidactions.yaml:',
2001
+ connect.yaml.split('\n').map((line) => ` ${line}`).join('\n'),
2002
+ '',
2003
+ 'Connecting directly from DuckDB or BI tools is coming later.',
2004
+ ].join('\n');
2005
+ }
2006
+ /**
2007
+ * Appendix A.8 — no client credentials for the analytical kind in v1
2008
+ * (deliberate; see spec). `connect()` never calls `admit()` — it is a pure,
2009
+ * synchronous read of the database row, so `waking` is not reachable here.
2010
+ */
2011
+ async function databaseConnectWithConfig(name, options, config, dependencies = {}) {
2012
+ const io = resolveDependencies(dependencies);
2013
+ const row = await requestDatabaseRecord(name, config, dependencies);
2014
+ refuseUnlessAnalytical(name, row, 'connect');
2015
+ const connect = stableConnectResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'connect', name }, requestDependencies(io)));
2016
+ if (options.json) {
2017
+ writeJson(io.stdout, connect);
2018
+ return;
2019
+ }
2020
+ io.stdout(renderConnect(connect));
2021
+ }
2022
+ async function databaseConnect(name, options, dependencies = {}) {
2023
+ await databaseConnectWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
2024
+ }
2025
+ function stableWakeActiveResponse(data) {
2026
+ if (!data || typeof data.activity !== 'string') {
2027
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
2028
+ }
2029
+ return { activity: data.activity };
2030
+ }
2031
+ /**
2032
+ * Appendix A.9 — read-intent pre-warm: `wake()` on the server is exactly one
2033
+ * `admit()` call, so this reuses `requestAnalyticalOperationAwaitingWake`
2034
+ * directly rather than hand-rolling its own retry loop.
2035
+ */
2036
+ async function databaseWakeWithConfig(name, options, config, dependencies = {}) {
2037
+ const io = resolveDependencies(dependencies);
2038
+ const row = await requestDatabaseRecord(name, config, dependencies);
2039
+ refuseUnlessAnalytical(name, row, 'wake');
2040
+ const response = stableWakeActiveResponse(await requestAnalyticalOperationAwaitingWake(config, { operation: 'wake', name }, name, io));
2041
+ if (options.json) {
2042
+ writeJson(io.stdout, response);
2043
+ return;
2044
+ }
2045
+ io.stdout(`${name} is ${response.activity}.`);
2046
+ }
2047
+ async function databaseWake(name, options, dependencies = {}) {
2048
+ await databaseWakeWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
2049
+ }