@solidactions/cli 3.38.0 → 3.40.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
@@ -100,6 +100,7 @@ active workspace. The complete command surface is:
100
100
 
101
101
  ```bash
102
102
  solidactions database list --json
103
+ solidactions database list --include-deleted --json
103
104
  solidactions database create analytics --from backup.sql --json
104
105
  solidactions database delete analytics --yes --json
105
106
  solidactions database undelete analytics --json
@@ -109,6 +110,7 @@ solidactions database exec analytics "DELETE FROM events WHERE expired = 1" --ye
109
110
  solidactions database dump analytics backup.sql --yes
110
111
  solidactions database pull analytics .solidactions/databases/analytics.db --yes
111
112
  solidactions database pull analytics --writable
113
+ solidactions database pull analytics --no-cache
112
114
  solidactions database import analytics backup.sql --yes
113
115
  solidactions database import analytics backup.sql --resume <checkpoint> --yes
114
116
  solidactions database push analytics complete.db --yes
@@ -132,11 +134,15 @@ solidactions database versions metrics --limit 20 --json
132
134
  solidactions database rollback metrics 2 --yes --json
133
135
  ```
134
136
 
137
+ `database pull` fetches only what changed since your last pull of the same database and keeps a hidden cache per database in `~/.solidactions/cache/database-replicas`; use `--no-cache` to skip it. Inside a workflow or function, query the database directly instead of pulling (`ctx.vars` with `createDatabaseClient`). Pull only for local analysis, keep and reuse one copy, and never pull per test or per preview.
138
+
135
139
  `--json` produces machine-readable output where supported. `delete`, `exec`,
136
140
  `dump` overwrites, `pull` overwrites, `drop-table`, and `import` prompt before
137
141
  changing data; use `--yes` only when that change is already approved. A
138
142
  database `delete` is a soft-delete, and its output shows the purge clock
139
- during which `undelete` can restore it (either kind).
143
+ during which `undelete` can restore it (either kind). A deleted database
144
+ stays visible to `database list --include-deleted` until it is purged;
145
+ the default `database list` shows live databases only.
140
146
 
141
147
  `create --kind` defaults to the standard (SQLite) kind; pass `--kind duckdb`
142
148
  for an analytical database (waits for provisioning unless `--no-wait`).
@@ -150,7 +156,12 @@ refuse an analytical name with a one-line hint.
150
156
 
151
157
  `create --kind duckdb_file` makes a DuckDB database file that your workflows
152
158
  open, change and publish as numbered versions; it has no `--from`, `ingest` or
153
- `exec` (change it from a workflow). `pull <name> [path]` downloads the latest
159
+ `exec` (change it from a workflow). Open it from a workflow with `openAnalytics`
160
+ from `@solidactions/sdk` 0.11.0 or newer (add `@duckdb/node-api` as a normal
161
+ dependency). The analytical verbs — `ingest`, `export`, `drop-table`,
162
+ `optimize`, `connect` and `wake` — do not apply to it: they are refused with
163
+ `kind_mismatch`, naming the kind and pointing at `query`, `schema`, `pull`,
164
+ `versions` and `rollback`. `pull <name> [path]` downloads the latest
154
165
  published version as a plain DuckDB file (default
155
166
  `.solidactions/databases/<name>.duckdb`; `--version <n>` picks an older one;
156
167
  needs Node 22.15 or newer), verifies its size and checksum, and refuses a
@@ -158,8 +169,7 @@ download that does not match. It also refuses to pull over a target that has a
158
169
  `<path>.wal` write-ahead file beside it, even with `--yes`: close the program
159
170
  that has the database open (or remove that file) and pull again. `versions <name>` lists the published versions,
160
171
  newest first, and `rollback <name> <version>` makes an earlier one current
161
- after a `--yes` confirmation. `query` and `schema` answer that queries on
162
- DuckDB databases arrive with the next release.
172
+ after a `--yes` confirmation. `query` and `schema` read the latest published version (read-only SQL on that version; `--limit` asks for fewer rows, and the server caps the rows it returns, 1000 by default) and answer `no_published_version` until a workflow has published one.
163
173
 
164
174
  `ingest --mode replace` overwrites a table's contents with no `--yes` prompt
165
175
  (unlike `drop-table`, which is a separate, rarer, schema-shaped operation) —
@@ -371,7 +381,7 @@ env:
371
381
  - A global key, an `oauth:` name, and a `database:` name are **mutually exclusive**: bind each variable to exactly one. The platform enforces that server-side (HTTP 422), but do not rely on seeing that error: through CLI v3.6.0 the YAML parser keeps only the first form it recognizes — `oauth:` beats `database:` — so a declaration carrying both deploys silently as the wrong binding instead of failing.
372
382
  - `project deploy` (including `--config-only`) syncs the *complete* `env:` list to the server on every run. Any previously YAML-sourced mapping whose name no longer appears in the list is deleted — removing or emptying `env:` prunes those mappings on the next deploy. Only mappings that were never YAML-declared survive: overriding a YAML-declared variable with `env set`/`env map` doesn't change its provenance, so removing its declaration still deletes the mapping.
373
383
  - Create the workspace database first with `solidactions database create <name>` or in the web UI. Workspace-database bindings require `@solidactions/sdk >=0.8.0`.
374
- - For a `database:` entry, the workflow receives a typed `DatabaseVar` at `ctx.vars.<NAME>` at runtime, typically wrapped with the SDK's `createDatabaseClient()`. The private transport payload uses `read_only`; SDK 0.8.0+ normalizes it to the public `DatabaseVar.readOnly` property. Use the typed SDK object rather than parsing the transport payload. See the SDK reference's [Workspace Databases](https://github.com/SolidActions/solidactions-ts-sdk/blob/main/docs/sdk-reference.md#workspace-databases) section for details.
384
+ - For a standard (libSQL) database, the workflow receives a typed `DatabaseVar` at `ctx.vars.<NAME>` at runtime, typically wrapped with the SDK's `createDatabaseClient()`; a `duckdb_file` database instead gets a plain database id string for `openAnalytics` (see the DuckDB database file paragraph above; needs `@solidactions/sdk` 0.11.0 or newer). The private transport payload uses `read_only`; SDK 0.8.0+ normalizes it to the public `DatabaseVar.readOnly` property. Use the typed SDK object rather than parsing the transport payload. See the SDK reference's [Workspace Databases](https://github.com/SolidActions/solidactions-ts-sdk/blob/main/docs/sdk-reference.md#workspace-databases) section for details.
375
385
 
376
386
  ## Commands
377
387
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema_version": 1,
3
3
  "cli_name": "solidactions",
4
- "cli_version": "3.38.0",
4
+ "cli_version": "3.40.0",
5
5
  "global_options": [
6
6
  {
7
7
  "flags": "-V, --version",
@@ -411,6 +411,18 @@
411
411
  "negated": false,
412
412
  "hidden": false
413
413
  },
414
+ {
415
+ "flags": "--include-deleted",
416
+ "long": "--include-deleted",
417
+ "short": null,
418
+ "description": "Include deleted databases (they can be restored with database undelete until they are purged)",
419
+ "required": false,
420
+ "value_required": false,
421
+ "value_optional": false,
422
+ "variadic": false,
423
+ "negated": false,
424
+ "hidden": false
425
+ },
414
426
  {
415
427
  "flags": "--json",
416
428
  "long": "--json",
@@ -570,7 +582,7 @@
570
582
  ],
571
583
  "name": "delete",
572
584
  "aliases": [],
573
- "description": "Delete a workspace database",
585
+ "description": "Delete a workspace database (soft-delete: database list --include-deleted still shows it until purged; restore with database undelete)",
574
586
  "hidden": false,
575
587
  "arguments": [
576
588
  {
@@ -626,7 +638,7 @@
626
638
  ],
627
639
  "name": "undelete",
628
640
  "aliases": [],
629
- "description": "Restore a deleted workspace database",
641
+ "description": "Restore a deleted workspace database (find it with database list --include-deleted)",
630
642
  "hidden": false,
631
643
  "arguments": [
632
644
  {
@@ -735,7 +747,7 @@
735
747
  "flags": "--limit <n>",
736
748
  "long": "--limit",
737
749
  "short": null,
738
- "description": "Row cap for analytical queries (max 10000)",
750
+ "description": "Maximum rows to return (analytical databases: up to 10000; DuckDB database files: the server caps it, 1000 by default)",
739
751
  "required": false,
740
752
  "value_required": true,
741
753
  "value_optional": false,
@@ -941,6 +953,19 @@
941
953
  "negated": false,
942
954
  "hidden": false
943
955
  },
956
+ {
957
+ "flags": "--no-cache",
958
+ "long": "--no-cache",
959
+ "short": null,
960
+ "description": "Do not read or write the local replica cache for this pull",
961
+ "required": false,
962
+ "value_required": false,
963
+ "value_optional": false,
964
+ "variadic": false,
965
+ "negated": true,
966
+ "hidden": false,
967
+ "default": true
968
+ },
944
969
  {
945
970
  "flags": "-h, --help",
946
971
  "long": "--help",
@@ -47,6 +47,7 @@ const promises_1 = require("stream/promises");
47
47
  const stream_1 = require("stream");
48
48
  const api_1 = require("../utils/api");
49
49
  const database_data_plane_1 = require("../utils/database-data-plane");
50
+ const database_kind_refusal_1 = require("../utils/database-kind-refusal");
50
51
  const database_1 = require("./database");
51
52
  function safeDownloadUrl(value) {
52
53
  if (typeof value !== 'string')
@@ -358,8 +359,9 @@ async function databaseExportWithConfig(name, options, config, dependencies = {}
358
359
  if (options.resume && options.wait === false)
359
360
  throw new ExportCommandError('invalid_arguments', '--no-wait cannot be combined with --resume. Resume waits for and downloads the existing export.');
360
361
  const database = await (0, database_1.requestDatabaseRecord)(name, config);
361
- if (database.kind !== 'duckdb')
362
- throw new ExportCommandError('kind_mismatch', `"${name}" is not an analytical database — \`database export\` only works on analytical (duckdb) databases.`);
362
+ const exportRefusal = (0, database_kind_refusal_1.analyticalVerbKindMismatch)(name, database, 'export');
363
+ if (exportRefusal)
364
+ throw new ExportCommandError(exportRefusal.code, exportRefusal.message);
363
365
  let metadata;
364
366
  if (options.resume) {
365
367
  try {