@fadhilp/stateql 0.15.1 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,7 @@ const RESULT_COMMANDS = new Set(["query", "mongo.query", "redis.query", "filter"
3
3
  const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
4
4
  const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
5
5
  // The caller already holds the handle it passed to these commands.
6
- const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
6
+ const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns", "summarize"]);
7
7
  const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "redis.exec", "apply"]);
8
8
  const COMMAND_ALIASES = {
9
9
  "objects.list": "objects",
@@ -55,6 +55,10 @@ export function agentResponse(result, commandName) {
55
55
  data.total = data.rows;
56
56
  delete data.rows;
57
57
  }
58
+ else if (currentCommand === "summarize" && Array.isArray(data.columns)) {
59
+ const table = columnarRows(data.columns, undefined);
60
+ Object.assign(data, { columns: table.columns, rows: table.rows });
61
+ }
58
62
  else if (WRITE_COMMANDS.has(currentCommand)) {
59
63
  delete data.actor_id;
60
64
  delete data.plan_id;
@@ -187,6 +191,7 @@ function primaryHandleKey(currentCommand) {
187
191
  rows: "result_id",
188
192
  count: "result_id",
189
193
  columns: "result_id",
194
+ summarize: "result_id",
190
195
  export: "result_id",
191
196
  alias: "result_id",
192
197
  "alias.set": "result_id",
package/dist/src/cli.js CHANGED
@@ -7,6 +7,42 @@ import { BSON } from "mongodb";
7
7
  import { exitCodeFor } from "./errors.js";
8
8
  import { StateQL } from "./stateql.js";
9
9
  import { agentResponse } from "./agent-response.js";
10
+ import { askPassword, cliCredentialResolver, deleteOsPassword, saveOsPassword } from "./os-credentials.js";
11
+ const USAGE = `stql connect <target> [--name NAME] [--read-only|--read-write]
12
+ stql connect --env ENV | --credential-ref REF | --profile NAME [--name NAME] [--read-only|--read-write]
13
+ stql disconnect|status
14
+ stql actor show | set-name <display-name>
15
+ stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
16
+ [--read-only|--read-write]
17
+ stql profile list|show|remove NAME
18
+ stql session start|list|show|summary|close
19
+ stql query <sql> | --file FILE [--params JSON | --param VALUE... | --params-file FILE]
20
+ [--cache auto|bypass|require] [--preview-rows 0..200]
21
+ stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
22
+ stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY]
23
+ [--replay] [--allow-unbounded] [--allow-destructive]
24
+ stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded]
25
+ [--allow-destructive]
26
+ stql apply <plan-handle>
27
+ stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
28
+ [--replay] [--allow-unbounded] [--allow-destructive]
29
+ stql redis query|exec|plan '<JSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
30
+ [--replay]
31
+ stql show|count|columns|summarize <result-handle>
32
+ stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
33
+ stql alias set <name> <result-handle>
34
+ stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
35
+ stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
36
+ stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
37
+ stql object KIND NAME [IDENTITY] [--schema NAME]
38
+ stql transaction begin|status|commit|rollback [--isolation LEVEL]
39
+ stql history [--limit N] [--offset N] [--category statement|introspection|management]
40
+ [--internal|--external]
41
+ stql receipt <operation-handle>
42
+ stql doctor|capabilities
43
+ stql purge [expired|results|history|all]
44
+ stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
45
+ stql pipe [--continue-on-error]`;
10
46
  const parsed = parseArgs({
11
47
  allowPositionals: true,
12
48
  strict: true,
@@ -15,11 +51,14 @@ const parsed = parseArgs({
15
51
  profile: { type: "string" },
16
52
  env: { type: "string" },
17
53
  "credential-ref": { type: "string" },
54
+ "ask-password": { type: "boolean" },
18
55
  "read-only": { type: "boolean" },
19
56
  "read-write": { type: "boolean" },
20
57
  params: { type: "string" },
21
58
  param: { type: "string", multiple: true },
22
59
  "params-file": { type: "string" },
60
+ file: { type: "string" },
61
+ columns: { type: "string" },
23
62
  cache: { type: "string" },
24
63
  "preview-rows": { type: "string" },
25
64
  "max-cell-characters": { type: "string" },
@@ -54,7 +93,13 @@ if (values.version) {
54
93
  process.exit(0);
55
94
  }
56
95
  if (values.help || !command || command === "help") {
57
- console.log(helpText());
96
+ const topic = command === "help" ? subcommand : command;
97
+ const usage = topic ? commandUsage(topic) : helpText();
98
+ if (usage === undefined) {
99
+ console.error(`Unknown command "${topic}". Run "stql help" to list commands.`);
100
+ process.exit(exitCodeFor("INVALID_COMMAND"));
101
+ }
102
+ console.log(usage);
58
103
  process.exit(0);
59
104
  }
60
105
  const abortController = new AbortController();
@@ -76,6 +121,7 @@ const stateql = new StateQL({
76
121
  ...(values["max-cell-characters"] === undefined
77
122
  ? {}
78
123
  : { maxCellCharacters: Number(values["max-cell-characters"]) }),
124
+ credentialResolver: cliCredentialResolver,
79
125
  signal: abortController.signal,
80
126
  });
81
127
  try {
@@ -144,7 +190,7 @@ async function runBatch() {
144
190
  }
145
191
  async function dispatch() {
146
192
  const params = parseParameters(values.params, values.param, values["params-file"]);
147
- const sql = [subcommand, ...rest].filter(Boolean).join(" ");
193
+ const sql = () => statementText([subcommand, ...rest]);
148
194
  switch (command) {
149
195
  case "connect": {
150
196
  if (values["read-only"] && values["read-write"]) {
@@ -180,7 +226,7 @@ async function dispatch() {
180
226
  case "redis":
181
227
  return dispatchRedis(subcommand, rest);
182
228
  case "query":
183
- return stateql.query(sql, {
229
+ return stateql.query(sql(), {
184
230
  params,
185
231
  cache: cacheMode(values.cache),
186
232
  ...(values["preview-rows"] === undefined
@@ -190,7 +236,7 @@ async function dispatch() {
190
236
  case "filter":
191
237
  return stateql.filter(requireValue(subcommand, "result handle"), requireValue(rest.join(" ").trim(), "filter predicate"), { params });
192
238
  case "exec":
193
- return stateql.exec(sql, {
239
+ return stateql.exec(sql(), {
194
240
  params,
195
241
  replay: values.replay ?? false,
196
242
  ...(values["idempotency-key"]
@@ -205,13 +251,16 @@ async function dispatch() {
205
251
  return stateql.rows(requireValue(subcommand, "result handle"), {
206
252
  offset: numberOption(values.offset, 0),
207
253
  limit: numberOption(values.limit, 20),
254
+ ...(values.columns === undefined ? {} : { columns: columnList(values.columns) }),
208
255
  });
209
256
  case "count":
210
257
  return stateql.count(requireValue(subcommand, "result handle"));
211
258
  case "columns":
212
259
  return stateql.columns(requireValue(subcommand, "result handle"));
260
+ case "summarize":
261
+ return stateql.summarize(requireValue(subcommand, "result handle"));
213
262
  case "export":
214
- return stateql.exportResult(requireValue(subcommand, "result handle"), requireValue(values.output, "--output"), exportFormat(values.format));
263
+ return stateql.exportResult(requireValue(subcommand, "result handle"), requireValue(values.output, "--output"), exportFormat(values.format), values.columns === undefined ? undefined : columnList(values.columns));
215
264
  case "alias":
216
265
  if (subcommand !== "set")
217
266
  throw new Error("Expected: alias set NAME RESULT");
@@ -238,7 +287,7 @@ async function dispatch() {
238
287
  case "transaction":
239
288
  return dispatchTransaction(subcommand, rest[0]);
240
289
  case "plan":
241
- return stateql.plan(sql, {
290
+ return stateql.plan(sql(), {
242
291
  params,
243
292
  allowUnbounded: values["allow-unbounded"] ?? false,
244
293
  ...(values["allow-destructive"]
@@ -268,7 +317,7 @@ async function dispatch() {
268
317
  }
269
318
  }
270
319
  async function dispatchMongo(action, args) {
271
- const payload = requireValue(args.join(" ").trim(), "MongoDB EJSON command");
320
+ const payload = requireValue(statementText(args), "MongoDB EJSON command");
272
321
  switch (action) {
273
322
  case "query":
274
323
  return stateql.mongoQuery(parseMongoCommand(payload), {
@@ -295,7 +344,7 @@ async function dispatchMongo(action, args) {
295
344
  }
296
345
  }
297
346
  async function dispatchRedis(action, args) {
298
- const payload = parseRedisCommand(requireValue(args.join(" ").trim(), "Redis JSON command"));
347
+ const payload = parseRedisCommand(requireValue(statementText(args), "Redis JSON command"));
299
348
  switch (action) {
300
349
  case "query": return stateql.redisQuery(payload, { cache: cacheMode(values.cache) });
301
350
  case "exec": return stateql.redisExec(payload, { replay: values.replay ?? false, ...(values["idempotency-key"] ? { idempotencyKey: values["idempotency-key"] } : {}) });
@@ -350,30 +399,62 @@ async function dispatchSession(action, args) {
350
399
  }
351
400
  async function dispatchProfile(action, args) {
352
401
  switch (action) {
353
- case "add":
402
+ case "add": {
354
403
  if (values["read-only"] && values["read-write"]) {
355
404
  throw new Error("--read-only and --read-write are mutually exclusive.");
356
405
  }
357
- return stateql.addProfile(requireValue(args[0], "profile name"), args[1], {
406
+ const name = requireValue(args[0], "profile name");
407
+ const passwordRef = values["ask-password"]
408
+ ? await saveOsPassword(await askPassword(name, requireValue(args[1], "TARGET for --ask-password")))
409
+ : undefined;
410
+ const added = await stateql.addProfile(name, args[1], {
358
411
  ...(values.env ? { secretEnv: values.env } : {}),
359
412
  ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
413
+ ...(passwordRef ? { passwordRef } : {}),
360
414
  readOnly: !values["read-write"],
361
415
  });
362
- case "update":
416
+ if (!added.ok)
417
+ await deleteOsPassword(passwordRef);
418
+ return added;
419
+ }
420
+ case "update": {
363
421
  if (values["read-only"] && values["read-write"])
364
422
  throw new Error("--read-only and --read-write are mutually exclusive.");
365
- return stateql.updateProfile(requireValue(args[0], "profile name"), {
423
+ const name = requireValue(args[0], "profile name");
424
+ const before = await stateql.showProfile(name);
425
+ if (!before.ok)
426
+ return before;
427
+ const target = args[1] ?? before.data.target;
428
+ const passwordRef = values["ask-password"]
429
+ ? await saveOsPassword(await askPassword(name, requireValue(target ?? undefined, "TARGET for --ask-password")))
430
+ : undefined;
431
+ const updated = await stateql.updateProfile(name, {
366
432
  ...(args[1] !== undefined ? { target: args[1] } : {}),
367
433
  ...(values.env ? { secretEnv: values.env } : {}),
368
434
  ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
435
+ ...(passwordRef ? { passwordRef } : {}),
369
436
  ...(values["read-only"] ? { readOnly: true } : values["read-write"] ? { readOnly: false } : {}),
370
437
  });
438
+ if (!updated.ok) {
439
+ await deleteOsPassword(passwordRef);
440
+ return updated;
441
+ }
442
+ if (updated.data.password_ref !== before.data.password_ref)
443
+ await deleteOsPassword(before.data.password_ref);
444
+ return updated;
445
+ }
371
446
  case "list":
372
447
  return stateql.listProfiles();
373
448
  case "show":
374
449
  return stateql.showProfile(requireValue(args[0], "profile name"));
375
- case "remove":
376
- return stateql.removeProfile(requireValue(args[0], "profile name"));
450
+ case "remove": {
451
+ const name = requireValue(args[0], "profile name");
452
+ const before = await stateql.showProfile(name);
453
+ const removed = await stateql.removeProfile(name);
454
+ if (removed.ok && before.ok)
455
+ await deleteOsPassword(before.data.password_ref);
456
+ return removed;
457
+ }
377
458
  default:
378
459
  throw new Error(`Unknown profile command "${action ?? ""}".`);
379
460
  }
@@ -418,6 +499,21 @@ function parseParameters(value, values, file) {
418
499
  }
419
500
  return parsedValue;
420
501
  }
502
+ function statementText(args) {
503
+ const inline = args.filter(Boolean).join(" ").trim();
504
+ const file = values.file;
505
+ if (file === undefined)
506
+ return inline;
507
+ if (inline)
508
+ throw new Error("Use either inline text or --file, not both.");
509
+ if (file === "-" && values["params-file"] === "-") {
510
+ throw new Error("--file and --params-file cannot both read standard input.");
511
+ }
512
+ return withoutBom(readFileSync(file === "-" ? 0 : resolve(file), "utf8")).trim();
513
+ }
514
+ function columnList(value) {
515
+ return value.split(",").map((name) => name.trim()).filter(Boolean);
516
+ }
421
517
  function parseParameter(value) {
422
518
  try {
423
519
  return JSON.parse(value);
@@ -571,34 +667,25 @@ function extractHandle(data) {
571
667
  }
572
668
  return undefined;
573
669
  }
670
+ function commandUsage(name) {
671
+ const entries = USAGE.split(/\n(?=stql )/).filter((entry) => entry.slice("stql ".length).split(" ")[0].split("|").includes(name));
672
+ return entries.length > 0 ? entries.join("\n") : undefined;
673
+ }
574
674
  function helpText() {
575
675
  return `StateQL ${packageVersion()}
576
676
 
577
677
  Usage: stql <command> [arguments] [options]
578
678
 
579
- Commands:
580
- connect TARGET | --env ENV | --credential-ref REF | --profile NAME
581
- disconnect, status
582
- actor show | set-name NAME
583
- profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
584
- profile list|show|remove
585
- query, filter, exec, show, rows, count, columns, export
586
- mongo query|exec|plan '<EJSON command>'
587
- redis query|exec|plan '<JSON command>'
588
- alias set
589
- inspect schema|table|collection|collections|columns|indexes|constraints
590
- objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR]
591
- object KIND NAME [IDENTITY] [--schema NAME]
592
- transaction begin|status|commit|rollback
593
- plan, apply, history [--category CATEGORY] [--internal|--external], receipt, doctor, purge, capabilities
594
- batch [file.json|file.jsonl|-]
595
- pipe
679
+ Commands (stql help COMMAND shows one):
680
+ ${USAGE}
596
681
 
597
682
  SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
683
+ Long SQL or native commands: --file FILE (- reads standard input) instead of inline text.
598
684
  Query preview: --preview-rows N (default: 5, maximum: 200).
599
685
  Long cells: --max-cell-characters N (default: 200); use export for full values.
600
686
  Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
601
- Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
687
+ Saved passwords: --ask-password opens a dialog and keeps the password in the OS credential store.
688
+ Other credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
602
689
  State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
603
690
  Output: --output agent|json|jsonl|text|silent (default: agent).
604
691
  Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
@@ -3,4 +3,4 @@ export { agentResponse } from "./agent-response.js";
3
3
  export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
4
4
  export type { CredentialResolutionFailure } from "./errors.js";
5
5
  export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
6
- export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
6
+ export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, ColumnSummary, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, SummaryData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
@@ -0,0 +1,6 @@
1
+ import type { CredentialRequest } from "./types.js";
2
+ export declare function isOsPasswordRef(reference: string | null | undefined): reference is string;
3
+ export declare function cliCredentialResolver(request: CredentialRequest): Promise<string | undefined>;
4
+ export declare function saveOsPassword(password: string): Promise<string>;
5
+ export declare function deleteOsPassword(reference: string | null | undefined): Promise<void>;
6
+ export declare function askPassword(profile: string, target: string): Promise<string>;
@@ -0,0 +1,96 @@
1
+ import { execFile } from "node:child_process";
2
+ import { randomUUID } from "node:crypto";
3
+ import { env, platform } from "node:process";
4
+ import { promisify } from "node:util";
5
+ const SERVICE = "stql";
6
+ const PREFIX = "os:";
7
+ const run = promisify(execFile);
8
+ export function isOsPasswordRef(reference) {
9
+ return reference?.startsWith(PREFIX) ?? false;
10
+ }
11
+ export async function cliCredentialResolver(request) {
12
+ if (request.source === "credential_ref")
13
+ return undefined;
14
+ if (request.source !== "password_ref")
15
+ return env[request.reference];
16
+ if (!isOsPasswordRef(request.reference))
17
+ return undefined;
18
+ return (await osEntry(request.reference)).getPassword() ?? undefined;
19
+ }
20
+ export async function saveOsPassword(password) {
21
+ const reference = `${PREFIX}${randomUUID()}`;
22
+ (await osEntry(reference)).setPassword(password);
23
+ return reference;
24
+ }
25
+ export async function deleteOsPassword(reference) {
26
+ if (!isOsPasswordRef(reference))
27
+ return;
28
+ (await osEntry(reference)).deletePassword();
29
+ }
30
+ async function osEntry(reference) {
31
+ const { Entry } = await import("@napi-rs/keyring");
32
+ return new Entry(SERVICE, reference.slice(PREFIX.length));
33
+ }
34
+ export async function askPassword(profile, target) {
35
+ const url = new URL(target);
36
+ const user = decodeURIComponent(url.username);
37
+ const message = `Password for ${user ? `${user}@` : ""}${url.host} (StateQL profile "${profile}")`;
38
+ let output;
39
+ try {
40
+ output = await passwordDialog(message);
41
+ }
42
+ catch (error) {
43
+ if (isMissingCommand(error)) {
44
+ throw new Error("--ask-password needs a password dialog: zenity on Linux, osascript on macOS.");
45
+ }
46
+ throw new Error("Password entry was cancelled.");
47
+ }
48
+ const password = platform === "win32" ? output : output.replace(/\r?\n$/, "");
49
+ if (password === "")
50
+ throw new Error("No password was entered.");
51
+ return password;
52
+ }
53
+ async function passwordDialog(message) {
54
+ if (platform === "win32") {
55
+ // Get-Credential opens behind the active window; a TopMost form stays visible.
56
+ // windowsHide makes the first ShowWindow hide the form, so show it again explicitly.
57
+ const script = [
58
+ "$ErrorActionPreference = 'Stop'",
59
+ "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false",
60
+ "Add-Type -AssemblyName System.Windows.Forms",
61
+ "Add-Type -Namespace StateQL -Name Win32 -MemberDefinition '[DllImport(\"user32.dll\")] public static extern bool ShowWindow(IntPtr window, int command);'",
62
+ "[Windows.Forms.Application]::EnableVisualStyles()",
63
+ "$form = New-Object Windows.Forms.Form -Property @{ Text = 'StateQL'; TopMost = $true; StartPosition = 'CenterScreen'; FormBorderStyle = 'FixedDialog'; MaximizeBox = $false; MinimizeBox = $false; AutoSize = $true; AutoSizeMode = 'GrowAndShrink'; Padding = 12 }",
64
+ "$layout = New-Object Windows.Forms.FlowLayoutPanel -Property @{ FlowDirection = 'TopDown'; AutoSize = $true }",
65
+ "$label = New-Object Windows.Forms.Label -Property @{ Text = $env:STQL_PROMPT_MESSAGE; AutoSize = $true; MaximumSize = '360,0' }",
66
+ "$box = New-Object Windows.Forms.TextBox -Property @{ UseSystemPasswordChar = $true; Width = 360 }",
67
+ "$buttons = New-Object Windows.Forms.FlowLayoutPanel -Property @{ FlowDirection = 'RightToLeft'; Width = 366; Height = 34 }",
68
+ "$cancel = New-Object Windows.Forms.Button -Property @{ Text = 'Cancel'; DialogResult = 'Cancel' }",
69
+ "$ok = New-Object Windows.Forms.Button -Property @{ Text = 'OK'; DialogResult = 'OK' }",
70
+ "$buttons.Controls.AddRange(@($cancel, $ok))",
71
+ "$layout.Controls.AddRange(@($label, $box, $buttons))",
72
+ "$form.Controls.Add($layout)",
73
+ "$form.AcceptButton = $ok",
74
+ "$form.CancelButton = $cancel",
75
+ "$form.Add_Shown({ [void][StateQL.Win32]::ShowWindow($form.Handle, 5); $form.Activate(); [void]$box.Focus() })",
76
+ "if ($form.ShowDialog() -ne 'OK') { exit 1 }",
77
+ "[Console]::Out.Write($box.Text)",
78
+ ].join("\n");
79
+ const { stdout } = await run("powershell.exe", ["-NoProfile", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], { env: { ...env, STQL_PROMPT_MESSAGE: message }, windowsHide: true });
80
+ return stdout;
81
+ }
82
+ if (platform === "darwin") {
83
+ const { stdout } = await run("osascript", [
84
+ "-e", "on run argv",
85
+ "-e", 'text returned of (display dialog (item 1 of argv) default answer "" with hidden answer with title "StateQL")',
86
+ "-e", "end run",
87
+ message,
88
+ ]);
89
+ return stdout;
90
+ }
91
+ const { stdout } = await run("zenity", ["--password", "--title", message]);
92
+ return stdout;
93
+ }
94
+ function isMissingCommand(error) {
95
+ return error.code === "ENOENT";
96
+ }
package/dist/src/sql.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { AST } from "node-sql-parser";
2
- import type { Driver, SqlDriver } from "./types.js";
2
+ import type { Driver, SqlDriver, SqlParameters } from "./types.js";
3
3
  export type StatementType = "select" | "insert" | "upsert" | "replace" | "update" | "delete" | "create" | "alter" | "drop" | "truncate" | "values" | "show" | "explain" | "vacuum" | "analyze" | "reindex" | "optimize" | "check" | "cluster";
4
4
  export interface SqlAnalysis {
5
5
  ast: AST;
@@ -18,3 +18,9 @@ export interface SqlAnalysis {
18
18
  export declare function analyzeSql(sql: string, driver: SqlDriver): SqlAnalysis;
19
19
  /** @internal Compatibility for existing connection records during Mongo rollout. */
20
20
  export declare function analyzeSql(sql: string, driver: Driver): SqlAnalysis;
21
+ export interface CountStatement {
22
+ sql: string;
23
+ params: unknown[];
24
+ }
25
+ /** A COUNT(*) of the rows a single-table UPDATE or DELETE matches, or undefined when it cannot be derived safely. */
26
+ export declare function matchedRowsCount(analysis: SqlAnalysis, params: SqlParameters, driver: SqlDriver): CountStatement | undefined;
package/dist/src/sql.js CHANGED
@@ -50,13 +50,93 @@ export function analyzeSql(sql, driver) {
50
50
  throw new StateQLError("INVALID_SQL", message);
51
51
  }
52
52
  }
53
+ function parserDatabase(driver) {
54
+ if (driver === "postgres")
55
+ return "Postgresql";
56
+ if (driver === "mysql")
57
+ return "MySQL";
58
+ return "Sqlite";
59
+ }
60
+ /** A COUNT(*) of the rows a single-table UPDATE or DELETE matches, or undefined when it cannot be derived safely. */
61
+ export function matchedRowsCount(analysis, params, driver) {
62
+ const ast = analysis.ast;
63
+ const isUpdate = analysis.statementType === "update";
64
+ const isDelete = analysis.statementType === "delete";
65
+ if (!isUpdate && !isDelete)
66
+ return undefined;
67
+ const tables = isUpdate ? ast.table : ast.from;
68
+ const singleTable = Array.isArray(tables) && tables.length === 1 && !record(tables[0])?.join;
69
+ const limit = record(ast.limit)?.value;
70
+ const hasLimit = Array.isArray(limit) && limit.length > 0;
71
+ if (!Array.isArray(params) || !singleTable)
72
+ return undefined;
73
+ if (ast.with || ast.orderby || hasLimit || (isUpdate && ast.from))
74
+ return undefined;
75
+ // The parser drops NULLS FIRST/LAST, which can change a subquery that also has a LIMIT.
76
+ if (/\bnulls\s+(?:first|last)\b/i.test(analysis.normalized))
77
+ return undefined;
78
+ const where = structuredClone(ast.where ?? null);
79
+ const setPlaceholders = placeholders(ast.set);
80
+ const wherePlaceholders = placeholders(where);
81
+ const placeholderCount = setPlaceholders.length + wherePlaceholders.length;
82
+ if (placeholders(ast).length !== placeholderCount)
83
+ return undefined;
84
+ let countParams;
85
+ if ([...setPlaceholders, ...wherePlaceholders].every(isQuestionMark)) {
86
+ if (params.length !== placeholderCount)
87
+ return undefined;
88
+ countParams = params.slice(setPlaceholders.length);
89
+ }
90
+ else if (driver === "postgres" && wherePlaceholders.every(isNumberedVar)) {
91
+ const renumbered = new Map();
92
+ for (const node of wherePlaceholders) {
93
+ const number = node.name;
94
+ if (!renumbered.has(number))
95
+ renumbered.set(number, renumbered.size + 1);
96
+ node.name = renumbered.get(number);
97
+ }
98
+ countParams = [...renumbered.keys()].map((number) => params[number - 1]);
99
+ }
100
+ else {
101
+ return undefined;
102
+ }
103
+ const select = {
104
+ type: "select",
105
+ columns: [{ expr: { type: "aggr_func", name: "COUNT", args: { expr: { type: "star", value: "*" } } }, as: null }],
106
+ from: tables,
107
+ where,
108
+ };
109
+ return {
110
+ sql: sqlParser().sqlify(select, { database: parserDatabase(driver) }),
111
+ params: countParams,
112
+ };
113
+ }
114
+ function placeholders(node, found = []) {
115
+ if (Array.isArray(node)) {
116
+ for (const item of node)
117
+ placeholders(item, found);
118
+ return found;
119
+ }
120
+ const value = record(node);
121
+ if (!value)
122
+ return found;
123
+ if (value.type === "var" || isQuestionMark(value)) {
124
+ found.push(value);
125
+ return found;
126
+ }
127
+ for (const child of Object.values(value))
128
+ placeholders(child, found);
129
+ return found;
130
+ }
131
+ function isQuestionMark(node) {
132
+ return node.type === "origin" && node.value === "?";
133
+ }
134
+ function isNumberedVar(node) {
135
+ return node.type === "var" && node.prefix === "$" && Number.isInteger(node.name);
136
+ }
53
137
  function parseSqlStatement(sql, driver) {
54
138
  const parser = sqlParser();
55
- const database = driver === "postgres"
56
- ? "Postgresql"
57
- : driver === "mysql"
58
- ? "MySQL"
59
- : "Sqlite";
139
+ const database = parserDatabase(driver);
60
140
  const parserSql = driver === "postgres" ? postgresParserSql(sql) : sql;
61
141
  let parsed;
62
142
  try {
@@ -699,10 +779,10 @@ class UtilityParser {
699
779
  if (this.done())
700
780
  return;
701
781
  while (true) {
702
- if (allowOnlyAndStar)
703
- this.consumeWord("ONLY");
782
+ const only = allowOnlyAndStar && this.consumeWord("ONLY");
704
783
  this.qualifiedIdentifier();
705
- if (allowOnlyAndStar)
784
+ // PostgreSQL accepts ONLY name or name *, never both.
785
+ if (allowOnlyAndStar && !only)
706
786
  this.consumePunctuation("*");
707
787
  if (this.consumePunctuation("(")) {
708
788
  this.identifier();
@@ -1,5 +1,5 @@
1
1
  import { type TableChange } from "./table-editor.js";
2
- import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
2
+ import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, SummaryData, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
3
3
  export declare class StateQL {
4
4
  /** Runtime contract marker for passwordRef/password_ref support. */
5
5
  static readonly passwordReferenceVersion: 1;
@@ -56,6 +56,7 @@ export declare class StateQL {
56
56
  rows(idOrAlias: string, options?: RowsOptions): Promise<Response<RowsData>>;
57
57
  count(idOrAlias: string): Promise<Response<CountData>>;
58
58
  columns(idOrAlias: string): Promise<Response<ColumnsData>>;
59
+ summarize(idOrAlias: string): Promise<Response<SummaryData>>;
59
60
  setAlias(name: string, id: string): Promise<Response<AliasData>>;
60
61
  /** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
61
62
  readMaterialized(id: string, options?: RowsOptions & {
@@ -97,7 +98,7 @@ export declare class StateQL {
97
98
  private editableMetadata;
98
99
  private panelResult;
99
100
  private fullResultRows;
100
- exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv"): Promise<Response<ExportData>>;
101
+ exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv", columns?: string[]): Promise<Response<ExportData>>;
101
102
  exec(sql: string, options?: ExecOptions): Promise<Response<ExecData>>;
102
103
  mongoExec(command: MongoWriteCommand, options?: MongoExecOptions): Promise<Response<ExecData>>;
103
104
  redisExec(command: RedisCommand, options?: RedisExecOptions): Promise<Response<ExecData>>;
@@ -11,9 +11,9 @@ import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCo
11
11
  import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
12
12
  import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
13
13
  import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData, transactionData, } from "./response-data.js";
14
- import { analyzeSql } from "./sql.js";
14
+ import { analyzeSql, matchedRowsCount } from "./sql.js";
15
15
  import { StateStore, } from "./store.js";
16
- import { compactRows, defaultHome, hash, isSqlParameters, parseJson, redact, } from "./util.js";
16
+ import { compactRows, compactValue, defaultHome, hash, isSqlParameters, parseJson, redact, } from "./util.js";
17
17
  const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
18
18
  const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
19
19
  const DEFAULT_CREDENTIAL_RESOLUTION_TIMEOUT_MS = 120_000;
@@ -1019,7 +1019,7 @@ export class StateQL {
1019
1019
  throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "limit cannot exceed 1000 rows.", { suggestedAction: "Fetch another page or use export." });
1020
1020
  }
1021
1021
  const allRows = this.store.resultRows(result);
1022
- const rows = allRows.slice(offset, offset + limit);
1022
+ const rows = selectColumns(allRows.slice(offset, offset + limit), this.store.resultColumns(result), options.columns);
1023
1023
  return {
1024
1024
  data: {
1025
1025
  result_id: result.id,
@@ -1059,6 +1059,22 @@ export class StateQL {
1059
1059
  confidence: result.state_confidence,
1060
1060
  }));
1061
1061
  }
1062
+ async summarize(idOrAlias) {
1063
+ return this.withResult("summarize", idOrAlias, async (result) => {
1064
+ const rows = this.store.resultRows(result);
1065
+ return {
1066
+ data: {
1067
+ result_id: result.id,
1068
+ total: result.row_count,
1069
+ columns: this.store.resultColumns(result).map((column) => summarizeColumn(column.name, rows, this.maxCellCharacters)),
1070
+ },
1071
+ handle: result.id,
1072
+ cached: true,
1073
+ stateVersion: result.state_version,
1074
+ confidence: result.state_confidence,
1075
+ };
1076
+ });
1077
+ }
1062
1078
  async setAlias(name, id) {
1063
1079
  return this.run("alias.set", async (session) => {
1064
1080
  const result = this.requireResult(id, session);
@@ -1321,14 +1337,15 @@ export class StateQL {
1321
1337
  this.panelRows = { id: result.id, json: result.rows_json, rows: this.store.resultRows(result) };
1322
1338
  return this.panelRows.rows;
1323
1339
  }
1324
- async exportResult(idOrAlias, output, format = "csv") {
1340
+ async exportResult(idOrAlias, output, format = "csv", columns) {
1325
1341
  return this.withResult("export", idOrAlias, async (result) => {
1326
- const rows = this.store.resultRows(result);
1342
+ const resultColumns = this.store.resultColumns(result);
1343
+ const rows = selectColumns(this.store.resultRows(result), resultColumns, columns);
1327
1344
  const content = format === "json"
1328
1345
  ? `${JSON.stringify(rows, null, 2)}\n`
1329
1346
  : format === "jsonl"
1330
1347
  ? `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`
1331
- : rowsToCsv(rows, this.store.resultColumns(result).map((column) => column.name));
1348
+ : rowsToCsv(rows, columns ?? resultColumns.map((column) => column.name));
1332
1349
  writeFileSync(resolve(output), content, "utf8");
1333
1350
  return {
1334
1351
  data: {
@@ -1648,6 +1665,7 @@ export class StateQL {
1648
1665
  const adapter = await this.openAdapter(connection, context, adapterSource);
1649
1666
  try {
1650
1667
  const stateSignature = await adapter.signature();
1668
+ const estimatedRows = await countMatchedRows(adapter, matchedRowsCount(analysis, options.params ?? [], connection.driver));
1651
1669
  const expiresAt = new Date(this.now().getTime() + 10 * 60_000).toISOString();
1652
1670
  const plan = this.store.savePlan({
1653
1671
  sessionId: session.id,
@@ -1681,6 +1699,7 @@ export class StateQL {
1681
1699
  state_version: plan.state_version,
1682
1700
  owner_actor_id: plan.owner_actor_id,
1683
1701
  expires_at: plan.expires_at,
1702
+ ...(estimatedRows === undefined ? {} : { estimated_rows: estimatedRows }),
1684
1703
  },
1685
1704
  handle: plan.id,
1686
1705
  executed: true,
@@ -1985,6 +2004,9 @@ export class StateQL {
1985
2004
  multi_row_table_plans: true,
1986
2005
  history_classification: true,
1987
2006
  actor_display_names: true,
2007
+ result_projection: true,
2008
+ result_summary: true,
2009
+ plan_row_estimates: true,
1988
2010
  },
1989
2011
  driver_features: {
1990
2012
  mongodb: {
@@ -2155,11 +2177,14 @@ export class StateQL {
2155
2177
  return this.rows(batchString(command.handle, "handle"), {
2156
2178
  offset: command.offset ?? 0,
2157
2179
  limit: command.limit ?? 20,
2180
+ ...(command.columns ? { columns: command.columns } : {}),
2158
2181
  });
2159
2182
  case "count":
2160
2183
  return this.count(batchString(command.handle, "handle"));
2161
2184
  case "columns":
2162
2185
  return this.columns(batchString(command.handle, "handle"));
2186
+ case "summarize":
2187
+ return this.summarize(batchString(command.handle, "handle"));
2163
2188
  case "alias.set":
2164
2189
  return this.setAlias(batchString(command.name, "name"), batchString(command.handle, "handle"));
2165
2190
  case "inspect":
@@ -3372,6 +3397,67 @@ function positiveInteger(value, name) {
3372
3397
  return value;
3373
3398
  throw new StateQLError("INVALID_COMMAND", `${name} must be a positive integer.`);
3374
3399
  }
3400
+ function selectColumns(rows, available, selected) {
3401
+ if (!selected)
3402
+ return rows;
3403
+ const names = available.map((column) => column.name);
3404
+ const unknown = selected.filter((name) => !names.includes(name));
3405
+ if (selected.length === 0 || unknown.length > 0) {
3406
+ throw new StateQLError("INVALID_COMMAND", unknown.length > 0 ? `Unknown column: ${unknown.join(", ")}.` : "columns cannot be empty.", { suggestedAction: `Use one or more of: ${names.join(", ")}.` });
3407
+ }
3408
+ // Keep missing keys missing, so MongoDB documents still distinguish missing from null.
3409
+ return rows.map((row) => Object.fromEntries(selected.filter((name) => name in row).map((name) => [name, row[name]])));
3410
+ }
3411
+ function summarizeColumn(name, rows, maxCellCharacters) {
3412
+ const values = rows
3413
+ .map((row) => row[name])
3414
+ .filter((value) => value !== null && value !== undefined);
3415
+ const [min, max] = valueRange(values);
3416
+ return {
3417
+ name,
3418
+ nulls: rows.length - values.length,
3419
+ distinct: new Set(values.map((value) => JSON.stringify(value))).size,
3420
+ min: compactValue(min, maxCellCharacters),
3421
+ max: compactValue(max, maxCellCharacters),
3422
+ };
3423
+ }
3424
+ const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
3425
+ // Exact numerics (PostgreSQL numeric/bigint, MySQL DECIMAL) arrive as strings, so compare them as numbers.
3426
+ function valueRange(values) {
3427
+ const numeric = values.every((value) => typeof value === "number" || (typeof value === "string" && NUMERIC_TEXT.test(value)));
3428
+ const text = values.every((value) => typeof value === "string");
3429
+ if (values.length === 0)
3430
+ return [null, null];
3431
+ if (!numeric && !text)
3432
+ return [null, null];
3433
+ const compare = numeric
3434
+ ? (left, right) => Number(left) - Number(right)
3435
+ : (left, right) => (String(left) < String(right) ? -1 : String(left) > String(right) ? 1 : 0);
3436
+ let min = values[0];
3437
+ let max = values[0];
3438
+ for (const value of values) {
3439
+ if (compare(value, min) < 0)
3440
+ min = value;
3441
+ if (compare(value, max) > 0)
3442
+ max = value;
3443
+ }
3444
+ return [min, max];
3445
+ }
3446
+ async function countMatchedRows(adapter, count) {
3447
+ if (!count)
3448
+ return undefined;
3449
+ try {
3450
+ const { rows } = await adapter.read(count.sql, count.params);
3451
+ const value = Number(Object.values(rows[0] ?? {})[0]);
3452
+ return Number.isSafeInteger(value) ? value : undefined;
3453
+ }
3454
+ catch (error) {
3455
+ if (error instanceof AdapterExecutionError)
3456
+ throw error;
3457
+ // The estimate is advisory; a count the parser cannot express must not block the plan.
3458
+ return undefined;
3459
+ }
3460
+ }
3375
3461
  async function closeAdapterQuietly(adapter) {
3376
3462
  try {
3377
3463
  await adapter.close();
@@ -337,6 +337,7 @@ export interface RedisPlanOptions extends ExecutionOptions {
337
337
  export interface RowsOptions {
338
338
  offset?: number;
339
339
  limit?: number;
340
+ columns?: string[];
340
341
  }
341
342
  export interface PlanOptions extends ExecutionOptions {
342
343
  params?: SqlParameters;
@@ -347,7 +348,7 @@ export interface MongoPlanOptions extends ExecutionOptions {
347
348
  allowUnbounded?: boolean;
348
349
  allowDestructive?: boolean;
349
350
  }
350
- export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
351
+ export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "summarize" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
351
352
  export interface BatchCommand {
352
353
  command: BatchCommandName;
353
354
  target?: string;
@@ -364,6 +365,7 @@ export interface BatchCommand {
364
365
  object?: CatalogObject;
365
366
  cache?: "auto" | "bypass" | "require";
366
367
  preview_rows?: number;
368
+ columns?: string[];
367
369
  read_only?: boolean;
368
370
  secret_env?: string;
369
371
  credential_ref?: string;
@@ -542,6 +544,18 @@ export interface ColumnsData {
542
544
  result_id: string;
543
545
  columns: Column[];
544
546
  }
547
+ export interface ColumnSummary {
548
+ name: string;
549
+ nulls: number;
550
+ distinct: number;
551
+ min: unknown;
552
+ max: unknown;
553
+ }
554
+ export interface SummaryData {
555
+ result_id: string;
556
+ total: number;
557
+ columns: ColumnSummary[];
558
+ }
545
559
  export interface AliasData {
546
560
  alias: string;
547
561
  result_id: string;
@@ -603,6 +617,8 @@ export interface PlanData {
603
617
  state_version: string;
604
618
  owner_actor_id: string;
605
619
  expires_at: string;
620
+ /** Rows a single-table UPDATE or DELETE matched at plan time; absent when not derivable. */
621
+ estimated_rows?: number;
606
622
  }
607
623
  export interface ApplyData extends ExecData {
608
624
  plan_id: string;
@@ -9,4 +9,5 @@ export declare function isColumns(value: unknown): value is Column[];
9
9
  export declare function isRecord(value: unknown): value is Record<string, unknown>;
10
10
  export declare function redact(value: string): string;
11
11
  export declare function compactRows(rows: Row[], maxCellCharacters: number): Row[];
12
+ export declare function compactValue(value: unknown, max: number): unknown;
12
13
  export declare function toJsonSafe<T>(value: T): T;
package/dist/src/util.js CHANGED
@@ -78,7 +78,7 @@ export function compactRows(rows, maxCellCharacters) {
78
78
  compactValue(value, maxCellCharacters),
79
79
  ])));
80
80
  }
81
- function compactValue(value, max) {
81
+ export function compactValue(value, max) {
82
82
  if (typeof value === "bigint")
83
83
  return value.toString();
84
84
  if (Buffer.isBuffer(value)) {
package/docs/batch.md CHANGED
@@ -42,7 +42,8 @@ stql batch commands.json
42
42
  Batch fields use snake case. Supported command names match CLI paths, such as
43
43
  `actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
44
44
  `alias.set`, `plan`, and `apply`. `actor.set-name` takes the display name in the
45
- `name` field. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
45
+ `name` field. Query commands may set `preview_rows` from 0 to 200. `rows` may
46
+ set `columns` to an array of column names; `summarize` takes `handle`. Native MongoDB
46
47
  batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
47
48
  in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
48
49
  apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
package/docs/cli.md CHANGED
@@ -11,29 +11,29 @@ stql disconnect
11
11
  stql status
12
12
  stql actor show
13
13
  stql actor set-name <display-name>
14
- stql profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
14
+ stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
15
15
  [--read-only|--read-write]
16
16
  stql profile list|show|remove
17
17
  stql session start|list|show|summary|close
18
- stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
18
+ stql query <sql> | --file FILE [--params JSON | --param VALUE...] [--cache auto|bypass|require]
19
19
  [--preview-rows 0..200]
20
20
  stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
21
- stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
21
+ stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
22
22
  [--allow-unbounded] [--allow-destructive]
23
- stql mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
23
+ stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
24
24
  [--replay] [--allow-unbounded] [--allow-destructive]
25
25
  stql redis query '<JSON command>' [--cache auto|bypass|require]
26
26
  stql redis exec '<JSON command>' [--idempotency-key KEY] [--replay]
27
27
  stql redis plan '<JSON command>'
28
- stql show|count|columns <result-handle>
29
- stql rows <result-handle> [--offset N] [--limit N]
28
+ stql show|count|columns|summarize <result-handle>
29
+ stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
30
30
  stql alias set <name> <result-handle>
31
- stql export <result-handle> --output FILE [--format json|jsonl|csv]
31
+ stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
32
32
  stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
33
33
  stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
34
34
  stql object KIND NAME [IDENTITY] [--schema NAME]
35
35
  stql transaction begin|status|commit|rollback [--isolation LEVEL]
36
- stql plan <sql> [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
36
+ stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
37
37
  stql apply <plan-handle>
38
38
  stql history [--limit N] [--offset N] [--category statement|introspection|management]
39
39
  [--internal|--external]
@@ -43,7 +43,7 @@ stql purge [expired|results|history|all]
43
43
  stql capabilities
44
44
  stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
45
45
  stql pipe [--continue-on-error]
46
- stql help
46
+ stql help [command]
47
47
  ```
48
48
 
49
49
  Global options: `--output MODE`, `--timeout-ms N`, `--max-cell-characters N`,
@@ -63,6 +63,10 @@ Use `--params JSON` for a JSON array or named parameters. Use
63
63
  `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
64
64
  JSON from standard input.
65
65
 
66
+ Use `--file FILE` instead of inline text to read the SQL, or the MongoDB or
67
+ Redis command, from a file. `--file -` reads standard input, so it cannot be
68
+ combined with `--params-file -`. A leading UTF-8 BOM is ignored.
69
+
66
70
  ## Catalog inspection
67
71
 
68
72
  Use `objects` to list a bounded page and `object` to describe an entry:
@@ -98,6 +102,8 @@ their complete error object. Empty warnings and tracing metadata are omitted.
98
102
 
99
103
  Agent mode also removes data that costs tokens but adds no information:
100
104
 
105
+ - `summarize` returns `columns` (`name`, `nulls`, `distinct`, `min`, `max`) and
106
+ one row per result column.
101
107
  - `query`, `filter`, `show`, `mongo.query`, and `rows` return `columns` once and
102
108
  each row as an array in that order. When rows have different keys (for
103
109
  example, MongoDB documents), rows stay objects and `columns` is omitted.
@@ -110,7 +116,7 @@ Agent mode also removes data that costs tokens but adds no information:
110
116
  - `capabilities` lists enabled `features` as names.
111
117
  - `objects` returns `columns` once and each entry as an array. `identity` is
112
118
  omitted when it equals `schema.name` (or `name`) for every entry.
113
- - `rows`, `count`, and `columns` do not repeat the handle you passed.
119
+ - `rows`, `count`, `columns`, and `summarize` do not repeat the handle you passed.
114
120
  - Result `handle` is the generated alias, which cannot be reassigned. Full
115
121
  `q_...` IDs work too and appear in `--output json`, `silent`, and history.
116
122
  `alias` is present only when you chose a different name (batch `as`).
@@ -45,9 +45,10 @@ export SQLITE_DATABASE='sqlite:./app.sqlite'
45
45
  stql connect --env SQLITE_DATABASE --name local --read-only
46
46
  ```
47
47
 
48
- StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password.
48
+ StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password in its state.
49
49
  Credential-bearing URLs must be supplied through `--env` or an opaque full-URL
50
- credential reference. SQLite paths remain persisted as connection metadata.
50
+ credential reference, or the password can be [saved in the OS credential
51
+ store](#saved-passwords). SQLite paths remain persisted as connection metadata.
51
52
 
52
53
  ## Local profiles
53
54
 
@@ -70,15 +71,36 @@ stql connect --profile production
70
71
  ```
71
72
 
72
73
  Credential references are bounded nonempty opaque strings; StateQL does not
73
- apply environment-variable syntax or normalization to them. They can only be
74
- resolved by a trusted host `CredentialResolver`, so the standalone CLI may
75
- store them in profiles but cannot connect with them.
74
+ apply environment-variable syntax or normalization to them. Apart from the
75
+ `os:` password references below, they can only be resolved by a trusted host
76
+ `CredentialResolver`, so the standalone CLI may store them in profiles but
77
+ cannot connect with them.
78
+
79
+ ## Saved passwords
80
+
81
+ `--ask-password` opens a password dialog and saves the password in the OS
82
+ credential store: Windows Credential Manager, macOS Keychain, or Linux Secret
83
+ Service. The profile keeps the password-free target and an `os:` password
84
+ reference.
85
+
86
+ ```bash
87
+ stql profile add charlie 'postgres://reader@db.example.com:5432/app?sslmode=verify-full' --ask-password --read-only
88
+ stql profile update charlie --ask-password # replace the saved password
89
+ stql profile remove charlie # also deletes the saved password
90
+ ```
91
+
92
+ The dialog uses Windows PowerShell on Windows, `osascript` on macOS, and `zenity`
93
+ on Linux, so it also works when an agent runs the command. Replacing the
94
+ password, changing the target or source, or removing the profile deletes the
95
+ old saved password; reconnect sessions that used it. Any program running as
96
+ your OS user can read the store, so give agent profiles a read-only database
97
+ user.
76
98
 
77
99
  A bare connection target matching a profile name resolves to that profile;
78
100
  otherwise it remains a path or database URL.
79
101
 
80
102
  `profile update` changes subsequent connections, not an already-open connection.
81
103
  Omitting the source keeps it; supplying a new source replaces the old one.
82
- Password references are configured through the library or batch API, not a CLI
83
- `--password-ref` flag. See [safe profile updates](library.md#safe-profile-updates)
104
+ Other password references are configured through the library or batch API, not
105
+ a CLI `--password-ref` flag. See [safe profile updates](library.md#safe-profile-updates)
84
106
  for source-replacement and downgrade restrictions.
package/docs/databases.md CHANGED
@@ -95,8 +95,8 @@ stql plan "REINDEX TABLE public.jobs" --allow-destructive
95
95
 
96
96
  The PostgreSQL 14–18 grammar includes parenthesized `REINDEX CONCURRENTLY`,
97
97
  PostgreSQL 16 `BUFFER_USAGE_LIMIT` for `VACUUM`/`ANALYZE`, optional
98
- `DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table *` maintenance
99
- targets. Memory sizes accept an integer number of kilobytes or a quoted
98
+ `DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table` and `table *`
99
+ maintenance targets (not both on one table). Memory sizes accept an integer number of kilobytes or a quoted
100
100
  `B|kB|MB|GB|TB` value. Older servers may reject newer forms after dispatch, so
101
101
  StateQL retains conservative unknown-outcome handling.
102
102
 
package/docs/library.md CHANGED
@@ -63,7 +63,9 @@ Library responses retain the full response envelope regardless of the CLI
63
63
  output mode. Check `response.ok` before reading `response.data`; failures expose
64
64
  `response.error`. Queries return typed `ResultData` with `result_id`, `preview`,
65
65
  and result metadata. Reuse `result_id` with methods such as `filter`, `rows`,
66
- `count`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
66
+ `count`, `summarize`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
67
+ `rows(id, { columns })` and `exportResult(id, output, format, columns)` return
68
+ only the named columns.
67
69
  Queries preview five rows by default. Set `previewRows` from 0 to 200 on an
68
70
  individual query to control its response without changing or rerunning the
69
71
  materialized result. The constructor-level `previewRows` option changes the
package/docs/results.md CHANGED
@@ -67,6 +67,18 @@ use `results`, `history`, or `all` for explicit session cleanup. On POSIX
67
67
  systems, StateQL removes group and world access from its state directory,
68
68
  database, and SQLite sidecar files.
69
69
 
70
+ ## Column projection and summaries
71
+
72
+ `rows` and `export` accept `--columns a,b` (library: `columns: ["a", "b"]`) to
73
+ return only those columns, in that order. Unknown column names fail with
74
+ `INVALID_COMMAND` and a list of the available columns.
75
+
76
+ `summarize` returns, for each column of a stored result, the null count, the
77
+ distinct count, and the min and max. Min and max are computed only when all
78
+ non-null values are numbers or all are strings. Numeric strings, such as
79
+ PostgreSQL `numeric` values, compare as numbers. Neither command accesses the
80
+ original database.
81
+
70
82
  ## Local filtering
71
83
 
72
84
  `filter` evaluates one scalar SQLite predicate against a stored result. It
package/docs/writes.md CHANGED
@@ -10,6 +10,12 @@ The flags are independent.
10
10
  the flags explicitly supplied when it is created; `apply` never adds
11
11
  authorization.
12
12
 
13
+ For a single-table SQL `UPDATE` or `DELETE` without `ORDER BY` or `LIMIT`,
14
+ `plan` also returns `estimated_rows`: a `COUNT(*)` of the rows that the `WHERE`
15
+ clause matches at plan time. The field is absent for other statements, or when
16
+ the count cannot be derived. Data can change before `apply`, so treat it as an
17
+ estimate; `affected_rows` on `apply` is the real value.
18
+
13
19
  Use an idempotency key to protect retryable writes from duplicate execution:
14
20
 
15
21
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.15.1",
3
+ "version": "0.17.0",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -47,6 +47,7 @@
47
47
  "node": ">=22.16"
48
48
  },
49
49
  "dependencies": {
50
+ "@napi-rs/keyring": "^2.1.1",
50
51
  "@redis/client": "^5.12.1",
51
52
  "bson": "^6.10.4",
52
53
  "mongodb": "^6.21.0",
@@ -22,7 +22,7 @@ If `stql --version` fails, ask the user before installing
22
22
  3. Never add `--allow-destructive`, `--allow-unbounded`, or `--replay` unless the
23
23
  user explicitly approved that operation. They are approvals, not fixes.
24
24
  4. Never put a password in a command. Remote URLs go in an environment variable
25
- that you pass with `--env`.
25
+ that you pass with `--env`, or in a profile with a saved password (below).
26
26
  5. Pass values as parameters (`--param`), never by building SQL strings.
27
27
  6. Do not rerun a query to see more rows. Use its handle.
28
28
 
@@ -37,6 +37,11 @@ stql connect --env DATABASE_URL --read-write # only for requested changes
37
37
 
38
38
  `status` without a `connection` field means no connection is open.
39
39
 
40
+ To save a remote database with its password, run
41
+ `stql profile add <name> '<password-free URL>' --ask-password`. The user types
42
+ the password in a dialog; then use `stql connect <name>`. `stql profile list`
43
+ shows saved profiles.
44
+
40
45
  ## Read workflow
41
46
 
42
47
  1. Find objects: `stql objects table --search order`
@@ -46,14 +51,18 @@ stql connect --env DATABASE_URL --read-write # only for requested changes
46
51
  4. Read the response (see below). `total` is the full row count, so you do not
47
52
  need a separate `COUNT(*)`.
48
53
  5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
49
- (default 20, maximum 1000).
54
+ (default 20, maximum 1000). Add `--columns id,email` to return only some
55
+ columns of a wide result.
56
+ To understand the data, run `stql summarize <handle>`: for each column it
57
+ returns the null count, distinct count, min, and max.
50
58
  6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
51
59
  This runs locally on the stored rows in SQLite syntax, always with `?`, and
52
60
  returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
53
61
  are stored as strings (`"7.50"`), and SQLite treats every string as greater
54
62
  than every number, so `total > ?` silently matches all rows. Wrap such
55
63
  columns in `CAST(... AS REAL)`, or filter in SQL with a new query.
56
- 7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`).
64
+ 7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`,
65
+ optional `--columns`).
57
66
 
58
67
  Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
59
68
  `--cache bypass` when data may have changed outside this session; writes made
@@ -67,7 +76,7 @@ through `stql` invalidate the cache automatically.
67
76
 
68
77
  | Field | Meaning |
69
78
  | --- | --- |
70
- | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
79
+ | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `summarize`, `show`, `export`. |
71
80
  | `columns` + `rows` | Each row is an array in `columns` order. If rows have different keys (MongoDB documents), rows are objects and `columns` is absent. |
72
81
  | `total` | Rows in the stored result. |
73
82
  | `next_offset` | Present only when more rows exist. Absent means you have every row. |
@@ -91,12 +100,16 @@ through `stql` invalidate the cache automatically.
91
100
 
92
101
  - Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
93
102
  string and breaks the query.
103
+ - For long SQL, or SQL with quotes, write it to a file and pass
104
+ `--file query.sql` instead of the inline SQL. `--file -` reads standard input.
105
+ This works for `query`, `exec`, `plan`, `stql mongo`, and `stql redis`.
94
106
  - Use parameters instead of string literals, so you do not need quotes inside
95
107
  quotes: `--param 'Ada Lovelace'`.
96
108
  - **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
97
109
  `--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
98
- Send JSON on standard input instead: `'<one JSON command>' | stql pipe` (see
99
- below), or escape every inner quote as `\"`.
110
+ Send the JSON on standard input instead:
111
+ `'{"command":"GET","args":["a"]}' | stql redis query --file -`, or
112
+ `'<one JSON command>' | stql pipe` (see below).
100
113
 
101
114
  ## Several steps in one call
102
115
 
@@ -163,4 +176,4 @@ before you use `stql mongo` or `stql redis`.
163
176
  | `stql history --limit 10` | Recent commands in this session |
164
177
  | `stql receipt <operation-handle>` | Full record of a write |
165
178
  | `stql session summary` | Open results and recent writes |
166
- | `stql help` | Command syntax |
179
+ | `stql help <command>` | Syntax of one command (`stql help` lists all) |
@@ -43,10 +43,13 @@ Use a plan when the user should review a write before it runs.
43
43
 
44
44
  ```bash
45
45
  stql plan 'DELETE FROM sessions WHERE expires_at < $1' --param 2026-01-01 --allow-destructive
46
- # show the user statement_type, required_overrides, and expires_at
46
+ # show the user statement_type, estimated_rows, required_overrides, and expires_at
47
47
  stql apply <plan-handle>
48
48
  ```
49
49
 
50
+ - `estimated_rows` is the number of rows the `WHERE` clause matched when the
51
+ plan was made. It is present only for single-table `UPDATE` and `DELETE`
52
+ without `ORDER BY`/`LIMIT`. If it is absent, count the rows with a query.
50
53
  - A plan keeps only the approval flags given to `plan`; `apply` never adds any.
51
54
  - If data changed after `plan`, `apply` returns `STALE_PLAN`. Create a new plan.
52
55
  - Plans expire after 10 minutes.