@fadhilp/stateql 0.13.2 → 0.14.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 +29 -68
- package/dist/src/adapters.js +11 -4
- package/dist/src/cli.js +158 -21
- package/dist/src/errors.d.ts +1 -0
- package/dist/src/errors.js +40 -0
- package/dist/src/migrations.js +27 -2
- package/dist/src/mongodb.js +6 -2
- package/dist/src/redis.js +7 -4
- package/dist/src/sql.js +28 -3
- package/dist/src/stateql.d.ts +4 -1
- package/dist/src/stateql.js +78 -7
- package/dist/src/store.d.ts +5 -0
- package/dist/src/store.js +28 -15
- package/dist/src/table-editor.js +1 -1
- package/dist/src/types.d.ts +5 -1
- package/dist/src/util.d.ts +1 -0
- package/dist/src/util.js +1 -1
- package/docs/agents.md +72 -0
- package/docs/batch.md +49 -0
- package/docs/cli.md +152 -0
- package/docs/connections.md +84 -0
- package/docs/databases.md +5 -7
- package/docs/library.md +14 -5
- package/docs/results.md +78 -0
- package/docs/writes.md +40 -0
- package/package.json +3 -3
- package/docs/usage.md +0 -358
package/README.md
CHANGED
|
@@ -1,99 +1,60 @@
|
|
|
1
1
|
# StateQL
|
|
2
2
|
|
|
3
3
|
StateQL is a stateful database CLI and TypeScript library for AI agents and
|
|
4
|
-
automation.
|
|
5
|
-
|
|
4
|
+
automation. It keeps query results as durable handles, so later commands can
|
|
5
|
+
page, filter, count, or export them without querying the database again.
|
|
6
6
|
|
|
7
7
|
- **SQL:** SQLite, PostgreSQL, and MySQL.
|
|
8
8
|
- **Native commands:** MongoDB (EJSON) and Redis (JSON).
|
|
9
|
-
- **
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
where supported by the database.
|
|
9
|
+
- **Compact output:** one-line JSON with a 5-row preview and column names sent once.
|
|
10
|
+
- **Safe writes:** read-only by default, explicit approval for unbounded or
|
|
11
|
+
destructive statements, idempotency keys, plans, and staged transactions.
|
|
13
12
|
|
|
14
|
-
Requires **Node.js 22.16 or newer
|
|
13
|
+
Requires **Node.js 22.16 or newer**.
|
|
15
14
|
|
|
16
|
-
##
|
|
17
|
-
|
|
18
|
-
Install the CLI:
|
|
15
|
+
## Install
|
|
19
16
|
|
|
20
17
|
```bash
|
|
21
|
-
npm install -g @fadhilp/stateql
|
|
18
|
+
npm install -g @fadhilp/stateql # CLI (stql)
|
|
19
|
+
npm install @fadhilp/stateql # TypeScript library
|
|
22
20
|
```
|
|
23
21
|
|
|
24
|
-
|
|
25
|
-
examples use Bash; see the [usage guide](docs/usage.md) for connection options and
|
|
26
|
-
SQL parameter handling.
|
|
22
|
+
## Quick start
|
|
27
23
|
|
|
28
24
|
```bash
|
|
29
25
|
export STQL_SESSION=audit
|
|
30
|
-
stql
|
|
31
|
-
stql connect local
|
|
26
|
+
stql connect ./app.sqlite
|
|
32
27
|
|
|
33
|
-
stql query
|
|
34
|
-
"SELECT id, name, email FROM users WHERE status = ? AND created_at >= ? ORDER BY id LIMIT 50" \
|
|
35
|
-
--param active \
|
|
36
|
-
--param 2026-01-01
|
|
28
|
+
stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
|
|
37
29
|
```
|
|
38
30
|
|
|
39
|
-
Parameters keep values separate from SQL. `ORDER BY` makes paging stable, and
|
|
40
|
-
`LIMIT` bounds work at the database. The default `agent` output is compact,
|
|
41
|
-
one-line JSON. An example response:
|
|
42
|
-
|
|
43
31
|
```json
|
|
44
|
-
{"ok":true,"handle":"
|
|
32
|
+
{"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
|
|
45
33
|
```
|
|
46
34
|
|
|
47
|
-
|
|
48
|
-
Give the snapshot a readable alias, then work with the stored data:
|
|
35
|
+
Reuse the result by its handle. These commands do not access the database:
|
|
49
36
|
|
|
50
37
|
```bash
|
|
51
|
-
stql
|
|
52
|
-
stql
|
|
53
|
-
stql
|
|
54
|
-
stql export active-users --output active-users.csv --format csv
|
|
55
|
-
stql filter active-users "email LIKE ?" --param "%@example.com"
|
|
38
|
+
stql rows katcitg6un --offset 5 --limit 20
|
|
39
|
+
stql filter katcitg6un "name LIKE ?" --param "A%"
|
|
40
|
+
stql export katcitg6un --output users.csv
|
|
56
41
|
```
|
|
57
42
|
|
|
58
|
-
These commands do not access the original database. `filter` creates a new
|
|
59
|
-
snapshot with its own handle. Repeating a query can reuse a valid cached result;
|
|
60
|
-
use `--cache bypass` when a fresh database read is required.
|
|
61
|
-
|
|
62
|
-
## Safety and state
|
|
63
|
-
|
|
64
|
-
- Connections are **read-only by default**. Writes require a read-write connection.
|
|
65
|
-
- Destructive and unbounded SQL/MongoDB operations require independent
|
|
66
|
-
`--allow-destructive` and `--allow-unbounded` approvals, respectively.
|
|
67
|
-
- `plan` stores a write for review; `apply` never adds authorization. Use
|
|
68
|
-
idempotency keys to protect retryable writes from duplicate execution.
|
|
69
|
-
- A write reported as `OUTCOME_UNKNOWN` must be inspected at the database before
|
|
70
|
-
replaying it. Transactions are staged locally, not live interactive SQL
|
|
71
|
-
transactions.
|
|
72
|
-
- Supply credential-bearing URLs through environment variables or a trusted
|
|
73
|
-
library credential resolver, not literal command arguments or profiles.
|
|
74
|
-
- Results and history persist under `STQL_HOME` (or the platform data directory).
|
|
75
|
-
Treat that state as database data; retention and size limits are configurable.
|
|
76
|
-
|
|
77
|
-
See [write safety](docs/usage.md#write-safety),
|
|
78
|
-
[credentials](docs/usage.md#environment-backed-credentials), and
|
|
79
|
-
[database restrictions](docs/databases.md) before using production data.
|
|
80
|
-
|
|
81
43
|
## Documentation
|
|
82
44
|
|
|
83
|
-
|
|
|
45
|
+
| Page | Contents |
|
|
84
46
|
| --- | --- |
|
|
85
|
-
| [
|
|
86
|
-
| [
|
|
87
|
-
| [
|
|
88
|
-
| [
|
|
89
|
-
|
|
90
|
-
|
|
47
|
+
| [Agent guide](docs/agents.md) | The short version for agents: connect, query, reuse, save tokens |
|
|
48
|
+
| [Connections](docs/connections.md) | Targets, environment credentials, profiles |
|
|
49
|
+
| [CLI reference](docs/cli.md) | Commands, parameters, catalog, output modes, deadlines |
|
|
50
|
+
| [Results and state](docs/results.md) | Sessions, actors, limits, caching, local filtering |
|
|
51
|
+
| [Write safety](docs/writes.md) | Approvals, plans, idempotency, transactions |
|
|
52
|
+
| [Batch and pipes](docs/batch.md) | Run many commands in one call |
|
|
53
|
+
| [Database support](docs/databases.md) | Dialects, diagnostics, MongoDB and Redis commands |
|
|
54
|
+
| [TypeScript library](docs/library.md) | API, responses, actors, credential resolution |
|
|
91
55
|
|
|
92
|
-
|
|
56
|
+
Run `stql help` for command syntax and `stql capabilities` for feature details.
|
|
93
57
|
|
|
94
|
-
|
|
95
|
-
npm install @fadhilp/stateql
|
|
96
|
-
```
|
|
58
|
+
## License
|
|
97
59
|
|
|
98
|
-
|
|
99
|
-
[connected, cleanup-safe example](docs/library.md#getting-started).
|
|
60
|
+
[MIT](LICENSE)
|
package/dist/src/adapters.js
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
import { fork } from "node:child_process";
|
|
2
|
-
import {
|
|
3
|
-
import { Client, types as pgTypes } from "pg";
|
|
2
|
+
import { createRequire } from "node:module";
|
|
4
3
|
import { StateQLError } from "./errors.js";
|
|
5
4
|
import { isSqlParameters, parseJson, toJsonSafe } from "./util.js";
|
|
5
|
+
const require = createRequire(import.meta.url);
|
|
6
|
+
let mysqlModule;
|
|
7
|
+
let postgresModule;
|
|
8
|
+
const mysql = () => (mysqlModule ??= require("mysql2"));
|
|
9
|
+
const postgres = () => (postgresModule ??= require("pg"));
|
|
6
10
|
export class AdapterExecutionError extends Error {
|
|
7
11
|
reason;
|
|
8
12
|
outcomeUnknown;
|
|
@@ -237,11 +241,14 @@ class PostgresAdapter {
|
|
|
237
241
|
context;
|
|
238
242
|
confidence = "ttl_based";
|
|
239
243
|
client;
|
|
244
|
+
pgTypes;
|
|
240
245
|
connected = false;
|
|
241
246
|
ending;
|
|
242
247
|
constructor(source, readOnly, context) {
|
|
243
248
|
this.readOnly = readOnly;
|
|
244
249
|
this.context = context;
|
|
250
|
+
const { Client, types } = postgres();
|
|
251
|
+
this.pgTypes = types;
|
|
245
252
|
const timeout = Math.min(2_147_483_647, remainingMilliseconds(context));
|
|
246
253
|
this.client = new Client({
|
|
247
254
|
connectionString: normalizePostgresConnectionString(source),
|
|
@@ -263,7 +270,7 @@ class PostgresAdapter {
|
|
|
263
270
|
rows: toJsonSafe(result.rows),
|
|
264
271
|
columns: result.fields.map((field) => ({
|
|
265
272
|
name: field.name,
|
|
266
|
-
type: pgTypes.getTypeParser(field.dataTypeID).name ||
|
|
273
|
+
type: this.pgTypes.getTypeParser(field.dataTypeID).name ||
|
|
267
274
|
`oid_${field.dataTypeID}`,
|
|
268
275
|
})),
|
|
269
276
|
};
|
|
@@ -884,7 +891,7 @@ class MySqlAdapter {
|
|
|
884
891
|
throwIfStopped(this.context, false);
|
|
885
892
|
if (this.closed)
|
|
886
893
|
throw new Error("MySQL adapter is closed.");
|
|
887
|
-
const rawClient =
|
|
894
|
+
const rawClient = mysql().createConnection({
|
|
888
895
|
uri: this.source,
|
|
889
896
|
connectTimeout: remainingMilliseconds(this.context),
|
|
890
897
|
multipleStatements: false,
|
package/dist/src/cli.js
CHANGED
|
@@ -6,6 +6,13 @@ import { parseArgs } from "node:util";
|
|
|
6
6
|
import { BSON } from "mongodb";
|
|
7
7
|
import { exitCodeFor } from "./errors.js";
|
|
8
8
|
import { StateQL } from "./stateql.js";
|
|
9
|
+
import { isColumns, isRecord } from "./util.js";
|
|
10
|
+
const RESULT_COMMANDS = new Set(["query", "mongo.query", "filter", "show"]);
|
|
11
|
+
const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
|
|
12
|
+
const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
|
|
13
|
+
// The caller already holds the handle it passed to these commands.
|
|
14
|
+
const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
|
|
15
|
+
const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "apply"]);
|
|
9
16
|
const parsed = parseArgs({
|
|
10
17
|
allowPositionals: true,
|
|
11
18
|
strict: true,
|
|
@@ -21,6 +28,7 @@ const parsed = parseArgs({
|
|
|
21
28
|
"params-file": { type: "string" },
|
|
22
29
|
cache: { type: "string" },
|
|
23
30
|
"preview-rows": { type: "string" },
|
|
31
|
+
"max-cell-characters": { type: "string" },
|
|
24
32
|
replay: { type: "boolean" },
|
|
25
33
|
"idempotency-key": { type: "string" },
|
|
26
34
|
"allow-unbounded": { type: "boolean" },
|
|
@@ -51,7 +59,7 @@ if (values.version) {
|
|
|
51
59
|
console.log(packageVersion());
|
|
52
60
|
process.exit(0);
|
|
53
61
|
}
|
|
54
|
-
if (values.help || !command) {
|
|
62
|
+
if (values.help || !command || command === "help") {
|
|
55
63
|
console.log(helpText());
|
|
56
64
|
process.exit(0);
|
|
57
65
|
}
|
|
@@ -71,6 +79,9 @@ const stateql = new StateQL({
|
|
|
71
79
|
...(values["result-ttl-seconds"] === undefined
|
|
72
80
|
? {}
|
|
73
81
|
: { resultTtlSeconds: Number(values["result-ttl-seconds"]) }),
|
|
82
|
+
...(values["max-cell-characters"] === undefined
|
|
83
|
+
? {}
|
|
84
|
+
: { maxCellCharacters: Number(values["max-cell-characters"]) }),
|
|
74
85
|
signal: abortController.signal,
|
|
75
86
|
});
|
|
76
87
|
try {
|
|
@@ -164,6 +175,8 @@ async function dispatch() {
|
|
|
164
175
|
return stateql.disconnect();
|
|
165
176
|
case "status":
|
|
166
177
|
return stateql.status();
|
|
178
|
+
case "actor":
|
|
179
|
+
return dispatchActor(subcommand, rest);
|
|
167
180
|
case "profile":
|
|
168
181
|
return dispatchProfile(subcommand, rest);
|
|
169
182
|
case "session":
|
|
@@ -315,6 +328,16 @@ function parseMongoCommand(value) {
|
|
|
315
328
|
throw new Error("Invalid MongoDB EJSON command.");
|
|
316
329
|
}
|
|
317
330
|
}
|
|
331
|
+
async function dispatchActor(action, args) {
|
|
332
|
+
switch (action) {
|
|
333
|
+
case "show":
|
|
334
|
+
return stateql.showActor();
|
|
335
|
+
case "set-name":
|
|
336
|
+
return stateql.setActorName(requireValue(args.join(" ").trim(), "actor name"));
|
|
337
|
+
default:
|
|
338
|
+
throw new Error(`Unknown actor command "${action ?? ""}".`);
|
|
339
|
+
}
|
|
340
|
+
}
|
|
318
341
|
async function dispatchSession(action, args) {
|
|
319
342
|
switch (action) {
|
|
320
343
|
case "start":
|
|
@@ -522,33 +545,33 @@ function print(result, mode, currentCommand) {
|
|
|
522
545
|
function toAgentResponse(result, currentCommand) {
|
|
523
546
|
if (!result.ok)
|
|
524
547
|
return { ok: false, error: result.error };
|
|
525
|
-
if (!result.data
|
|
526
|
-
typeof result.data !== "object" ||
|
|
527
|
-
Array.isArray(result.data)) {
|
|
548
|
+
if (!isRecord(result.data))
|
|
528
549
|
return { ok: true, data: result.data };
|
|
529
|
-
}
|
|
530
550
|
const data = { ...result.data };
|
|
531
551
|
const handleKey = primaryHandleKey(currentCommand);
|
|
532
|
-
|
|
552
|
+
let handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
|
|
533
553
|
? data[handleKey]
|
|
534
554
|
: undefined;
|
|
535
555
|
if (handle && handleKey)
|
|
536
556
|
delete data[handleKey];
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
557
|
+
const generatedAlias = data.display_alias;
|
|
558
|
+
delete data.display_alias;
|
|
559
|
+
// Generated aliases cannot be reassigned, so they are stable short result handles.
|
|
560
|
+
if (RESULT_COMMANDS.has(currentCommand) && typeof generatedAlias === "string") {
|
|
561
|
+
handle = generatedAlias;
|
|
562
|
+
if (data.alias === generatedAlias)
|
|
563
|
+
delete data.alias;
|
|
564
|
+
}
|
|
565
|
+
const isResult = RESULT_COMMANDS.has(currentCommand) &&
|
|
541
566
|
typeof data.rows === "number" &&
|
|
542
|
-
Array.isArray(data.preview)
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
data.rows =
|
|
547
|
-
data.total = total;
|
|
548
|
-
data.next_offset = truncated ? rows.length : null;
|
|
567
|
+
Array.isArray(data.preview);
|
|
568
|
+
if (isResult) {
|
|
569
|
+
data.total = data.rows;
|
|
570
|
+
data.next_offset = data.truncated ? data.preview.length : null;
|
|
571
|
+
data.rows = data.preview;
|
|
549
572
|
delete data.preview;
|
|
550
573
|
delete data.preview_count;
|
|
551
|
-
delete data.
|
|
574
|
+
delete data.truncated;
|
|
552
575
|
delete data.storage;
|
|
553
576
|
delete data.state_version;
|
|
554
577
|
delete data.duplicate_of;
|
|
@@ -557,11 +580,55 @@ function toAgentResponse(result, currentCommand) {
|
|
|
557
580
|
delete data.offset;
|
|
558
581
|
delete data.limit;
|
|
559
582
|
delete data.returned;
|
|
583
|
+
delete data.truncated;
|
|
560
584
|
}
|
|
561
585
|
else if (currentCommand === "count" && typeof data.rows === "number") {
|
|
562
586
|
data.total = data.rows;
|
|
563
587
|
delete data.rows;
|
|
564
588
|
}
|
|
589
|
+
else if (WRITE_COMMANDS.has(currentCommand)) {
|
|
590
|
+
delete data.actor_id;
|
|
591
|
+
delete data.plan_id;
|
|
592
|
+
delete data.state_version_before;
|
|
593
|
+
if (typeof data.status === "string")
|
|
594
|
+
delete data.committed;
|
|
595
|
+
}
|
|
596
|
+
else if (currentCommand === "history" &&
|
|
597
|
+
Array.isArray(data.history) &&
|
|
598
|
+
data.history.every(isRecord)) {
|
|
599
|
+
Object.assign(data, compactHistory(data.history));
|
|
600
|
+
}
|
|
601
|
+
else if (currentCommand === "inspect" && Array.isArray(data.columns)) {
|
|
602
|
+
data.columns = data.columns.map(withoutFalsePrimaryKey);
|
|
603
|
+
}
|
|
604
|
+
else if (currentCommand === "capabilities" && isRecord(data.features)) {
|
|
605
|
+
const features = data.features;
|
|
606
|
+
data.features = Object.keys(features).filter((key) => features[key] === true);
|
|
607
|
+
}
|
|
608
|
+
else if (currentCommand === "objects" &&
|
|
609
|
+
Array.isArray(data.objects) &&
|
|
610
|
+
data.objects.every(isRecord)) {
|
|
611
|
+
const objects = data.objects.every(hasDerivedIdentity)
|
|
612
|
+
? data.objects.map(withoutIdentity)
|
|
613
|
+
: data.objects;
|
|
614
|
+
const table = columnarRows(objects, undefined);
|
|
615
|
+
delete data.objects;
|
|
616
|
+
Object.assign(data, { columns: table.columns, objects: table.rows });
|
|
617
|
+
}
|
|
618
|
+
else if (currentCommand === "object" &&
|
|
619
|
+
isRecord(data.object) &&
|
|
620
|
+
hasDerivedIdentity(data.object)) {
|
|
621
|
+
data.object = withoutIdentity(data.object);
|
|
622
|
+
}
|
|
623
|
+
if (isResult || (currentCommand === "rows" && Array.isArray(data.rows))) {
|
|
624
|
+
const table = columnarRows(data.rows, data.columns);
|
|
625
|
+
delete data.columns;
|
|
626
|
+
delete data.rows;
|
|
627
|
+
Object.assign(data, table);
|
|
628
|
+
}
|
|
629
|
+
const hasMoreRows = data.next_offset !== null && data.next_offset !== undefined;
|
|
630
|
+
const warnings = result.warnings.filter((warning) => warning.code !== "NON_DETERMINISTIC_PAGINATION" || hasMoreRows);
|
|
631
|
+
dropFalseDefaults(data);
|
|
565
632
|
for (const key of ["ok", "error", "handle", "warnings"]) {
|
|
566
633
|
if (!(key in data))
|
|
567
634
|
continue;
|
|
@@ -570,10 +637,76 @@ function toAgentResponse(result, currentCommand) {
|
|
|
570
637
|
}
|
|
571
638
|
return {
|
|
572
639
|
ok: true,
|
|
573
|
-
...(handle ? { handle } : {}),
|
|
574
|
-
...data,
|
|
575
|
-
...(
|
|
640
|
+
...(handle && !HANDLE_ECHO_COMMANDS.has(currentCommand) ? { handle } : {}),
|
|
641
|
+
...withoutNulls(data),
|
|
642
|
+
...(warnings.length ? { warnings } : {}),
|
|
643
|
+
};
|
|
644
|
+
}
|
|
645
|
+
// Rows with differing keys (e.g. MongoDB documents) stay objects so missing and null remain distinct.
|
|
646
|
+
function columnarRows(rows, columns) {
|
|
647
|
+
const names = isColumns(columns)
|
|
648
|
+
? columns.map((column) => column.name)
|
|
649
|
+
: Object.keys(rows[0] ?? {});
|
|
650
|
+
if (names.length === 0)
|
|
651
|
+
return { rows };
|
|
652
|
+
const nameSet = new Set(names);
|
|
653
|
+
const hasColumnKeys = (row) => {
|
|
654
|
+
if (!isRecord(row))
|
|
655
|
+
return false;
|
|
656
|
+
const keys = Object.keys(row);
|
|
657
|
+
return keys.length === names.length && keys.every((key) => nameSet.has(key));
|
|
576
658
|
};
|
|
659
|
+
if (!rows.every(hasColumnKeys))
|
|
660
|
+
return { rows };
|
|
661
|
+
return {
|
|
662
|
+
columns: names,
|
|
663
|
+
rows: rows.map((row) => names.map((name) => row[name])),
|
|
664
|
+
};
|
|
665
|
+
}
|
|
666
|
+
function compactHistory(entries) {
|
|
667
|
+
const shared = {};
|
|
668
|
+
for (const key of SHARED_HISTORY_KEYS) {
|
|
669
|
+
const value = entries[0]?.[key];
|
|
670
|
+
if (value === undefined)
|
|
671
|
+
continue;
|
|
672
|
+
if (entries.every((entry) => entry[key] === value))
|
|
673
|
+
shared[key] = value;
|
|
674
|
+
}
|
|
675
|
+
const history = entries.map((entry) => {
|
|
676
|
+
const compact = withoutNulls(entry);
|
|
677
|
+
dropFalseDefaults(compact);
|
|
678
|
+
for (const key of Object.keys(shared))
|
|
679
|
+
delete compact[key];
|
|
680
|
+
return compact;
|
|
681
|
+
});
|
|
682
|
+
return { ...shared, history };
|
|
683
|
+
}
|
|
684
|
+
function hasDerivedIdentity(object) {
|
|
685
|
+
const qualifiedName = typeof object.schema === "string"
|
|
686
|
+
? `${object.schema}.${String(object.name)}`
|
|
687
|
+
: object.name;
|
|
688
|
+
return object.identity === undefined || object.identity === qualifiedName;
|
|
689
|
+
}
|
|
690
|
+
function withoutIdentity(object) {
|
|
691
|
+
const compact = { ...object };
|
|
692
|
+
delete compact.identity;
|
|
693
|
+
return compact;
|
|
694
|
+
}
|
|
695
|
+
function withoutFalsePrimaryKey(column) {
|
|
696
|
+
if (!isRecord(column) || column.primary_key !== false)
|
|
697
|
+
return column;
|
|
698
|
+
const compact = { ...column };
|
|
699
|
+
delete compact.primary_key;
|
|
700
|
+
return compact;
|
|
701
|
+
}
|
|
702
|
+
function dropFalseDefaults(record) {
|
|
703
|
+
for (const key of FALSE_DEFAULT_KEYS) {
|
|
704
|
+
if (record[key] === false)
|
|
705
|
+
delete record[key];
|
|
706
|
+
}
|
|
707
|
+
}
|
|
708
|
+
function withoutNulls(record) {
|
|
709
|
+
return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== null));
|
|
577
710
|
}
|
|
578
711
|
function primaryHandleKey(currentCommand) {
|
|
579
712
|
const keys = {
|
|
@@ -645,6 +778,7 @@ Usage: stql <command> [arguments] [options]
|
|
|
645
778
|
Commands:
|
|
646
779
|
connect TARGET | --env ENV | --credential-ref REF | --profile NAME
|
|
647
780
|
disconnect, status
|
|
781
|
+
actor show | set-name NAME
|
|
648
782
|
profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
|
|
649
783
|
profile list|show|remove
|
|
650
784
|
query, filter, exec, show, rows, count, columns, export
|
|
@@ -661,10 +795,13 @@ Commands:
|
|
|
661
795
|
|
|
662
796
|
SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
|
|
663
797
|
Query preview: --preview-rows N (default: 5, maximum: 200).
|
|
798
|
+
Long cells: --max-cell-characters N (default: 200); use export for full values.
|
|
664
799
|
Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
|
|
665
800
|
Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
|
|
666
801
|
State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
|
|
667
802
|
Output: --output agent|json|jsonl|text|silent (default: agent).
|
|
803
|
+
Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
|
|
804
|
+
Agent output omits null fields and false cached/duplicate flags. Guide: docs/agents.md.
|
|
668
805
|
Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
|
|
669
806
|
}
|
|
670
807
|
function packageVersion() {
|
package/dist/src/errors.d.ts
CHANGED
|
@@ -14,4 +14,5 @@ export declare class StateQLError extends Error {
|
|
|
14
14
|
});
|
|
15
15
|
}
|
|
16
16
|
export declare function exitCodeFor(code: string): number;
|
|
17
|
+
export declare function isTransientDatabaseError(error: unknown): boolean;
|
|
17
18
|
export declare function asStateQLError(error: unknown): StateQLError;
|
package/dist/src/errors.js
CHANGED
|
@@ -49,6 +49,46 @@ export function exitCodeFor(code) {
|
|
|
49
49
|
return 9;
|
|
50
50
|
return 1;
|
|
51
51
|
}
|
|
52
|
+
const TRANSIENT_NETWORK_CODES = new Set([
|
|
53
|
+
"ECONNRESET",
|
|
54
|
+
"ECONNREFUSED",
|
|
55
|
+
"ETIMEDOUT",
|
|
56
|
+
"EPIPE",
|
|
57
|
+
"EAI_AGAIN",
|
|
58
|
+
"PROTOCOL_CONNECTION_LOST",
|
|
59
|
+
]);
|
|
60
|
+
// SQLSTATE classes: connection, transaction rollback, resources, operator intervention, system.
|
|
61
|
+
const TRANSIENT_SQLSTATE_CLASSES = new Set(["08", "40", "53", "57", "58"]);
|
|
62
|
+
// MySQL: too many connections, lock wait timeout, deadlock.
|
|
63
|
+
const TRANSIENT_MYSQL_ERRNOS = new Set([1040, 1205, 1213]);
|
|
64
|
+
const TRANSIENT_ERROR_NAMES = new Set([
|
|
65
|
+
"MongoNetworkError",
|
|
66
|
+
"MongoNetworkTimeoutError",
|
|
67
|
+
"MongoServerSelectionError",
|
|
68
|
+
"SocketClosedUnexpectedlyError",
|
|
69
|
+
"ConnectionTimeoutError",
|
|
70
|
+
]);
|
|
71
|
+
const TRANSIENT_SQLITE_MESSAGE = /database (table )?is locked|SQLITE_BUSY/i;
|
|
72
|
+
// Permanent failures such as a missing table must not invite retries; unknown errors are not retryable.
|
|
73
|
+
export function isTransientDatabaseError(error) {
|
|
74
|
+
if (!(error instanceof Error))
|
|
75
|
+
return false;
|
|
76
|
+
const details = error;
|
|
77
|
+
if (typeof details.code === "string" && TRANSIENT_NETWORK_CODES.has(details.code))
|
|
78
|
+
return true;
|
|
79
|
+
if (TRANSIENT_ERROR_NAMES.has(error.name))
|
|
80
|
+
return true;
|
|
81
|
+
if (typeof details.errno === "number" && TRANSIENT_MYSQL_ERRNOS.has(details.errno))
|
|
82
|
+
return true;
|
|
83
|
+
if (Array.isArray(details.errorLabels) && details.errorLabels.includes("TransientTransactionError")) {
|
|
84
|
+
return true;
|
|
85
|
+
}
|
|
86
|
+
const sqlState = typeof details.sqlState === "string" ? details.sqlState : details.code;
|
|
87
|
+
if (typeof sqlState === "string" && /^[0-9A-Z]{5}$/.test(sqlState)) {
|
|
88
|
+
return TRANSIENT_SQLSTATE_CLASSES.has(sqlState.slice(0, 2));
|
|
89
|
+
}
|
|
90
|
+
return TRANSIENT_SQLITE_MESSAGE.test(error.message);
|
|
91
|
+
}
|
|
52
92
|
export function asStateQLError(error) {
|
|
53
93
|
if (error instanceof StateQLError)
|
|
54
94
|
return error;
|
package/dist/src/migrations.js
CHANGED
|
@@ -131,6 +131,26 @@ const MIGRATIONS = [
|
|
|
131
131
|
apply: migratePasswordRefs,
|
|
132
132
|
validate: validatePasswordRefs,
|
|
133
133
|
},
|
|
134
|
+
{
|
|
135
|
+
name: "actor_display_names_v1",
|
|
136
|
+
apply(db) {
|
|
137
|
+
addColumn(db, "session_members", "actor_name", "TEXT");
|
|
138
|
+
addColumn(db, "history", "actor_name", "TEXT");
|
|
139
|
+
db.exec(`
|
|
140
|
+
UPDATE session_members SET actor_name = actor_id WHERE actor_name IS NULL;
|
|
141
|
+
UPDATE history SET actor_name = actor_id WHERE actor_name IS NULL;
|
|
142
|
+
`);
|
|
143
|
+
},
|
|
144
|
+
validate(db) {
|
|
145
|
+
requireColumns(db, "session_members", ["actor_name"]);
|
|
146
|
+
requireColumns(db, "history", ["actor_name"]);
|
|
147
|
+
for (const table of ["session_members", "history"]) {
|
|
148
|
+
const row = db.prepare(`SELECT COUNT(*) AS count FROM ${table} WHERE actor_name IS NULL OR actor_name = ''`).get();
|
|
149
|
+
if (row.count)
|
|
150
|
+
throw new Error(`State migration left ${table}.actor_name empty.`);
|
|
151
|
+
}
|
|
152
|
+
},
|
|
153
|
+
},
|
|
134
154
|
];
|
|
135
155
|
export function runMigrations(db, now) {
|
|
136
156
|
db.exec(`
|
|
@@ -178,6 +198,7 @@ function createInitialSchema(db) {
|
|
|
178
198
|
CREATE TABLE IF NOT EXISTS session_members (
|
|
179
199
|
session_id TEXT NOT NULL,
|
|
180
200
|
actor_id TEXT NOT NULL UNIQUE,
|
|
201
|
+
actor_name TEXT NOT NULL,
|
|
181
202
|
attached_at TEXT NOT NULL,
|
|
182
203
|
PRIMARY KEY(session_id, actor_id),
|
|
183
204
|
FOREIGN KEY(session_id) REFERENCES sessions(id)
|
|
@@ -294,6 +315,7 @@ function createInitialSchema(db) {
|
|
|
294
315
|
timestamp TEXT NOT NULL,
|
|
295
316
|
session_id TEXT NOT NULL,
|
|
296
317
|
actor_id TEXT NOT NULL,
|
|
318
|
+
actor_name TEXT NOT NULL,
|
|
297
319
|
command TEXT NOT NULL,
|
|
298
320
|
origin TEXT NOT NULL DEFAULT 'legacy',
|
|
299
321
|
category TEXT NOT NULL DEFAULT 'management',
|
|
@@ -313,19 +335,22 @@ function migrateSharedSessionActors(db) {
|
|
|
313
335
|
CREATE TABLE IF NOT EXISTS session_members (
|
|
314
336
|
session_id TEXT NOT NULL,
|
|
315
337
|
actor_id TEXT NOT NULL UNIQUE,
|
|
338
|
+
actor_name TEXT,
|
|
316
339
|
attached_at TEXT NOT NULL,
|
|
317
340
|
PRIMARY KEY(session_id, actor_id),
|
|
318
341
|
FOREIGN KEY(session_id) REFERENCES sessions(id)
|
|
319
342
|
)
|
|
320
343
|
`);
|
|
344
|
+
addColumn(db, "session_members", "actor_name", "TEXT");
|
|
321
345
|
addColumn(db, "operations", "actor_id", "TEXT");
|
|
322
346
|
addColumn(db, "transactions", "owner_actor_id", "TEXT");
|
|
323
347
|
addColumn(db, "plans", "owner_actor_id", "TEXT");
|
|
324
348
|
addColumn(db, "plans", "claim_token", "TEXT");
|
|
325
349
|
addColumn(db, "history", "actor_id", "TEXT");
|
|
326
350
|
db.exec(`
|
|
327
|
-
INSERT OR IGNORE INTO session_members(session_id, actor_id, attached_at)
|
|
328
|
-
SELECT id, name, created_at FROM sessions;
|
|
351
|
+
INSERT OR IGNORE INTO session_members(session_id, actor_id, actor_name, attached_at)
|
|
352
|
+
SELECT id, name, name, created_at FROM sessions;
|
|
353
|
+
UPDATE session_members SET actor_name = actor_id WHERE actor_name IS NULL;
|
|
329
354
|
UPDATE operations SET actor_id = (
|
|
330
355
|
SELECT name FROM sessions WHERE sessions.id = operations.session_id
|
|
331
356
|
) WHERE actor_id IS NULL;
|
package/dist/src/mongodb.js
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { createRequire } from "node:module";
|
|
2
|
+
import { BSON } from "bson";
|
|
2
3
|
import { AdapterExecutionError, AdapterWriteError, BatchWriteError, } from "./adapters.js";
|
|
4
|
+
const require = createRequire(import.meta.url);
|
|
5
|
+
let mongodbModule;
|
|
6
|
+
const mongodb = () => (mongodbModule ??= require("mongodb"));
|
|
3
7
|
const MAX_INSPECTION_ITEMS = 1_000;
|
|
4
8
|
const FIND_OPTIONS = new Set([
|
|
5
9
|
"projection",
|
|
@@ -170,7 +174,7 @@ export class MongoAdapter {
|
|
|
170
174
|
this.databaseName = connection.database_name;
|
|
171
175
|
this.readOnly = Boolean(connection.read_only);
|
|
172
176
|
const timeout = remainingMilliseconds(context);
|
|
173
|
-
this.client = new MongoClient(input.source, {
|
|
177
|
+
this.client = new (mongodb().MongoClient)(input.source, {
|
|
174
178
|
connectTimeoutMS: timeout,
|
|
175
179
|
serverSelectionTimeoutMS: timeout,
|
|
176
180
|
waitQueueTimeoutMS: timeout,
|
package/dist/src/redis.js
CHANGED
|
@@ -1,6 +1,9 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { createRequire } from "node:module";
|
|
2
2
|
import { AdapterExecutionError, AdapterWriteError } from "./adapters.js";
|
|
3
3
|
import { hash, toJsonSafe } from "./util.js";
|
|
4
|
+
const require = createRequire(import.meta.url);
|
|
5
|
+
let redisModule;
|
|
6
|
+
const redis = () => (redisModule ??= require("@redis/client"));
|
|
4
7
|
const MAX_ARGUMENTS = 100;
|
|
5
8
|
const MAX_ARGUMENT_BYTES = 256 * 1024;
|
|
6
9
|
const MAX_RESPONSE_BYTES = 1024 * 1024;
|
|
@@ -105,7 +108,7 @@ export class RedisAdapter {
|
|
|
105
108
|
constructor(source, readOnly, context) {
|
|
106
109
|
this.readOnly = readOnly;
|
|
107
110
|
this.context = context;
|
|
108
|
-
this.client = createClient({
|
|
111
|
+
this.client = redis().createClient({
|
|
109
112
|
url: source,
|
|
110
113
|
socket: {
|
|
111
114
|
connectTimeout: remainingMilliseconds(context),
|
|
@@ -183,7 +186,7 @@ export class RedisAdapter {
|
|
|
183
186
|
catch (error) {
|
|
184
187
|
if (error instanceof AdapterWriteError)
|
|
185
188
|
throw error;
|
|
186
|
-
if (error instanceof WatchError)
|
|
189
|
+
if (error instanceof redis().WatchError)
|
|
187
190
|
throw new AdapterWriteError("ROW_CONFLICT: The Redis key changed. Reload before editing.", false);
|
|
188
191
|
if (error instanceof AdapterExecutionError)
|
|
189
192
|
throw error;
|
|
@@ -274,7 +277,7 @@ export class RedisAdapter {
|
|
|
274
277
|
}
|
|
275
278
|
const [type, dump] = await Promise.all([
|
|
276
279
|
this.execute(["TYPE", key], false),
|
|
277
|
-
withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
|
|
280
|
+
withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [redis().RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
|
|
278
281
|
]);
|
|
279
282
|
const encoded = Buffer.isBuffer(dump) ? dump.toString("base64") : dump;
|
|
280
283
|
if (Buffer.byteLength(JSON.stringify(encoded), "utf8") > MAX_RESPONSE_BYTES * 2) {
|