@solidactions/cli 3.34.0 → 3.36.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
@@ -124,6 +124,11 @@ solidactions database optimize analytics --wait --json
124
124
  solidactions database connect analytics --json
125
125
  solidactions database wake analytics --json
126
126
  solidactions database query analytics "select category, sum(amount) from events group by 1" --limit 1000 --json
127
+ solidactions database create metrics --kind duckdb_file --json
128
+ solidactions database pull metrics
129
+ solidactions database pull metrics ./metrics.duckdb --version 2 --yes
130
+ solidactions database versions metrics --limit 20 --json
131
+ solidactions database rollback metrics 2 --yes --json
127
132
  ```
128
133
 
129
134
  `--json` produces machine-readable output where supported. `delete`, `exec`,
@@ -142,6 +147,19 @@ after creation. Analytical verbs — `ingest`, `export`, `drop-table`, `optimize
142
147
  `push`, `import`, and `exec` are for the standard (SQLite) kind only and
143
148
  refuse an analytical name with a one-line hint.
144
149
 
150
+ `create --kind duckdb_file` makes a DuckDB database file that your workflows
151
+ open, change and publish as numbered versions; it has no `--from`, `ingest` or
152
+ `exec` (change it from a workflow). `pull <name> [path]` downloads the latest
153
+ published version as a plain DuckDB file (default
154
+ `.solidactions/databases/<name>.duckdb`; `--version <n>` picks an older one;
155
+ needs Node 22.15 or newer), verifies its size and checksum, and refuses a
156
+ download that does not match. It also refuses to pull over a target that has a
157
+ `<path>.wal` write-ahead file beside it, even with `--yes`: close the program
158
+ that has the database open (or remove that file) and pull again. `versions <name>` lists the published versions,
159
+ newest first, and `rollback <name> <version>` makes an earlier one current
160
+ after a `--yes` confirmation. `query` and `schema` answer that queries on
161
+ DuckDB databases arrive with the next release.
162
+
145
163
  `ingest --mode replace` overwrites a table's contents with no `--yes` prompt
146
164
  (unlike `drop-table`, which is a separate, rarer, schema-shaped operation) —
147
165
  this is the normal, expected way to refresh an analytical table from an
@@ -537,6 +555,18 @@ You do **not** need `--overwrite` to keep an edited file whose doc was deleted o
537
555
 
538
556
  **`doc pull` refuses to replace another folder's manifest.** If the destination already tracks a different folder, pulling into it would leave the previously tracked files untracked — and untracked files are not protected from being overwritten by a later pull. `pull` refuses (exit 1, before anything is written) and names both folders. Pull into a different directory, or pass `--overwrite` to replace the manifest anyway. This also covers the single-doc pull path, whose one-entry manifest would otherwise clobber a folder's.
539
557
 
558
+ ### app
559
+
560
+ | Command | Key Flags | Description |
561
+ |---------|-----------|-------------|
562
+ | `app preview <app>` | `--page <id>` | Print a one-time link that opens the app's dev copy in your own browser, no login |
563
+
564
+ `app preview` asks the server for a link and prints it on its own line. The CLI does not open a browser. The link opens the app's **dev copy** only (never production) as you, and only if you may deploy the app. It works once and must be opened within 60 seconds; the session ends after 3 minutes without use or 10 minutes in all, and you ask again for a new link when it ends. `--page <id>` opens one page of the app first (the page's numeric doc id).
565
+
566
+ If the dev copy shares a database with production, the command prints a warning naming the databases; the link is still issued. A refusal (the app is unknown, it has no dev copy, the page is not part of it, previews are switched off for the workspace, too many links asked for) prints a plain message and exits non-zero.
567
+
568
+ **For agents:** before calling an app change done, deploy it to dev (`solidactions project deploy <app> . -e dev`), run `solidactions app preview <app>`, open the link in your own browser and try the app (open pages, press buttons, fill forms).
569
+
540
570
  ### workspace
541
571
 
542
572
  | Command | Description |
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "cli_name": "solidactions",
4
- "cli_version": "3.34.0",
4
+ "cli_version": "3.36.0",
5
5
  "global_options": [
6
6
  {
7
7
  "flags": "-V, --version",
@@ -403,7 +403,7 @@
403
403
  "flags": "--kind <kind>",
404
404
  "long": "--kind",
405
405
  "short": null,
406
- "description": "Filter by kind: libsql or duckdb",
406
+ "description": "Filter by kind: libsql, duckdb or duckdb_file",
407
407
  "required": false,
408
408
  "value_required": true,
409
409
  "value_optional": false,
@@ -459,7 +459,7 @@
459
459
  "flags": "--kind <kind>",
460
460
  "long": "--kind",
461
461
  "short": null,
462
- "description": "Database kind: libsql (default) or duckdb",
462
+ "description": "Database kind: libsql (default), duckdb or duckdb_file (a DuckDB database file that workflows open, change and publish)",
463
463
  "required": false,
464
464
  "value_required": true,
465
465
  "value_optional": false,
@@ -929,6 +929,136 @@
929
929
  "negated": false,
930
930
  "hidden": false
931
931
  },
932
+ {
933
+ "flags": "--version <n>",
934
+ "long": "--version",
935
+ "short": null,
936
+ "description": "DuckDB databases: pull this published version instead of the latest",
937
+ "required": false,
938
+ "value_required": true,
939
+ "value_optional": false,
940
+ "variadic": false,
941
+ "negated": false,
942
+ "hidden": false
943
+ },
944
+ {
945
+ "flags": "-h, --help",
946
+ "long": "--help",
947
+ "short": "-h",
948
+ "description": "display help for command",
949
+ "required": false,
950
+ "value_required": false,
951
+ "value_optional": false,
952
+ "variadic": false,
953
+ "negated": false,
954
+ "hidden": false
955
+ }
956
+ ]
957
+ },
958
+ {
959
+ "path": [
960
+ "database",
961
+ "versions"
962
+ ],
963
+ "name": "versions",
964
+ "aliases": [],
965
+ "description": "List the published versions of a DuckDB database, newest first",
966
+ "hidden": false,
967
+ "arguments": [
968
+ {
969
+ "name": "name",
970
+ "required": true,
971
+ "variadic": false,
972
+ "description": "Database name"
973
+ }
974
+ ],
975
+ "options": [
976
+ {
977
+ "flags": "--limit <n>",
978
+ "long": "--limit",
979
+ "short": null,
980
+ "description": "How many versions to list (1-200)",
981
+ "required": false,
982
+ "value_required": true,
983
+ "value_optional": false,
984
+ "variadic": false,
985
+ "negated": false,
986
+ "hidden": false
987
+ },
988
+ {
989
+ "flags": "--json",
990
+ "long": "--json",
991
+ "short": null,
992
+ "description": "Output as JSON",
993
+ "required": false,
994
+ "value_required": false,
995
+ "value_optional": false,
996
+ "variadic": false,
997
+ "negated": false,
998
+ "hidden": false
999
+ },
1000
+ {
1001
+ "flags": "-h, --help",
1002
+ "long": "--help",
1003
+ "short": "-h",
1004
+ "description": "display help for command",
1005
+ "required": false,
1006
+ "value_required": false,
1007
+ "value_optional": false,
1008
+ "variadic": false,
1009
+ "negated": false,
1010
+ "hidden": false
1011
+ }
1012
+ ]
1013
+ },
1014
+ {
1015
+ "path": [
1016
+ "database",
1017
+ "rollback"
1018
+ ],
1019
+ "name": "rollback",
1020
+ "aliases": [],
1021
+ "description": "Make an earlier published version of a DuckDB database the current one",
1022
+ "hidden": false,
1023
+ "arguments": [
1024
+ {
1025
+ "name": "name",
1026
+ "required": true,
1027
+ "variadic": false,
1028
+ "description": "Database name"
1029
+ },
1030
+ {
1031
+ "name": "version",
1032
+ "required": true,
1033
+ "variadic": false,
1034
+ "description": "Version number to roll back to"
1035
+ }
1036
+ ],
1037
+ "options": [
1038
+ {
1039
+ "flags": "-y, --yes",
1040
+ "long": "--yes",
1041
+ "short": "-y",
1042
+ "description": "Skip confirmation",
1043
+ "required": false,
1044
+ "value_required": false,
1045
+ "value_optional": false,
1046
+ "variadic": false,
1047
+ "negated": false,
1048
+ "hidden": false
1049
+ },
1050
+ {
1051
+ "flags": "--json",
1052
+ "long": "--json",
1053
+ "short": null,
1054
+ "description": "Output as JSON",
1055
+ "required": false,
1056
+ "value_required": false,
1057
+ "value_optional": false,
1058
+ "variadic": false,
1059
+ "negated": false,
1060
+ "hidden": false
1061
+ },
932
1062
  {
933
1063
  "flags": "-h, --help",
934
1064
  "long": "--help",
@@ -4741,6 +4871,93 @@
4741
4871
  ],
4742
4872
  "options": []
4743
4873
  },
4874
+ {
4875
+ "path": [
4876
+ "app"
4877
+ ],
4878
+ "name": "app",
4879
+ "aliases": [],
4880
+ "description": "Try an app before it ships",
4881
+ "hidden": false,
4882
+ "arguments": [],
4883
+ "options": [
4884
+ {
4885
+ "flags": "-h, --help",
4886
+ "long": "--help",
4887
+ "short": "-h",
4888
+ "description": "display help for command",
4889
+ "required": false,
4890
+ "value_required": false,
4891
+ "value_optional": false,
4892
+ "variadic": false,
4893
+ "negated": false,
4894
+ "hidden": false
4895
+ }
4896
+ ]
4897
+ },
4898
+ {
4899
+ "path": [
4900
+ "app",
4901
+ "preview"
4902
+ ],
4903
+ "name": "preview",
4904
+ "aliases": [],
4905
+ "description": "Print a one-time link that opens an app's dev copy in your own browser, no login",
4906
+ "hidden": false,
4907
+ "arguments": [
4908
+ {
4909
+ "name": "app",
4910
+ "required": true,
4911
+ "variadic": false,
4912
+ "description": "App name, or the slug of any of its environment rows"
4913
+ }
4914
+ ],
4915
+ "options": [
4916
+ {
4917
+ "flags": "--page <id>",
4918
+ "long": "--page",
4919
+ "short": null,
4920
+ "description": "Open this page first (the page's numeric doc id)",
4921
+ "required": false,
4922
+ "value_required": true,
4923
+ "value_optional": false,
4924
+ "variadic": false,
4925
+ "negated": false,
4926
+ "hidden": false
4927
+ },
4928
+ {
4929
+ "flags": "-h, --help",
4930
+ "long": "--help",
4931
+ "short": "-h",
4932
+ "description": "display help for command",
4933
+ "required": false,
4934
+ "value_required": false,
4935
+ "value_optional": false,
4936
+ "variadic": false,
4937
+ "negated": false,
4938
+ "hidden": false
4939
+ }
4940
+ ]
4941
+ },
4942
+ {
4943
+ "path": [
4944
+ "app",
4945
+ "help"
4946
+ ],
4947
+ "name": "help",
4948
+ "aliases": [],
4949
+ "description": "display help for command",
4950
+ "hidden": false,
4951
+ "arguments": [
4952
+ {
4953
+ "name": "command",
4954
+ "required": false,
4955
+ "variadic": false,
4956
+ "description": ""
4957
+ }
4958
+ ],
4959
+ "options": []
4960
+ },
4744
4961
  {
4745
4962
  "path": [
4746
4963
  "ai"
@@ -0,0 +1,78 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.appPreview = appPreview;
7
+ const chalk_1 = __importDefault(require("chalk"));
8
+ const api_1 = require("../utils/api");
9
+ const connect_link_1 = require("../utils/connect-link");
10
+ const mcp_1 = require("../utils/mcp");
11
+ const output_1 = require("../utils/output");
12
+ function fail(line) {
13
+ (0, output_1.err)(line, chalk_1.default.red);
14
+ process.exit(1);
15
+ }
16
+ /** The doc id for --page, or null when it is not a positive whole number a JSON integer can hold. */
17
+ function parsePage(value) {
18
+ if (!/^[1-9][0-9]*$/.test(value))
19
+ return null;
20
+ const n = Number(value);
21
+ return Number.isSafeInteger(n) ? n : null;
22
+ }
23
+ async function appPreview(app, options) {
24
+ const project = app.trim();
25
+ if (project === '') {
26
+ fail('app preview: give the app name, e.g. solidactions app preview my-app.');
27
+ }
28
+ const args = { action: 'preview_link', project };
29
+ if (options.page !== undefined) {
30
+ const page = parsePage(options.page);
31
+ if (page === null) {
32
+ fail("app preview: --page needs a whole number (the page's doc id), e.g. --page 12.");
33
+ }
34
+ args.page = page;
35
+ }
36
+ const config = await (0, api_1.requireConfigWithWorkspace)();
37
+ let result;
38
+ try {
39
+ result = await (0, mcp_1.callProjectsSandbox)(config, args);
40
+ }
41
+ catch (error) {
42
+ fail(`error: ${error.message}`);
43
+ }
44
+ if (!result.ok) {
45
+ const refusal = result.data?.error ?? result.data ?? {};
46
+ const code = typeof refusal.code === 'string' ? refusal.code : '';
47
+ const message = typeof refusal.message === 'string' && refusal.message !== ''
48
+ ? refusal.message
49
+ : code !== '' ? code : 'the server refused the request';
50
+ (0, output_1.err)(`error: ${message}`, chalk_1.default.red);
51
+ if (code === 'no_dev_copy') {
52
+ (0, output_1.err)(`Deploy it to dev first: solidactions project deploy ${(0, connect_link_1.shellArg)(project)} . -e dev`, chalk_1.default.red);
53
+ }
54
+ else if (code === 'rate_limited' && typeof refusal.retry_after === 'number') {
55
+ (0, output_1.err)(`Try again in ${refusal.retry_after} seconds.`, chalk_1.default.red);
56
+ }
57
+ else if (code === 'invalid_action') {
58
+ (0, output_1.err)('This server may be older than the CLI expects: preview links need app v0.295.0 or later.', chalk_1.default.red);
59
+ }
60
+ process.exit(1);
61
+ }
62
+ const data = result.data ?? {};
63
+ if (typeof data.link !== 'string' || data.link === '') {
64
+ fail('Failed: the server answered without a preview link.');
65
+ }
66
+ (0, output_1.out)(`Preview link for ${project} (dev copy):`);
67
+ // Same style as the device-login URL: two-space indent, blue underline on the URL only (src/commands/device-login.ts).
68
+ (0, output_1.out)(' ' + data.link, (s) => ' ' + chalk_1.default.blue.underline(s.slice(2)));
69
+ if (typeof data.note === 'string' && data.note !== '') {
70
+ (0, output_1.out)(data.note);
71
+ }
72
+ if (data.shares_production_data === true) {
73
+ const names = Array.isArray(data.databases) && data.databases.length > 0
74
+ ? data.databases.filter((name) => typeof name === 'string').join(', ')
75
+ : 'unknown';
76
+ (0, output_1.out)(`Warning: this dev copy shares data with production (databases: ${names || 'unknown'}). What you press in the preview changes that data.`, chalk_1.default.yellow);
77
+ }
78
+ }
@@ -51,6 +51,9 @@ exports.databaseQueryWithConfig = databaseQueryWithConfig;
51
51
  exports.databaseExecWithConfig = databaseExecWithConfig;
52
52
  exports.databaseDumpWithConfig = databaseDumpWithConfig;
53
53
  exports.databasePullWithConfig = databasePullWithConfig;
54
+ exports.parseStrictPositiveInteger = parseStrictPositiveInteger;
55
+ exports.databaseVersionsWithConfig = databaseVersionsWithConfig;
56
+ exports.databaseRollbackWithConfig = databaseRollbackWithConfig;
54
57
  exports.databaseList = databaseList;
55
58
  exports.databaseCreate = databaseCreate;
56
59
  exports.databaseShow = databaseShow;
@@ -61,6 +64,8 @@ exports.databaseQuery = databaseQuery;
61
64
  exports.databaseExec = databaseExec;
62
65
  exports.databaseDump = databaseDump;
63
66
  exports.databasePull = databasePull;
67
+ exports.databaseVersions = databaseVersions;
68
+ exports.databaseRollback = databaseRollback;
64
69
  exports.databaseImport = databaseImport;
65
70
  exports.databaseIngestWithConfig = databaseIngestWithConfig;
66
71
  exports.databaseIngest = databaseIngest;
@@ -86,6 +91,7 @@ var database_sql_import_2 = require("../utils/database-sql-import");
86
91
  Object.defineProperty(exports, "parseDatabaseImportSql", { enumerable: true, get: function () { return database_sql_import_2.parseDatabaseImportSql; } });
87
92
  const database_sql_import_runner_1 = require("../utils/database-sql-import-runner");
88
93
  const table_1 = require("../utils/table");
94
+ const database_download_1 = require("../utils/database-download");
89
95
  const database_ingest_digest_1 = require("../utils/database-ingest-digest");
90
96
  function defaultConfirmation(message) {
91
97
  const input = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -125,6 +131,7 @@ function resolveDependencies(dependencies) {
125
131
  sleep: dependencies.sleep ?? ((milliseconds) => new Promise((resolve) => {
126
132
  setTimeout(resolve, milliseconds);
127
133
  })),
134
+ zstdAvailable: dependencies.zstdAvailable ?? (0, database_download_1.zstdDecompressAvailable)(),
128
135
  put: dependencies.put ?? axios_1.default.put,
129
136
  };
130
137
  }
@@ -142,7 +149,35 @@ function clientDependencies(dependencies) {
142
149
  dataPlaneTimeoutMs: dependencies.dataPlaneTimeoutMs,
143
150
  };
144
151
  }
152
+ function stableDuckdbFileRecord(database) {
153
+ if ((database.id !== undefined && typeof database.id !== 'string')
154
+ || typeof database.name !== 'string'
155
+ || typeof database.status !== 'string'
156
+ || typeof database.bytes !== 'number'
157
+ || typeof database.cap_bytes !== 'number'
158
+ || (database.latest_version !== null && typeof database.latest_version !== 'number')
159
+ || (database.last_published_at !== null && typeof database.last_published_at !== 'string')
160
+ || (database.deleted_at !== null && typeof database.deleted_at !== 'string')
161
+ || (database.purge_at !== null && typeof database.purge_at !== 'string')) {
162
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
163
+ }
164
+ return {
165
+ ...(database.id === undefined ? {} : { id: database.id }),
166
+ name: database.name,
167
+ kind: 'duckdb_file',
168
+ status: database.status,
169
+ bytes: database.bytes,
170
+ cap_bytes: database.cap_bytes,
171
+ latest_version: database.latest_version,
172
+ last_published_at: database.last_published_at,
173
+ deleted_at: database.deleted_at,
174
+ purge_at: database.purge_at,
175
+ };
176
+ }
145
177
  function stableDatabaseRecord(database) {
178
+ if (database && database.kind === 'duckdb_file') {
179
+ return stableDuckdbFileRecord(database);
180
+ }
146
181
  if (!database
147
182
  || (database.id !== undefined && typeof database.id !== 'string')
148
183
  || typeof database.name !== 'string'
@@ -212,17 +247,30 @@ function stableListResponse(data) {
212
247
  };
213
248
  }
214
249
  function databaseRows(databases) {
215
- return databases.map((database) => [
216
- database.name,
217
- database.kind,
218
- database.status,
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),
223
- database.deleted_at ?? '-',
224
- database.purge_at ?? '-',
225
- ]);
250
+ return databases.map((database) => {
251
+ if (database.kind === 'duckdb_file') {
252
+ return [
253
+ database.name,
254
+ database.kind,
255
+ database.status,
256
+ '-',
257
+ `${formatByteSize(database.bytes)} / ${formatByteSize(database.cap_bytes)}`,
258
+ database.deleted_at ?? '-',
259
+ database.purge_at ?? '-',
260
+ ];
261
+ }
262
+ return [
263
+ database.name,
264
+ database.kind,
265
+ database.status,
266
+ database.kind === 'duckdb' ? (database.activity ?? '-') : '-',
267
+ database.kind === 'duckdb'
268
+ ? `${formatByteSize(database.size_bytes)} / ${formatByteSize(database.size_limit_bytes ?? 0)}`
269
+ : String(database.size_bytes),
270
+ database.deleted_at ?? '-',
271
+ database.purge_at ?? '-',
272
+ ];
273
+ });
226
274
  }
227
275
  function renderDatabaseTable(databases) {
228
276
  return (0, table_1.renderTable)(['NAME', 'KIND', 'STATUS', 'ACTIVITY', 'SIZE', 'DELETED AT', 'PURGE AT'], databaseRows(databases)).join('\n');
@@ -428,6 +476,9 @@ function renderAnalyticalSchema(schema) {
428
476
  return `${table.name} — ${table.row_count} rows, last loaded ${table.last_loaded_at ?? 'never'}\n ${columns}`;
429
477
  }).join('\n\n');
430
478
  }
479
+ function databaseRecordSizeBytes(database) {
480
+ return database.kind === 'duckdb_file' ? database.bytes : database.size_bytes;
481
+ }
431
482
  /** "1.2 GiB", "512.0 MiB", "900 B" — used by `show`, `list`, and `ingest`. */
432
483
  function formatByteSize(bytes) {
433
484
  // Binary (1024-based) division — the units must say Gi/Mi/Ki, not G/M/K
@@ -445,6 +496,8 @@ function formatByteSize(bytes) {
445
496
  // The analytical (DuckDB) kind is Beta on every surface — this label is the
446
497
  // canonical rendering; standard (libSQL) rows keep the plain kind value.
447
498
  function kindLabel(kind) {
499
+ if (kind === 'duckdb_file')
500
+ return 'DuckDB (analytics)';
448
501
  return kind === 'duckdb' ? 'Analytical · DuckDB (Beta)' : kind;
449
502
  }
450
503
  function renderShow(database) {
@@ -453,6 +506,12 @@ function renderShow(database) {
453
506
  `Kind: ${kindLabel(database.kind)}`,
454
507
  `Status: ${database.status}`,
455
508
  ];
509
+ if (database.kind === 'duckdb_file') {
510
+ lines.push(`Size: ${formatByteSize(database.bytes)} of ${formatByteSize(database.cap_bytes)}`);
511
+ lines.push(`Latest version: ${database.latest_version ?? 'none'}`);
512
+ lines.push(`Last published: ${database.last_published_at ?? 'never'}`);
513
+ return lines.join('\n');
514
+ }
456
515
  if (database.kind === 'duckdb') {
457
516
  lines.push(`Activity: ${database.activity ?? 'unknown'}`);
458
517
  lines.push(`Size: ${formatByteSize(database.size_bytes)} of ${formatByteSize(database.size_limit_bytes ?? 0)}`);
@@ -817,13 +876,16 @@ async function finalizeReplica(io, temp, target, createClient) {
817
876
  await assertNoSymlinkComponents(io.filesystem, target);
818
877
  await io.filesystem.rename(temp, target);
819
878
  }
879
+ function isKnownKindOption(kind) {
880
+ return kind === undefined || kind === 'libsql' || kind === 'duckdb' || kind === 'duckdb_file';
881
+ }
820
882
  async function databaseListWithConfig(options, config, dependencies = {}) {
821
883
  const io = resolveDependencies(dependencies);
822
884
  // The server's `list` operation takes no `kind` parameter — CliDatabaseRequest
823
885
  // prohibits it on anything but `create` — so the filter is applied here,
824
886
  // 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}").`);
887
+ if (!isKnownKindOption(options.kind)) {
888
+ throw new database_data_plane_1.DatabaseOperationError('invalid_kind', `--kind must be "libsql", "duckdb" or "duckdb_file" (received "${options.kind}").`);
827
889
  }
828
890
  const data = stableListResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'list' }, requestDependencies(io)));
829
891
  const databases = options.kind
@@ -839,10 +901,13 @@ const CREATE_POLL_INTERVAL_MS = 2_000;
839
901
  const CREATE_POLL_TIMEOUT_MS = 5 * 60_000;
840
902
  async function databaseCreateWithConfig(name, options, config, dependencies = {}) {
841
903
  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}").`);
904
+ if (!isKnownKindOption(options.kind)) {
905
+ throw new database_data_plane_1.DatabaseOperationError('invalid_kind', `--kind must be "libsql", "duckdb" or "duckdb_file" (received "${options.kind}").`);
906
+ }
907
+ const kind = options.kind === 'duckdb' || options.kind === 'duckdb_file' ? options.kind : 'libsql';
908
+ if (kind === 'duckdb_file' && options.from) {
909
+ throw new database_data_plane_1.DatabaseOperationError('invalid_flag_combination', '--from is not supported with --kind duckdb_file; SQL import only applies to libsql databases.');
844
910
  }
845
- const kind = options.kind === 'duckdb' ? 'duckdb' : 'libsql';
846
911
  if (kind === 'duckdb' && options.from) {
847
912
  // C-2: reject before the create POST. An analytical database is a
848
913
  // billable, org-quota-scoped resource (1 per org on Free) — letting
@@ -929,7 +994,17 @@ const ANALYTICAL_DOCS_URL = 'https://www.solidactions.com/docs/analytical-databa
929
994
  // these operations with `kind_mismatch`; this guard only makes the refusal
930
995
  // fast (before any file read, temp file, or data-plane mint) and legible.
931
996
  async function refuseIfAnalytical(config, name, verb, dependencies = {}) {
932
- const row = await requestDatabaseRecord(name, config, dependencies);
997
+ refuseIfAnalyticalRow(await requestDatabaseRecord(name, config, dependencies), name, verb);
998
+ }
999
+ // The same refusal for a caller that already holds the `show` row, so it does
1000
+ // not ask the server twice.
1001
+ function refuseIfAnalyticalRow(row, name, verb) {
1002
+ if (row.kind === 'duckdb_file') {
1003
+ if (verb === 'exec') {
1004
+ throw new database_data_plane_1.DatabaseOperationError('read_only', `read-only: "${name}" is a DuckDB database — change it from a workflow: open, change, publish.`);
1005
+ }
1006
+ throw new database_data_plane_1.DatabaseOperationError('kind_mismatch', `"${name}" is a DuckDB database — use \`database pull\`, \`database versions\` and \`database rollback\` with it.`);
1007
+ }
933
1008
  if (row.kind !== 'duckdb')
934
1009
  return;
935
1010
  if (verb === 'exec') {
@@ -1000,9 +1075,20 @@ async function databaseUndeleteWithConfig(name, options, config, dependencies =
1000
1075
  }
1001
1076
  io.stdout(renderMutation('undelete', data.database));
1002
1077
  }
1078
+ // `query` and `schema` on a DuckDB database file are the app's to answer (it
1079
+ // says `not_available` until queries ship). The answer is relayed as the
1080
+ // error; a success body would be a contract the CLI does not know yet, so it
1081
+ // is refused as an invalid response rather than guessed at.
1082
+ async function requestDuckdbFileNotAvailable(config, body, io) {
1083
+ await (0, database_data_plane_1.requestDatabaseOperation)(config, body, requestDependencies(io));
1084
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1085
+ }
1003
1086
  async function databaseSchemaWithConfig(name, options, config, dependencies = {}) {
1004
1087
  const io = resolveDependencies(dependencies);
1005
1088
  const row = await requestDatabaseRecord(name, config, dependencies);
1089
+ if (row.kind === 'duckdb_file') {
1090
+ await requestDuckdbFileNotAvailable(config, { operation: 'schema', name }, io);
1091
+ }
1006
1092
  if (row.kind === 'duckdb') {
1007
1093
  // Read-intent, served from the cached catalog — never wakes a
1008
1094
  // paused database (spec:568/598).
@@ -1091,6 +1177,9 @@ function formatAnalyticalQueryValue(value) {
1091
1177
  async function databaseQueryWithConfig(name, sql, options, config, dependencies = {}) {
1092
1178
  const io = resolveDependencies(dependencies);
1093
1179
  const row = await requestDatabaseRecord(name, config, dependencies);
1180
+ if (row.kind === 'duckdb_file') {
1181
+ await requestDuckdbFileNotAvailable(config, { operation: 'query', name, sql }, io);
1182
+ }
1094
1183
  if (row.kind === 'duckdb') {
1095
1184
  if (options.limit !== undefined && (Number.isNaN(options.limit) || options.limit < 1 || options.limit > ANALYTICAL_QUERY_ROW_LIMIT_CLI_MAX)) {
1096
1185
  throw new database_data_plane_1.DatabaseOperationError('invalid_limit', `--limit must be between 1 and ${ANALYTICAL_QUERY_ROW_LIMIT_CLI_MAX} (received "${options.limit}").`);
@@ -1466,7 +1555,17 @@ async function databaseWritablePullWithConfig(name, destination, options, config
1466
1555
  }
1467
1556
  async function databasePullWithConfig(name, destination, options, config, dependencies = {}) {
1468
1557
  const io = resolveDependencies(dependencies);
1469
- await refuseIfAnalytical(config, name, 'sqlite-only', io);
1558
+ if (options.version !== undefined && !isPositiveInteger(options.version)) {
1559
+ throw new database_data_plane_1.DatabaseOperationError('invalid_version', '--version must be a whole number of 1 or more.');
1560
+ }
1561
+ const row = await requestDatabaseRecord(name, config, io);
1562
+ if (row.kind === 'duckdb_file') {
1563
+ return databaseDuckdbFilePullWithConfig(name, destination, options, config, io);
1564
+ }
1565
+ if (options.version !== undefined) {
1566
+ throw new database_data_plane_1.DatabaseOperationError('invalid_flag_combination', '--version is only for DuckDB databases; a standard database has no numbered versions.');
1567
+ }
1568
+ refuseIfAnalyticalRow(row, name, 'sqlite-only');
1470
1569
  if (options.writable) {
1471
1570
  return databaseWritablePullWithConfig(name, destination, options, config, io);
1472
1571
  }
@@ -1599,6 +1698,183 @@ async function databasePullWithConfig(name, destination, options, config, depend
1599
1698
  throw freshSafeFileError(error);
1600
1699
  }
1601
1700
  }
1701
+ function isPositiveInteger(value) {
1702
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1;
1703
+ }
1704
+ /**
1705
+ * The one parser for a whole number of 1 or more typed on the command line
1706
+ * (`--version`, `--limit`, rollback's version). Anything else (`1e0`, `0x2`,
1707
+ * ` 3 `, `0`, `-1`, `abc`) is NaN, which the command then refuses before it
1708
+ * sends a request.
1709
+ */
1710
+ function parseStrictPositiveInteger(value) {
1711
+ return /^[1-9][0-9]*$/.test(value) ? Number(value) : Number.NaN;
1712
+ }
1713
+ function stableDuckdbPullUrl(data, requestedVersion) {
1714
+ if (!data
1715
+ || typeof data.url !== 'string'
1716
+ || !/^https?:\/\//i.test(data.url)
1717
+ || !isPositiveInteger(data.version)
1718
+ || (requestedVersion !== undefined && data.version !== requestedVersion)
1719
+ || !Number.isSafeInteger(data.bytes) || data.bytes < 0
1720
+ || !Number.isSafeInteger(data.stored_bytes) || data.stored_bytes < 0
1721
+ || typeof data.sha256 !== 'string'
1722
+ || !/^[0-9a-f]{64}$/.test(data.sha256)) {
1723
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1724
+ }
1725
+ return {
1726
+ url: data.url,
1727
+ version: data.version,
1728
+ bytes: data.bytes,
1729
+ stored_bytes: data.stored_bytes,
1730
+ sha256: data.sha256,
1731
+ };
1732
+ }
1733
+ async function databaseDuckdbFilePullWithConfig(name, destination, options, config, io) {
1734
+ if (options.writable) {
1735
+ throw new database_data_plane_1.DatabaseOperationError('invalid_flag_combination', '--writable is only for standard databases; a DuckDB database is a file you pull and open locally.');
1736
+ }
1737
+ if (!io.zstdAvailable) {
1738
+ throw new database_data_plane_1.DatabaseOperationError('zstd_unsupported', `Pulling a DuckDB database needs Node 22.15 or newer. This is Node ${process.version}.`);
1739
+ }
1740
+ const target = resolveDatabaseDestination(io, destination, path_1.default.join('.solidactions', 'databases', `${safeDatabaseStem(name)}.duckdb`));
1741
+ try {
1742
+ // A write-ahead file left beside the target belongs to whatever had the old
1743
+ // database open; DuckDB would replay it against the file pulled here. Refused
1744
+ // even with --yes, and before any request.
1745
+ if (await anyPathExists(io.filesystem, [`${target}.wal`])) {
1746
+ throw new database_data_plane_1.DatabaseOperationError('target_has_wal', `A DuckDB write-ahead file sits beside ${displayDestination(io, target)}. Close the program that has the database open (or remove ${displayDestination(io, `${target}.wal`)}) and run the pull again.`);
1747
+ }
1748
+ if (!await confirmFileOverwrite(target, options, io))
1749
+ return;
1750
+ // A refused link (expired) is replaced by a fresh one once; a second
1751
+ // refusal is a failed download, never a loop.
1752
+ let temp;
1753
+ let pulled;
1754
+ for (let attempt = 0; attempt < 2 && !temp; attempt += 1) {
1755
+ const object = stableDuckdbPullUrl(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'pull_url', name, ...(options.version === undefined ? {} : { version: options.version }) }, requestDependencies(io)), options.version);
1756
+ try {
1757
+ temp = await downloadDuckdbToTemp(io, target, object);
1758
+ pulled = object;
1759
+ }
1760
+ catch (error) {
1761
+ if (!(error instanceof database_download_1.DuckdbLinkExpiredError))
1762
+ throw error;
1763
+ }
1764
+ }
1765
+ if (!temp || !pulled) {
1766
+ throw new database_data_plane_1.DatabaseOperationError('download_failed', 'The database download link was refused. Try again.');
1767
+ }
1768
+ try {
1769
+ await assertNoSymlinkComponents(io.filesystem, temp);
1770
+ await assertNoSymlinkComponents(io.filesystem, target);
1771
+ await io.filesystem.rename(temp, target);
1772
+ }
1773
+ catch (error) {
1774
+ await removeOwnedFiles(io.filesystem, [temp]);
1775
+ throw error;
1776
+ }
1777
+ io.stdout(`Database saved to ${displayDestination(io, target)} (version ${pulled.version}, ${pulled.bytes} bytes)`);
1778
+ }
1779
+ catch (error) {
1780
+ throw freshSafeFileError(error);
1781
+ }
1782
+ }
1783
+ // Streams one verified download into a freshly reserved sibling temp file
1784
+ // (mode 0644: DuckDB writes a WAL beside the file, unlike the read-only libsql
1785
+ // replica) and returns its path; on any failure the temp file is removed.
1786
+ async function downloadDuckdbToTemp(io, target, object) {
1787
+ const { temp, handle } = await reserveDestinationTemp(io, target);
1788
+ try {
1789
+ await (0, database_download_1.downloadDuckdbObject)(object, handle.createWriteStream(), io.dataPlaneTimeoutMs);
1790
+ await handle.close();
1791
+ await io.filesystem.chmod(temp, 0o644);
1792
+ return temp;
1793
+ }
1794
+ catch (error) {
1795
+ try {
1796
+ await handle.close();
1797
+ }
1798
+ catch {
1799
+ // The write stream closes the handle itself once it has finished or failed.
1800
+ }
1801
+ await removeOwnedFiles(io.filesystem, [temp]);
1802
+ throw error;
1803
+ }
1804
+ }
1805
+ function stableVersionsResponse(data) {
1806
+ if (!data || !Array.isArray(data.versions)) {
1807
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1808
+ }
1809
+ return {
1810
+ database: stableDatabaseRecord(data.database),
1811
+ versions: data.versions.map((entry) => {
1812
+ if (!entry
1813
+ || !isPositiveInteger(entry.version)
1814
+ || typeof entry.state !== 'string'
1815
+ || typeof entry.bytes !== 'number'
1816
+ || typeof entry.stored_bytes !== 'number'
1817
+ || (entry.published_at !== null && typeof entry.published_at !== 'string')
1818
+ || (entry.run_uuid !== null && typeof entry.run_uuid !== 'string')
1819
+ || typeof entry.latest !== 'boolean') {
1820
+ throw new database_data_plane_1.DatabaseOperationError('upstream_unavailable', 'The database response was invalid.');
1821
+ }
1822
+ return {
1823
+ version: entry.version,
1824
+ state: entry.state,
1825
+ bytes: entry.bytes,
1826
+ stored_bytes: entry.stored_bytes,
1827
+ published_at: entry.published_at,
1828
+ run_uuid: entry.run_uuid,
1829
+ latest: entry.latest,
1830
+ };
1831
+ }),
1832
+ };
1833
+ }
1834
+ const VERSIONS_LIMIT_MAX = 200;
1835
+ async function databaseVersionsWithConfig(name, options, config, dependencies = {}) {
1836
+ const io = resolveDependencies(dependencies);
1837
+ if (options.limit !== undefined && (!isPositiveInteger(options.limit) || options.limit > VERSIONS_LIMIT_MAX)) {
1838
+ throw new database_data_plane_1.DatabaseOperationError('invalid_limit', `--limit must be a whole number between 1 and ${VERSIONS_LIMIT_MAX} (received "${options.limit}").`);
1839
+ }
1840
+ const data = stableVersionsResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'versions', name, ...(options.limit === undefined ? {} : { limit: options.limit }) }, requestDependencies(io)));
1841
+ if (options.json) {
1842
+ writeJson(io.stdout, data);
1843
+ return;
1844
+ }
1845
+ if (data.versions.length === 0) {
1846
+ io.stdout('No published versions yet.');
1847
+ return;
1848
+ }
1849
+ io.stdout((0, table_1.renderTable)(['VERSION', 'PUBLISHED', 'SIZE', 'RUN'], data.versions.map((entry) => [
1850
+ entry.latest ? `${entry.version} (latest)` : String(entry.version),
1851
+ entry.published_at ?? '-',
1852
+ formatByteSize(entry.bytes),
1853
+ entry.run_uuid ?? '-',
1854
+ ])).join('\n'));
1855
+ }
1856
+ async function databaseRollbackWithConfig(name, version, options, config, dependencies = {}) {
1857
+ const io = resolveDependencies(dependencies);
1858
+ const versionNumber = parseStrictPositiveInteger(version);
1859
+ if (!isPositiveInteger(versionNumber)) {
1860
+ throw new database_data_plane_1.DatabaseOperationError('invalid_version', 'The version must be a whole number of 1 or more.');
1861
+ }
1862
+ if (!options.yes) {
1863
+ if (options.json || !io.isTTY) {
1864
+ throw new database_data_plane_1.DatabaseOperationError('confirmation_required', 'Rolling back a database requires --yes in JSON or non-interactive mode.');
1865
+ }
1866
+ if (!await io.confirm(`Roll back database "${name}" to version ${versionNumber}?`)) {
1867
+ io.stdout('Cancelled.');
1868
+ return;
1869
+ }
1870
+ }
1871
+ const data = stableDatabaseResponse(await (0, database_data_plane_1.requestDatabaseOperation)(config, { operation: 'rollback', name, version: versionNumber }, requestDependencies(io)));
1872
+ if (options.json) {
1873
+ writeJson(io.stdout, data);
1874
+ return;
1875
+ }
1876
+ io.stdout(`Database "${data.database.name}" rolled back to version ${versionNumber}.\n${renderDatabaseTable([data.database])}`);
1877
+ }
1602
1878
  async function databaseList(options, dependencies = {}) {
1603
1879
  await databaseListWithConfig(options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1604
1880
  }
@@ -1629,6 +1905,12 @@ async function databaseDump(name, file, options, dependencies = {}) {
1629
1905
  async function databasePull(name, destination, options, dependencies = {}) {
1630
1906
  await databasePullWithConfig(name, destination, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1631
1907
  }
1908
+ async function databaseVersions(name, options, dependencies = {}) {
1909
+ await databaseVersionsWithConfig(name, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1910
+ }
1911
+ async function databaseRollback(name, version, options, dependencies = {}) {
1912
+ await databaseRollbackWithConfig(name, version, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1913
+ }
1632
1914
  async function databaseImport(name, file, options, dependencies = {}) {
1633
1915
  await databaseImportWithConfig(name, file, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
1634
1916
  }
@@ -1893,7 +2175,7 @@ async function databaseDropTableWithConfig(name, table, options, config, depende
1893
2175
  writeJson(io.stdout, data);
1894
2176
  return;
1895
2177
  }
1896
- io.stdout(`Dropped table "${table}" from "${name}". Size is now ${formatByteSize(data.database.size_bytes)}.`);
2178
+ io.stdout(`Dropped table "${table}" from "${name}". Size is now ${formatByteSize(databaseRecordSizeBytes(data.database))}.`);
1897
2179
  }
1898
2180
  async function databaseDropTable(name, table, options, dependencies = {}) {
1899
2181
  await databaseDropTableWithConfig(name, table, options, await (0, api_1.requireConfigWithWorkspace)(), dependencies);
package/dist/index.js CHANGED
@@ -76,6 +76,7 @@ const oauth_action_platforms_1 = require("./commands/oauth-action-platforms");
76
76
  const connection_connect_1 = require("./commands/connection-connect");
77
77
  const connection_wait_1 = require("./commands/connection-wait");
78
78
  const connection_list_1 = require("./commands/connection-list");
79
+ const app_preview_1 = require("./commands/app-preview");
79
80
  const workspaces_1 = require("./commands/workspaces");
80
81
  const skill_push_1 = require("./commands/skill-push");
81
82
  const skill_publish_1 = require("./commands/skill-publish");
@@ -138,6 +139,38 @@ exports.program
138
139
  .name('solidactions')
139
140
  .description('SolidActions CLI - Deploy and manage workflow automation')
140
141
  .version(pkg.version);
142
+ function takesGlobalOptionValue(root, arg) {
143
+ return root.options.some((option) => (option.required || option.optional) && option.is(arg));
144
+ }
145
+ function resolveNamedCommand(root, args, isRootVersionFlag) {
146
+ let command = root;
147
+ for (let i = 0; i < args.length; i++) {
148
+ const arg = args[i];
149
+ if (arg === '--' || isRootVersionFlag(arg))
150
+ break;
151
+ if (arg.length > 1 && arg.startsWith('-')) {
152
+ if (takesGlobalOptionValue(root, arg))
153
+ i++;
154
+ continue;
155
+ }
156
+ const next = command.commands.find((candidate) => candidate.name() === arg || candidate.aliases().includes(arg));
157
+ if (!next)
158
+ break;
159
+ command = next;
160
+ }
161
+ return command;
162
+ }
163
+ const rootVersionOption = exports.program.options.find((option) => option.long === '--version');
164
+ if (rootVersionOption) {
165
+ const matchesFlag = rootVersionOption.is.bind(rootVersionOption);
166
+ let namedCommand = exports.program;
167
+ rootVersionOption.is = (arg) => matchesFlag(arg) && !(namedCommand !== exports.program && namedCommand.options.some((option) => option.is(arg)));
168
+ const parseRootOptions = exports.program.parseOptions.bind(exports.program);
169
+ exports.program.parseOptions = (args) => {
170
+ namedCommand = resolveNamedCommand(exports.program, args, matchesFlag);
171
+ return parseRootOptions(args);
172
+ };
173
+ }
141
174
  // Long form is --workspace-override (NOT --workspace) — `login` already owns
142
175
  // `--workspace` for its own purpose (set the workspace at login time), and
143
176
  // commander silently drops a subcommand option whose long name collides with
@@ -265,7 +298,7 @@ driver): https://www.solidactions.com/docs/workspace-databases/`);
265
298
  database
266
299
  .command('list')
267
300
  .description('List workspace databases')
268
- .option('--kind <kind>', 'Filter by kind: libsql or duckdb')
301
+ .option('--kind <kind>', 'Filter by kind: libsql, duckdb or duckdb_file')
269
302
  .option('--json', 'Output as JSON')
270
303
  .action(async (options) => {
271
304
  await (0, database_1.databaseList)(options);
@@ -274,7 +307,7 @@ database
274
307
  .command('create')
275
308
  .description('Create a workspace database')
276
309
  .argument('<name>', 'Database name')
277
- .option('--kind <kind>', 'Database kind: libsql (default) or duckdb', 'libsql')
310
+ .option('--kind <kind>', 'Database kind: libsql (default), duckdb or duckdb_file (a DuckDB database file that workflows open, change and publish)', 'libsql')
278
311
  .option('--from <file.sql>', 'Import a SQL file after creation')
279
312
  .option('--no-wait', 'Do not wait for analytical (duckdb) provisioning to finish')
280
313
  .option('--json', 'Output as JSON')
@@ -350,9 +383,33 @@ database
350
383
  .argument('[path]', 'Destination path')
351
384
  .option('-y, --yes', 'Overwrite without confirmation')
352
385
  .option('--writable', 'Open a foreground writable session')
386
+ .option('--version <n>', 'DuckDB databases: pull this published version instead of the latest', (value) => (0, database_1.parseStrictPositiveInteger)(value))
387
+ .addHelpText('after', `
388
+ A DuckDB database (--kind duckdb_file) is saved to .solidactions/databases/<name>.duckdb
389
+ unless you give a path. Pulling it needs Node 22.15 or newer. List its versions with
390
+ \`solidactions database versions <name>\`.`)
353
391
  .action(async (name, destination, options) => {
354
392
  await (0, database_1.databasePull)(name, destination, options);
355
393
  });
394
+ database
395
+ .command('versions')
396
+ .description('List the published versions of a DuckDB database, newest first')
397
+ .argument('<name>', 'Database name')
398
+ .option('--limit <n>', 'How many versions to list (1-200)', (value) => (0, database_1.parseStrictPositiveInteger)(value))
399
+ .option('--json', 'Output as JSON')
400
+ .action(async (name, options) => {
401
+ await (0, database_1.databaseVersions)(name, options);
402
+ });
403
+ database
404
+ .command('rollback')
405
+ .description('Make an earlier published version of a DuckDB database the current one')
406
+ .argument('<name>', 'Database name')
407
+ .argument('<version>', 'Version number to roll back to')
408
+ .option('-y, --yes', 'Skip confirmation')
409
+ .option('--json', 'Output as JSON')
410
+ .action(async (name, version, options) => {
411
+ await (0, database_1.databaseRollback)(name, version, options);
412
+ });
356
413
  database
357
414
  .command('import')
358
415
  .description('Import a SQL file into a database')
@@ -924,6 +981,26 @@ connection
924
981
  (0, connection_wait_1.connectionWait)(requestId, options);
925
982
  });
926
983
  // =============================================================================
984
+ // app <subcommand>
985
+ // =============================================================================
986
+ const app = exports.program.command('app').description('Try an app before it ships');
987
+ app
988
+ .command('preview')
989
+ .description("Print a one-time link that opens an app's dev copy in your own browser, no login")
990
+ .argument('<app>', 'App name, or the slug of any of its environment rows')
991
+ .option('--page <id>', "Open this page first (the page's numeric doc id)")
992
+ .addHelpText('after', `
993
+ The link opens the app's dev copy only, never production, as you. It works once and
994
+ must be opened within 60 seconds. The session ends after 3 minutes without use or
995
+ 10 minutes in all; ask again for a new link when it ends. The CLI does not open a browser.
996
+
997
+ For agents: before you call an app change done, run this, open the link in your own
998
+ browser and try the app on the dev copy (open pages, press buttons, fill forms).
999
+ Deploy to dev first: solidactions project deploy <app> . -e dev`)
1000
+ .action(async (appName, options) => {
1001
+ await (0, app_preview_1.appPreview)(appName, options);
1002
+ });
1003
+ // =============================================================================
927
1004
  // ai <subcommand>
928
1005
  // =============================================================================
929
1006
  const ai = exports.program.command('ai').description('AI helper tools');
@@ -0,0 +1,114 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.DuckdbLinkExpiredError = void 0;
7
+ exports.zstdDecompressAvailable = zstdDecompressAvailable;
8
+ exports.downloadDuckdbObject = downloadDuckdbObject;
9
+ const axios_1 = __importDefault(require("axios"));
10
+ const crypto_1 = require("crypto");
11
+ const stream_1 = require("stream");
12
+ const promises_1 = require("stream/promises");
13
+ const zlib_1 = __importDefault(require("zlib"));
14
+ const database_data_plane_1 = require("./database-data-plane");
15
+ /** The link was refused (HTTP 403): it expired, so the caller asks for a fresh one. */
16
+ class DuckdbLinkExpiredError extends Error {
17
+ constructor() {
18
+ super('The download link expired.');
19
+ delete this.stack;
20
+ }
21
+ }
22
+ exports.DuckdbLinkExpiredError = DuckdbLinkExpiredError;
23
+ /** True when this Node can decompress zstd without a dependency. */
24
+ function zstdDecompressAvailable() {
25
+ return typeof zlib_1.default.createZstdDecompress === 'function';
26
+ }
27
+ function createZstdDecompress() {
28
+ return zlib_1.default.createZstdDecompress();
29
+ }
30
+ function corrupt() {
31
+ return new database_data_plane_1.DatabaseOperationError('download_corrupt', 'The downloaded database did not match its recorded size and checksum. Nothing was saved.');
32
+ }
33
+ /** Counts the bytes passing through and refuses to pass more than `limit`. */
34
+ function meter(limit, onChunk) {
35
+ let count = 0;
36
+ const stream = new stream_1.Transform({
37
+ transform(chunk, _encoding, callback) {
38
+ count += chunk.length;
39
+ if (count > limit) {
40
+ callback(corrupt());
41
+ return;
42
+ }
43
+ onChunk?.(chunk);
44
+ callback(null, chunk);
45
+ },
46
+ });
47
+ return { stream, count: () => count };
48
+ }
49
+ /**
50
+ * Stream a DuckDB database file from its signed link into `sink`: the stored
51
+ * (zstd) bytes are counted and hashed on the way in, decompressed, and the
52
+ * decompressed bytes counted on the way out. Every figure must match what the
53
+ * app recorded or the download is `download_corrupt`. The sink is left for the
54
+ * caller to remove on failure; the link is never part of an error message.
55
+ * `timeoutMs` bounds the wait for the response and any stall in the body (idle
56
+ * time between chunks, not the whole download).
57
+ */
58
+ async function downloadDuckdbObject(object, sink, timeoutMs) {
59
+ let response;
60
+ try {
61
+ response = await axios_1.default.get(object.url, { responseType: 'stream', validateStatus: () => true, timeout: timeoutMs });
62
+ }
63
+ catch {
64
+ throw new database_data_plane_1.DatabaseOperationError('download_failed', 'The database download could not be started.');
65
+ }
66
+ if (response.status === 403) {
67
+ response.data.destroy?.();
68
+ throw new DuckdbLinkExpiredError();
69
+ }
70
+ if (response.status < 200 || response.status >= 300) {
71
+ response.data.destroy?.();
72
+ throw new database_data_plane_1.DatabaseOperationError('download_failed', `The database download failed with HTTP ${response.status}.`);
73
+ }
74
+ const hash = (0, crypto_1.createHash)('sha256');
75
+ const storedMeter = meter(object.stored_bytes, (chunk) => { hash.update(chunk); });
76
+ const rawMeter = meter(object.bytes);
77
+ const decompress = createZstdDecompress();
78
+ // The first failure to surface is the cause: a decode error makes the
79
+ // pipeline destroy the source, whose own error must not hide it.
80
+ let firstFailure;
81
+ response.data.on('error', () => { firstFailure ??= 'transport'; });
82
+ decompress.on('error', () => { firstFailure ??= 'decode'; });
83
+ // A server that sends headers and then goes quiet is a failed download.
84
+ let idle;
85
+ const armIdleTimer = () => {
86
+ if (timeoutMs === undefined)
87
+ return;
88
+ clearTimeout(idle);
89
+ idle = setTimeout(() => { response.data.destroy(new Error('The database download stalled.')); }, timeoutMs);
90
+ };
91
+ response.data.on('data', armIdleTimer);
92
+ armIdleTimer();
93
+ try {
94
+ await (0, promises_1.pipeline)(response.data, storedMeter.stream, decompress, rawMeter.stream, sink);
95
+ }
96
+ catch (error) {
97
+ if (error instanceof database_data_plane_1.DatabaseOperationError)
98
+ throw error;
99
+ if (firstFailure === 'decode')
100
+ throw corrupt();
101
+ if (firstFailure === 'transport') {
102
+ throw new database_data_plane_1.DatabaseOperationError('download_failed', 'The database download was interrupted.');
103
+ }
104
+ throw error;
105
+ }
106
+ finally {
107
+ clearTimeout(idle);
108
+ }
109
+ if (storedMeter.count() !== object.stored_bytes
110
+ || rawMeter.count() !== object.bytes
111
+ || hash.digest('hex') !== object.sha256) {
112
+ throw corrupt();
113
+ }
114
+ }
package/dist/utils/mcp.js CHANGED
@@ -47,6 +47,7 @@ exports.McpRpcError = void 0;
47
47
  exports.retryAfterSeconds = retryAfterSeconds;
48
48
  exports.resolveCrewsCall = resolveCrewsCall;
49
49
  exports.callCrewsTool = callCrewsTool;
50
+ exports.callProjectsSandbox = callProjectsSandbox;
50
51
  exports.resolveDocsCall = resolveDocsCall;
51
52
  exports.callDocsTool = callDocsTool;
52
53
  exports.callCrewsToolContent = callCrewsToolContent;
@@ -254,6 +255,10 @@ async function callCrewsTool(config, toolName, args) {
254
255
  }
255
256
  return callMcpTool(config, UNIFIED_MCP_PATH, toolName, args);
256
257
  }
258
+ /** Call the projects_sandbox MCP tool (the app's dev-copy actions: exec, status, clear, promote, preview_link). */
259
+ async function callProjectsSandbox(config, args) {
260
+ return callMcpTool(config, UNIFIED_MCP_PATH, 'projects_sandbox', args);
261
+ }
257
262
  // Current catalog (solidactions-app ToolCatalog.php): the public docs tool depends on the action.
258
263
  // Call sites send the public action names, so only the tool is routed (no action/param renames).
259
264
  // Only actions the CLI actually sends are routed; anything else throws in resolveDocsCall.
@@ -49,6 +49,8 @@ exports.MUTATING_COMMANDS = new Set([
49
49
  'database exec',
50
50
  'database import',
51
51
  'database push',
52
+ // Makes an earlier published version of a DuckDB database the current one.
53
+ 'database rollback',
52
54
  'database ingest',
53
55
  // Export creates durable operation rows and temporary R2 objects and may
54
56
  // wake billed compute, even though authorization is read-capability based.
@@ -102,6 +104,8 @@ exports.MUTATING_COMMANDS = new Set([
102
104
  'doc upload',
103
105
  // POSTs a connect-link request (a row the workspace counts against its open-link limit).
104
106
  'connection connect',
107
+ // Mints a preview session row (counts against the workspace's mint limit); the link itself changes nothing until it is opened.
108
+ 'app preview',
105
109
  ]);
106
110
  /** Space-joined command paths that do not mutate server state. */
107
111
  exports.READONLY_COMMANDS = new Set([
@@ -115,6 +119,8 @@ exports.READONLY_COMMANDS = new Set([
115
119
  'database show',
116
120
  'database schema',
117
121
  'database query',
122
+ // Lists published versions; changes nothing.
123
+ 'database versions',
118
124
  // `connect` never calls the server's admission gate — it is a pure,
119
125
  // synchronous read of the database row (no side effects at all).
120
126
  'database connect',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solidactions/cli",
3
- "version": "3.34.0",
3
+ "version": "3.36.0",
4
4
  "description": "SolidActions CLI - Deploy and manage workflow automation",
5
5
  "main": "dist/index.js",
6
6
  "bin": {