@solidactions/cli 3.33.0 → 3.35.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
@@ -331,6 +349,10 @@ revision after the build. Use `--no-git-metadata` or
331
349
  `SOLIDACTIONS_NO_GIT_METADATA=1` to opt out. Deploying a non-Git directory
332
350
  continues normally without revision metadata.
333
351
 
352
+ ### Source of truth and sandbox deploys
353
+
354
+ Every app records whether `git` or `solidactions` owns its source (Settings, "Source of truth"). When the source of truth is git, a deploy made from a sandbox (with its project-scoped token) is refused with `source_of_truth_git`; deploys from your laptop or CI are never refused. To deploy from the sandbox anyway, pass `--override-source-of-truth`: the CLI sends it on every call the deploy makes (functions, config, pages, app settings and the source archive). The deploy is stored and the app shows as drifted until you mark it reconciled in the app's settings or flip its source of truth to SolidActions. While an app is drifted, every deploy prints `Warning: this app is drifted: deployed outside git since <date>. Mark it reconciled in the app's settings, or flip its source of truth to SolidActions.` Apps whose source of truth is SolidActions never warn or refuse.
355
+
334
356
  ### Env declarations (`solidactions.yaml`)
335
357
 
336
358
  Declare the variables a workflow needs with an `env:` list in `solidactions.yaml`. Each entry uses one of four forms:
@@ -369,7 +391,7 @@ Use `solidactions <command> --help` for full flag details on any command.
369
391
  | Command | Key Flags | Description |
370
392
  |---------|-----------|-------------|
371
393
  | `project create <name>` | `-e` | Create an empty project (no source/build); `-e` defaults to `production` |
372
- | `project deploy <name> [path]` | `-e`, `--create`, `--config-only`, `--paused`, `--no-git-metadata` | Deploy or sync config only; optionally land YAML schedules paused |
394
+ | `project deploy <name> [path]` | `-e`, `--create`, `--config-only`, `--paused`, `--override-source-of-truth`, `--no-git-metadata` | Deploy or sync config only; optionally land YAML schedules paused; deploy from a sandbox over a git-owned app |
373
395
  | `project enable <project>` | `-e` (default `dev`) | Allow new starts through this project gate |
374
396
  | `project disable <project>` | `-e` (default `dev`) | Block new root starts without cancelling existing roots |
375
397
  | `project view <project>` | `-e` (default `dev`), `--json` | View status, `Enabled: on|off`, and client-reported deployed revision, incl. an `N behind origin/<branch> at deploy` drift clause when the deployment is behind the default branch |
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "cli_name": "solidactions",
4
- "cli_version": "3.33.0",
4
+ "cli_version": "3.35.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",
@@ -1694,6 +1824,18 @@
1694
1824
  "negated": false,
1695
1825
  "hidden": false
1696
1826
  },
1827
+ {
1828
+ "flags": "--override-source-of-truth",
1829
+ "long": "--override-source-of-truth",
1830
+ "short": null,
1831
+ "description": "Deploy from a sandbox even though the app's source of truth is git; the app shows as drifted until you mark it reconciled or flip its source of truth to SolidActions",
1832
+ "required": false,
1833
+ "value_required": false,
1834
+ "value_optional": false,
1835
+ "variadic": false,
1836
+ "negated": false,
1837
+ "hidden": false
1838
+ },
1697
1839
  {
1698
1840
  "flags": "--no-cache",
1699
1841
  "long": "--no-cache",
@@ -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);
@@ -32,6 +32,7 @@ const app_sync_1 = require("../utils/app-sync");
32
32
  const pages_sync_1 = require("../utils/pages-sync");
33
33
  const functions_sync_1 = require("../utils/functions-sync");
34
34
  const api_1 = require("../utils/api");
35
+ const source_of_truth_1 = require("../utils/source-of-truth");
35
36
  const host_display_1 = require("../utils/host-display");
36
37
  const deploy_ignore_1 = require("../utils/deploy-ignore");
37
38
  const sandbox_base_1 = require("../utils/sandbox-base");
@@ -290,7 +291,7 @@ function formatSyncYamlWarnings(warnings) {
290
291
  * (PM round #1127 finding 14: a failed sync must never be reported as
291
292
  * success by the caller).
292
293
  */
293
- async function pushYamlDeclarations(config, projectSlug, yamlConfig, baseSourceHash) {
294
+ async function pushYamlDeclarations(config, projectSlug, yamlConfig, baseSourceHash, overrideSourceOfTruth) {
294
295
  const parsedVars = (0, env_1.parseYamlEnvVars)(yamlConfig);
295
296
  // Build the declarations array
296
297
  const declarations = parsedVars.map(v => ({
@@ -301,7 +302,7 @@ async function pushYamlDeclarations(config, projectSlug, yamlConfig, baseSourceH
301
302
  yaml_default_docs_path: v.docsPath,
302
303
  source: 'yaml',
303
304
  }));
304
- const response = await axios_1.default.post(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings/sync-yaml`, { declarations, ...(baseSourceHash !== undefined ? { base_source_hash: baseSourceHash } : {}) }, {
305
+ const response = await axios_1.default.post(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings/sync-yaml`, (0, source_of_truth_1.withOverrideSourceOfTruth)({ declarations, ...(baseSourceHash !== undefined ? { base_source_hash: baseSourceHash } : {}) }, overrideSourceOfTruth), {
305
306
  headers: (0, api_1.getApiHeaders)(config, 'application/json'),
306
307
  });
307
308
  // Non-fatal: a warning means a declared resource doesn't exist in the
@@ -623,12 +624,16 @@ async function deploy(projectName, sourcePath, options = {}) {
623
624
  process.exit(1);
624
625
  }
625
626
  try {
626
- await pushYamlDeclarations(config, projectSlug, yamlConfig, guardedBaseWire ?? undefined);
627
+ await pushYamlDeclarations(config, projectSlug, yamlConfig, guardedBaseWire ?? undefined, options.overrideSourceOfTruth);
627
628
  }
628
629
  catch (error) {
630
+ const refusal = (0, source_of_truth_1.sourceOfTruthRefusal)(error.response?.status, error.response?.data);
629
631
  if (error.response?.status === 409 && error.response.data?.code === 'stale_base') {
630
632
  console.error(chalk_1.default.red(staleBaseLine()));
631
633
  }
634
+ else if (refusal !== null) {
635
+ console.error(chalk_1.default.red(refusal));
636
+ }
632
637
  else if (error.response?.status === 401) {
633
638
  console.error(chalk_1.default.red((0, api_1.authFailedLine)(config.host)));
634
639
  }
@@ -677,11 +682,16 @@ async function deploy(projectName, sourcePath, options = {}) {
677
682
  const functionsPayload = (0, functions_sync_1.buildFunctionsSyncPayload)(functionFiles, functionSources, codeRef);
678
683
  if (guardedBaseWire !== null)
679
684
  functionsPayload.base_source_hash = guardedBaseWire;
680
- const functionsResult = await (0, functions_sync_1.syncFunctions)(config, projectSlug, functionsPayload);
685
+ const functionsResult = await (0, functions_sync_1.syncFunctions)(config, projectSlug, (0, source_of_truth_1.withOverrideSourceOfTruth)(functionsPayload, options.overrideSourceOfTruth));
681
686
  if (functionsResult.httpStatus === 409 && functionsResult.body?.code === 'stale_base') {
682
687
  console.error(chalk_1.default.red(staleBaseLine()));
683
688
  process.exit(1);
684
689
  }
690
+ const functionsRefusal = (0, source_of_truth_1.sourceOfTruthRefusal)(functionsResult.httpStatus, functionsResult.body);
691
+ if (functionsRefusal !== null) {
692
+ console.error(chalk_1.default.red(functionsRefusal));
693
+ process.exit(1);
694
+ }
685
695
  const functionRows = functionsResult.body?.functions ?? [];
686
696
  const retiredFunctions = functionsResult.body?.retired ?? [];
687
697
  const retireErrors = functionsResult.body?.retire_errors ?? [];
@@ -696,7 +706,7 @@ async function deploy(projectName, sourcePath, options = {}) {
696
706
  let yamlSyncFailed = false;
697
707
  if (yamlConfig) {
698
708
  try {
699
- await pushYamlDeclarations(config, projectSlug, yamlConfig);
709
+ await pushYamlDeclarations(config, projectSlug, yamlConfig, undefined, options.overrideSourceOfTruth);
700
710
  }
701
711
  catch (error) {
702
712
  yamlSyncFailed = true;
@@ -710,7 +720,7 @@ async function deploy(projectName, sourcePath, options = {}) {
710
720
  }
711
721
  for (const warning of (0, app_sync_1.emptyColourWarnings)(yamlConfig?.app))
712
722
  console.log(chalk_1.default.yellow(warning));
713
- const appResult = await (0, app_sync_1.syncApp)(config, projectSlug, (0, app_sync_1.buildAppSyncPayload)(yamlConfig ?? {}));
723
+ const appResult = await (0, app_sync_1.syncApp)(config, projectSlug, (0, source_of_truth_1.withOverrideSourceOfTruth)((0, app_sync_1.buildAppSyncPayload)(yamlConfig ?? {}), options.overrideSourceOfTruth));
714
724
  const appSummary = (0, app_sync_1.formatAppSync)(appResult, yamlConfig?.app != null);
715
725
  if (appResult.httpStatus === 401)
716
726
  console.error(chalk_1.default.red((0, api_1.authFailedLine)(config.host)));
@@ -722,7 +732,7 @@ async function deploy(projectName, sourcePath, options = {}) {
722
732
  }
723
733
  yamlSyncFailed = yamlSyncFailed || appSummary.failed;
724
734
  const payload = (0, pages_sync_1.buildPagesSyncPayload)(pageFiles, pageBodies, deploymentId, codeRef, bundledPages);
725
- const result = await (0, pages_sync_1.syncPages)(config, projectSlug, payload);
735
+ const result = await (0, pages_sync_1.syncPages)(config, projectSlug, (0, source_of_truth_1.withOverrideSourceOfTruth)(payload, options.overrideSourceOfTruth));
726
736
  const rows = result.body?.pages ?? [];
727
737
  const trashed = result.body?.trashed ?? [];
728
738
  const trashErrors = result.body?.trash_errors ?? [];
@@ -789,6 +799,9 @@ async function deploy(projectName, sourcePath, options = {}) {
789
799
  if (options.paused) {
790
800
  form.append('paused', '1');
791
801
  }
802
+ if (options.overrideSourceOfTruth === true) {
803
+ form.append('override_source_of_truth', '1');
804
+ }
792
805
  console.log(chalk_1.default.yellow('Uploading...'));
793
806
  if (process.env.SOLIDACTIONS_DEPLOY_DEBUG === '1') {
794
807
  process.stderr.write(`[deploy-debug] POST ${(0, host_display_1.displayHost)(config.host)}/api/v1/projects/${projectSlug}/deploy (workspace=${config.workspaceId ?? '(none)'})\n`);
@@ -809,6 +822,9 @@ async function deploy(projectName, sourcePath, options = {}) {
809
822
  console.log(chalk_1.default.yellow('The server stored different bytes than this deploy uploaded; base.json was left unchanged.'));
810
823
  }
811
824
  }
825
+ for (const line of (0, source_of_truth_1.driftWarningLines)(deployResponse.data)) {
826
+ console.log(chalk_1.default.yellow(line));
827
+ }
812
828
  if (!yamlConfig?.workflows) {
813
829
  console.log(chalk_1.default.green('Source archived.'));
814
830
  cleanupArchive();
@@ -892,9 +908,13 @@ async function deploy(projectName, sourcePath, options = {}) {
892
908
  catch (error) {
893
909
  console.error(chalk_1.default.red('Deployment failed:'));
894
910
  if (error.response) {
911
+ const refusal = (0, source_of_truth_1.sourceOfTruthRefusal)(error.response.status, error.response.data);
895
912
  if (error.response.status === 409 && error.response.data?.code === 'stale_base') {
896
913
  console.error(chalk_1.default.red(staleBaseLine()));
897
914
  }
915
+ else if (refusal !== null) {
916
+ console.error(chalk_1.default.red(refusal));
917
+ }
898
918
  else if (error.response.status === 404) {
899
919
  console.error("Project not found.");
900
920
  }
package/dist/index.js CHANGED
@@ -138,6 +138,38 @@ exports.program
138
138
  .name('solidactions')
139
139
  .description('SolidActions CLI - Deploy and manage workflow automation')
140
140
  .version(pkg.version);
141
+ function takesGlobalOptionValue(root, arg) {
142
+ return root.options.some((option) => (option.required || option.optional) && option.is(arg));
143
+ }
144
+ function resolveNamedCommand(root, args, isRootVersionFlag) {
145
+ let command = root;
146
+ for (let i = 0; i < args.length; i++) {
147
+ const arg = args[i];
148
+ if (arg === '--' || isRootVersionFlag(arg))
149
+ break;
150
+ if (arg.length > 1 && arg.startsWith('-')) {
151
+ if (takesGlobalOptionValue(root, arg))
152
+ i++;
153
+ continue;
154
+ }
155
+ const next = command.commands.find((candidate) => candidate.name() === arg || candidate.aliases().includes(arg));
156
+ if (!next)
157
+ break;
158
+ command = next;
159
+ }
160
+ return command;
161
+ }
162
+ const rootVersionOption = exports.program.options.find((option) => option.long === '--version');
163
+ if (rootVersionOption) {
164
+ const matchesFlag = rootVersionOption.is.bind(rootVersionOption);
165
+ let namedCommand = exports.program;
166
+ rootVersionOption.is = (arg) => matchesFlag(arg) && !(namedCommand !== exports.program && namedCommand.options.some((option) => option.is(arg)));
167
+ const parseRootOptions = exports.program.parseOptions.bind(exports.program);
168
+ exports.program.parseOptions = (args) => {
169
+ namedCommand = resolveNamedCommand(exports.program, args, matchesFlag);
170
+ return parseRootOptions(args);
171
+ };
172
+ }
141
173
  // Long form is --workspace-override (NOT --workspace) — `login` already owns
142
174
  // `--workspace` for its own purpose (set the workspace at login time), and
143
175
  // commander silently drops a subcommand option whose long name collides with
@@ -265,7 +297,7 @@ driver): https://www.solidactions.com/docs/workspace-databases/`);
265
297
  database
266
298
  .command('list')
267
299
  .description('List workspace databases')
268
- .option('--kind <kind>', 'Filter by kind: libsql or duckdb')
300
+ .option('--kind <kind>', 'Filter by kind: libsql, duckdb or duckdb_file')
269
301
  .option('--json', 'Output as JSON')
270
302
  .action(async (options) => {
271
303
  await (0, database_1.databaseList)(options);
@@ -274,7 +306,7 @@ database
274
306
  .command('create')
275
307
  .description('Create a workspace database')
276
308
  .argument('<name>', 'Database name')
277
- .option('--kind <kind>', 'Database kind: libsql (default) or duckdb', 'libsql')
309
+ .option('--kind <kind>', 'Database kind: libsql (default), duckdb or duckdb_file (a DuckDB database file that workflows open, change and publish)', 'libsql')
278
310
  .option('--from <file.sql>', 'Import a SQL file after creation')
279
311
  .option('--no-wait', 'Do not wait for analytical (duckdb) provisioning to finish')
280
312
  .option('--json', 'Output as JSON')
@@ -350,9 +382,33 @@ database
350
382
  .argument('[path]', 'Destination path')
351
383
  .option('-y, --yes', 'Overwrite without confirmation')
352
384
  .option('--writable', 'Open a foreground writable session')
385
+ .option('--version <n>', 'DuckDB databases: pull this published version instead of the latest', (value) => (0, database_1.parseStrictPositiveInteger)(value))
386
+ .addHelpText('after', `
387
+ A DuckDB database (--kind duckdb_file) is saved to .solidactions/databases/<name>.duckdb
388
+ unless you give a path. Pulling it needs Node 22.15 or newer. List its versions with
389
+ \`solidactions database versions <name>\`.`)
353
390
  .action(async (name, destination, options) => {
354
391
  await (0, database_1.databasePull)(name, destination, options);
355
392
  });
393
+ database
394
+ .command('versions')
395
+ .description('List the published versions of a DuckDB database, newest first')
396
+ .argument('<name>', 'Database name')
397
+ .option('--limit <n>', 'How many versions to list (1-200)', (value) => (0, database_1.parseStrictPositiveInteger)(value))
398
+ .option('--json', 'Output as JSON')
399
+ .action(async (name, options) => {
400
+ await (0, database_1.databaseVersions)(name, options);
401
+ });
402
+ database
403
+ .command('rollback')
404
+ .description('Make an earlier published version of a DuckDB database the current one')
405
+ .argument('<name>', 'Database name')
406
+ .argument('<version>', 'Version number to roll back to')
407
+ .option('-y, --yes', 'Skip confirmation')
408
+ .option('--json', 'Output as JSON')
409
+ .action(async (name, version, options) => {
410
+ await (0, database_1.databaseRollback)(name, version, options);
411
+ });
356
412
  database
357
413
  .command('import')
358
414
  .description('Import a SQL file into a database')
@@ -477,6 +533,7 @@ project
477
533
  .option('--create', 'Create environment project if it doesn\'t exist')
478
534
  .option('--config-only', 'Sync YAML env declarations without building/deploying')
479
535
  .option('--paused', 'Deploy with all YAML-declared schedules initially paused')
536
+ .option('--override-source-of-truth', 'Deploy from a sandbox even though the app\'s source of truth is git; the app shows as drifted until you mark it reconciled or flip its source of truth to SolidActions')
480
537
  .option('--no-cache', 'Force a fresh build, bypassing all build caches')
481
538
  .option('--force-rebuild', 'Force a fresh build, bypassing all build caches (alias for --no-cache)')
482
539
  .option('--no-git-metadata', 'Do not transmit Git provenance (branch, commit subject, and sanitized remote repository URL; credentials are stripped); also available as SOLIDACTIONS_NO_GIT_METADATA=1')
@@ -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
+ }
@@ -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.
@@ -115,6 +117,8 @@ exports.READONLY_COMMANDS = new Set([
115
117
  'database show',
116
118
  'database schema',
117
119
  'database query',
120
+ // Lists published versions; changes nothing.
121
+ 'database versions',
118
122
  // `connect` never calls the server's admission gate — it is a pure,
119
123
  // synchronous read of the database row (no side effects at all).
120
124
  'database connect',
@@ -0,0 +1,40 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.withOverrideSourceOfTruth = withOverrideSourceOfTruth;
4
+ exports.sourceOfTruthRefusal = sourceOfTruthRefusal;
5
+ exports.driftWarningLines = driftWarningLines;
6
+ const source_provenance_1 = require("./source-provenance");
7
+ /**
8
+ * Adds `override_source_of_truth: 1` to a JSON body only when the flag is set.
9
+ * When it is not set the SAME payload object comes back, so a deploy without
10
+ * the flag sends byte-identical bodies to today (design invariant 5).
11
+ */
12
+ function withOverrideSourceOfTruth(payload, override) {
13
+ return override === true ? { ...payload, override_source_of_truth: 1 } : payload;
14
+ }
15
+ /**
16
+ * The printable server message of a 409 `source_of_truth_git` refusal, or null
17
+ * when the response is anything else. The server text already names the repo
18
+ * and the override flag, so it is printed as is.
19
+ */
20
+ function sourceOfTruthRefusal(status, body) {
21
+ if (status !== 409 || body === null || typeof body !== 'object' || Array.isArray(body))
22
+ return null;
23
+ const record = body;
24
+ if (record.code !== 'source_of_truth_git')
25
+ return null;
26
+ return (0, source_provenance_1.sanitizeDisplayText)(record.message)
27
+ ?? 'This app\'s source of truth is git. Re-run with --override-source-of-truth to deploy from the sandbox anyway.';
28
+ }
29
+ /** One printable line per `warnings[]` entry with code `drift`; nothing for any other shape. */
30
+ function driftWarningLines(data) {
31
+ const warnings = data !== null && typeof data === 'object' ? data.warnings : undefined;
32
+ if (!Array.isArray(warnings))
33
+ return [];
34
+ return warnings.flatMap((warning) => {
35
+ if (warning === null || typeof warning !== 'object' || warning.code !== 'drift')
36
+ return [];
37
+ const since = (0, source_provenance_1.sanitizeDisplayText)(warning.since, 64) ?? 'an unknown date';
38
+ return [`Warning: this app is drifted: deployed outside git since ${since}. Mark it reconciled in the app's settings, or flip its source of truth to SolidActions.`];
39
+ });
40
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@solidactions/cli",
3
- "version": "3.33.0",
3
+ "version": "3.35.0",
4
4
  "description": "SolidActions CLI - Deploy and manage workflow automation",
5
5
  "main": "dist/index.js",
6
6
  "bin": {