@fadhilp/stateql 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -40,11 +40,23 @@ stql filter katcitg6un "name LIKE ?" --param "A%"
40
40
  stql export katcitg6un --output users.csv
41
41
  ```
42
42
 
43
+ ## Agent skill
44
+
45
+ `skills/stateql` is an [Agent Skill](https://agentskills.io) that teaches coding
46
+ agents to use `stql` safely and with few tokens. Copy the folder into your
47
+ agent's skills directory, for example for Claude Code:
48
+
49
+ ```bash
50
+ cp -r "$(npm root -g)/@fadhilp/stateql/skills/stateql" ~/.claude/skills/
51
+ ```
52
+
53
+ Use `.claude/skills/` inside a project to share it with your team.
54
+
43
55
  ## Documentation
44
56
 
45
57
  | Page | Contents |
46
58
  | --- | --- |
47
- | [Agent guide](docs/agents.md) | The short version for agents: connect, query, reuse, save tokens |
59
+ | [Agent skill](skills/stateql/SKILL.md) | Rules, workflow, response format, quoting, and errors for coding agents |
48
60
  | [Connections](docs/connections.md) | Targets, environment credentials, profiles |
49
61
  | [CLI reference](docs/cli.md) | Commands, parameters, catalog, output modes, deadlines |
50
62
  | [Results and state](docs/results.md) | Sessions, actors, limits, caching, local filtering |
package/dist/src/cli.js CHANGED
@@ -7,6 +7,7 @@ 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";
10
11
  const parsed = parseArgs({
11
12
  allowPositionals: true,
12
13
  strict: true,
@@ -15,6 +16,7 @@ const parsed = parseArgs({
15
16
  profile: { type: "string" },
16
17
  env: { type: "string" },
17
18
  "credential-ref": { type: "string" },
19
+ "ask-password": { type: "boolean" },
18
20
  "read-only": { type: "boolean" },
19
21
  "read-write": { type: "boolean" },
20
22
  params: { type: "string" },
@@ -76,6 +78,7 @@ const stateql = new StateQL({
76
78
  ...(values["max-cell-characters"] === undefined
77
79
  ? {}
78
80
  : { maxCellCharacters: Number(values["max-cell-characters"]) }),
81
+ credentialResolver: cliCredentialResolver,
79
82
  signal: abortController.signal,
80
83
  });
81
84
  try {
@@ -350,30 +353,62 @@ async function dispatchSession(action, args) {
350
353
  }
351
354
  async function dispatchProfile(action, args) {
352
355
  switch (action) {
353
- case "add":
356
+ case "add": {
354
357
  if (values["read-only"] && values["read-write"]) {
355
358
  throw new Error("--read-only and --read-write are mutually exclusive.");
356
359
  }
357
- return stateql.addProfile(requireValue(args[0], "profile name"), args[1], {
360
+ const name = requireValue(args[0], "profile name");
361
+ const passwordRef = values["ask-password"]
362
+ ? await saveOsPassword(await askPassword(name, requireValue(args[1], "TARGET for --ask-password")))
363
+ : undefined;
364
+ const added = await stateql.addProfile(name, args[1], {
358
365
  ...(values.env ? { secretEnv: values.env } : {}),
359
366
  ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
367
+ ...(passwordRef ? { passwordRef } : {}),
360
368
  readOnly: !values["read-write"],
361
369
  });
362
- case "update":
370
+ if (!added.ok)
371
+ await deleteOsPassword(passwordRef);
372
+ return added;
373
+ }
374
+ case "update": {
363
375
  if (values["read-only"] && values["read-write"])
364
376
  throw new Error("--read-only and --read-write are mutually exclusive.");
365
- return stateql.updateProfile(requireValue(args[0], "profile name"), {
377
+ const name = requireValue(args[0], "profile name");
378
+ const before = await stateql.showProfile(name);
379
+ if (!before.ok)
380
+ return before;
381
+ const target = args[1] ?? before.data.target;
382
+ const passwordRef = values["ask-password"]
383
+ ? await saveOsPassword(await askPassword(name, requireValue(target ?? undefined, "TARGET for --ask-password")))
384
+ : undefined;
385
+ const updated = await stateql.updateProfile(name, {
366
386
  ...(args[1] !== undefined ? { target: args[1] } : {}),
367
387
  ...(values.env ? { secretEnv: values.env } : {}),
368
388
  ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
389
+ ...(passwordRef ? { passwordRef } : {}),
369
390
  ...(values["read-only"] ? { readOnly: true } : values["read-write"] ? { readOnly: false } : {}),
370
391
  });
392
+ if (!updated.ok) {
393
+ await deleteOsPassword(passwordRef);
394
+ return updated;
395
+ }
396
+ if (updated.data.password_ref !== before.data.password_ref)
397
+ await deleteOsPassword(before.data.password_ref);
398
+ return updated;
399
+ }
371
400
  case "list":
372
401
  return stateql.listProfiles();
373
402
  case "show":
374
403
  return stateql.showProfile(requireValue(args[0], "profile name"));
375
- case "remove":
376
- return stateql.removeProfile(requireValue(args[0], "profile name"));
404
+ case "remove": {
405
+ const name = requireValue(args[0], "profile name");
406
+ const before = await stateql.showProfile(name);
407
+ const removed = await stateql.removeProfile(name);
408
+ if (removed.ok && before.ok)
409
+ await deleteOsPassword(before.data.password_ref);
410
+ return removed;
411
+ }
377
412
  default:
378
413
  throw new Error(`Unknown profile command "${action ?? ""}".`);
379
414
  }
@@ -406,7 +441,7 @@ function parseParameters(value, values, file) {
406
441
  : value;
407
442
  let parsedValue;
408
443
  try {
409
- parsedValue = JSON.parse(json);
444
+ parsedValue = JSON.parse(withoutBom(json));
410
445
  }
411
446
  catch {
412
447
  throw new Error(`Invalid JSON from ${file ? "--params-file" : "--params"}. ` +
@@ -447,6 +482,10 @@ async function* readBatchCommands(source) {
447
482
  yield parseBatchCommand(parseBatchJson(line, `line ${lineNumber}`), `line ${lineNumber}`);
448
483
  }
449
484
  }
485
+ // PowerShell pipes and Out-File/Notepad files can start with a UTF-8 BOM, which JSON.parse rejects.
486
+ function withoutBom(value) {
487
+ return value.startsWith("") ? value.slice(1) : value;
488
+ }
450
489
  function parseBatchCommand(value, location) {
451
490
  if (!value ||
452
491
  typeof value !== "object" ||
@@ -457,7 +496,7 @@ function parseBatchCommand(value, location) {
457
496
  }
458
497
  function parseBatchJson(value, location) {
459
498
  try {
460
- return JSON.parse(value);
499
+ return JSON.parse(withoutBom(value));
461
500
  }
462
501
  catch {
463
502
  throw new Error(`Invalid JSON at ${location}.`);
@@ -576,7 +615,7 @@ Commands:
576
615
  connect TARGET | --env ENV | --credential-ref REF | --profile NAME
577
616
  disconnect, status
578
617
  actor show | set-name NAME
579
- profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
618
+ profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
580
619
  profile list|show|remove
581
620
  query, filter, exec, show, rows, count, columns, export
582
621
  mongo query|exec|plan '<EJSON command>'
@@ -594,11 +633,12 @@ SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
594
633
  Query preview: --preview-rows N (default: 5, maximum: 200).
595
634
  Long cells: --max-cell-characters N (default: 200); use export for full values.
596
635
  Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
597
- Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
636
+ Saved passwords: --ask-password opens a dialog and keeps the password in the OS credential store.
637
+ Other credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
598
638
  State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
599
639
  Output: --output agent|json|jsonl|text|silent (default: agent).
600
640
  Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
601
- Agent output omits null fields and false cached/duplicate flags. Guide: docs/agents.md.
641
+ Agent output omits null fields and false cached/duplicate flags. Agent skill: skills/stateql/SKILL.md.
602
642
  Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
603
643
  }
604
644
  function packageVersion() {
@@ -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/docs/batch.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Batch and pipes
2
2
 
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  `batch` reads a JSON array from a `.json` file or JSONL from a `.jsonl` file.
6
6
  `pipe` reads JSONL from standard input. Commands run sequentially and stop on
package/docs/cli.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # CLI reference
2
2
 
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  ```bash
6
6
  stql connect <target> [--name NAME] [--read-only|--read-write]
@@ -11,7 +11,7 @@ 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
@@ -1,6 +1,6 @@
1
1
  # Connections and profiles
2
2
 
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  A connection accepts exactly one source: a direct target, `--env`,
6
6
  `--credential-ref`, or `--profile`. Library and batch callers may additionally
@@ -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
@@ -1,6 +1,6 @@
1
1
  # Database support
2
2
 
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  - [Driver notes](#driver-notes)
6
6
  - [SQL statement support](#sql-statement-support)
package/docs/library.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # TypeScript library
2
2
 
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  - [Getting started](#getting-started)
6
6
  - [Responses and command context](#responses-and-command-context)
package/docs/results.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Durable state and result reuse
2
2
 
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  State metadata lives under `STQL_HOME`, or the platform data directory when
6
6
  unset. StateQL keeps connections, sessions, handles, aliases, cache entries,
package/docs/writes.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Write safety
2
2
 
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
3
+ [StateQL](../README.md) · [Agent skill](../skills/stateql/SKILL.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
4
 
5
5
  Writes require a read-write connection. Destructive and unbounded SQL/MongoDB
6
6
  operations require `--allow-destructive` and `--allow-unbounded`, respectively.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -22,6 +22,7 @@
22
22
  "dist/src",
23
23
  "README.md",
24
24
  "docs",
25
+ "skills",
25
26
  "LICENSE"
26
27
  ],
27
28
  "scripts": {
@@ -46,6 +47,7 @@
46
47
  "node": ">=22.16"
47
48
  },
48
49
  "dependencies": {
50
+ "@napi-rs/keyring": "^2.1.1",
49
51
  "@redis/client": "^5.12.1",
50
52
  "bson": "^6.10.4",
51
53
  "mongodb": "^6.21.0",
@@ -0,0 +1,171 @@
1
+ ---
2
+ name: stateql
3
+ description: Query, inspect, and safely change SQLite, PostgreSQL, MySQL, MongoDB, and Redis databases with the `stql` CLI, which stores each result behind a short handle and returns compact JSON. Use when the user asks to look at a database schema, run SQL, read or page through rows, count or filter query results, export data, or make a guarded write.
4
+ ---
5
+
6
+ # StateQL (`stql`)
7
+
8
+ `stql` runs a query once, stores the full result locally, and returns a short
9
+ preview plus a handle. Page, filter, count, and export from the handle without
10
+ running the query again. Output is one line of JSON per command.
11
+
12
+ If `stql --version` fails, ask the user before installing
13
+ `npm install -g @fadhilp/stateql` (Node.js 22.16+).
14
+
15
+ ## Rules
16
+
17
+ 1. Set a session once per task: `export STQL_SESSION=<short-task-name>`
18
+ (PowerShell: `$env:STQL_SESSION = "<name>"`). Without it, every task shares
19
+ the `default` session.
20
+ 2. Connect read-only (the default). Use `--read-write` only when the user asked
21
+ for a change.
22
+ 3. Never add `--allow-destructive`, `--allow-unbounded`, or `--replay` unless the
23
+ user explicitly approved that operation. They are approvals, not fixes.
24
+ 4. Never put a password in a command. Remote URLs go in an environment variable
25
+ that you pass with `--env`, or in a profile with a saved password (below).
26
+ 5. Pass values as parameters (`--param`), never by building SQL strings.
27
+ 6. Do not rerun a query to see more rows. Use its handle.
28
+
29
+ ## Connect
30
+
31
+ ```bash
32
+ stql status # already connected in this session?
33
+ stql connect ./app.sqlite # SQLite path, read-only
34
+ stql connect --env DATABASE_URL # postgres://, mysql://, mongodb://, redis:// URL in the variable
35
+ stql connect --env DATABASE_URL --read-write # only for requested changes
36
+ ```
37
+
38
+ `status` without a `connection` field means no connection is open.
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
+
45
+ ## Read workflow
46
+
47
+ 1. Find objects: `stql objects table --search order`
48
+ 2. Read the shape: `stql object table orders` (returns the DDL or column list)
49
+ 3. Query only the columns you need, with `ORDER BY`:
50
+ `stql query 'SELECT id, total FROM orders WHERE status = $1 ORDER BY id' --param paid`
51
+ 4. Read the response (see below). `total` is the full row count, so you do not
52
+ need a separate `COUNT(*)`.
53
+ 5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
54
+ (default 20, maximum 1000).
55
+ 6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
56
+ This runs locally on the stored rows in SQLite syntax, always with `?`, and
57
+ returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
58
+ are stored as strings (`"7.50"`), and SQLite treats every string as greater
59
+ than every number, so `total > ?` silently matches all rows. Wrap such
60
+ columns in `CAST(... AS REAL)`, or filter in SQL with a new query.
61
+ 7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`).
62
+
63
+ Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
64
+ `--cache bypass` when data may have changed outside this session; writes made
65
+ through `stql` invalidate the cache automatically.
66
+
67
+ ## Response format
68
+
69
+ ```json
70
+ {"ok":true,"handle":"katcitg6un","total":331,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
71
+ ```
72
+
73
+ | Field | Meaning |
74
+ | --- | --- |
75
+ | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
76
+ | `columns` + `rows` | Each row is an array in `columns` order. If rows have different keys (MongoDB documents), rows are objects and `columns` is absent. |
77
+ | `total` | Rows in the stored result. |
78
+ | `next_offset` | Present only when more rows exist. Absent means you have every row. |
79
+ | `alias` | Present only when you named the result (batch `as`). |
80
+ | `warnings` | For example `NON_DETERMINISTIC_PAGINATION`: add `ORDER BY` before paging. |
81
+
82
+ - Exact numbers keep their precision as strings: PostgreSQL `numeric` and
83
+ `bigint`, MySQL `DECIMAL`.
84
+ - A long cell comes back as `{"type":"text","length":20000,"preview":"..."}`.
85
+ Use `--max-cell-characters N` or `export` for the full value.
86
+ - Null fields and false `cached`/`duplicate` flags are omitted.
87
+ - `rows`, `count`, and `columns` do not repeat the handle you passed.
88
+
89
+ ## Placeholders and shell quoting
90
+
91
+ | Database | Placeholders |
92
+ | --- | --- |
93
+ | SQLite, MySQL | `?` |
94
+ | PostgreSQL | `$1`, `$2`, ... |
95
+ | `filter` predicates (all databases) | `?` |
96
+
97
+ - Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
98
+ string and breaks the query.
99
+ - Use parameters instead of string literals, so you do not need quotes inside
100
+ quotes: `--param 'Ada Lovelace'`.
101
+ - **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
102
+ `--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
103
+ Send JSON on standard input instead: `'<one JSON command>' | stql pipe` (see
104
+ below), or escape every inner quote as `\"`.
105
+
106
+ ## Several steps in one call
107
+
108
+ `stql pipe` reads one JSON command per line and prints one response per line.
109
+ It stops at the first error unless you pass `--continue-on-error`. Fields use
110
+ snake_case; `as` gives a result a name that later lines can use.
111
+
112
+ ```bash
113
+ printf '%s\n' \
114
+ '{"command":"query","sql":"SELECT id, email FROM users WHERE status = $1 ORDER BY id","params":["active"],"as":"active"}' \
115
+ '{"command":"filter","handle":"active","where":"email LIKE ?","params":["%@example.com"],"as":"example"}' \
116
+ '{"command":"rows","handle":"example","offset":5,"limit":20}' | stql pipe
117
+ ```
118
+
119
+ Command names match the CLI: `query`, `filter`, `rows`, `count`, `columns`,
120
+ `show`, `export`, `exec`, `plan`, `apply`, `objects.list`, `object.describe`,
121
+ `inspect`, `mongo.query`, `redis.query`, `transaction.begin`, and so on.
122
+ `stql batch commands.json` runs a JSON array from a file.
123
+
124
+ ## Errors
125
+
126
+ Errors look like `{"ok":false,"error":{"code":"...","message":"...","retryable":false,"executed":false}}`.
127
+ Retry only when `retryable` is `true`. `executed:false` means nothing ran.
128
+
129
+ | Code | What to do |
130
+ | --- | --- |
131
+ | `INVALID_SQL` | Fix the SQL at the reported line and column. Check the placeholder style. |
132
+ | `QUERY_FAILED` | Read the database message (missing table or column, type error). Retry only if `retryable`. |
133
+ | `READ_ONLY_CONNECTION` | Ask the user before you reconnect with `--read-write`. |
134
+ | `UNBOUNDED_MUTATION` | Add a `WHERE` clause. Use `--allow-unbounded` only with user approval. |
135
+ | `DESTRUCTIVE_OPERATION_BLOCKED` | `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, and `REPLACE` need user approval, then `--allow-destructive`. |
136
+ | `POTENTIAL_DUPLICATE_WRITE` | The same write already ran (`previous_operation_id`). Do not use `--replay` unless the user wants it to run again. |
137
+ | `OUTCOME_UNKNOWN` | The write may or may not have committed. Check the data with a query before anything else. |
138
+ | `OUTPUT_LIMIT_EXCEEDED` | Results are capped at 10,000 rows and 16 MiB. Add `WHERE`/`LIMIT` or select fewer columns; page `rows` in steps of at most 1000. |
139
+ | `RESULT_NOT_FOUND`, `RESULT_EXPIRED` | Wrong session or the result expired (24 h). Run the query again. |
140
+ | `STALE_PLAN` | Data changed after `plan`. Create a new plan. |
141
+ | `TRANSACTION_FAILED` | A staged transaction is open. Reads wait until you commit or roll back. |
142
+ | `DEADLINE_EXCEEDED` | The default timeout is 30 s. Narrow the query or pass `--timeout-ms`. |
143
+ | `CONNECTION_FAILED`, `CONNECTION_NOT_FOUND` | Check `stql status`, the URL variable, and the network. |
144
+
145
+ ## Writes
146
+
147
+ Writes need a read-write connection and the user's request. Read
148
+ [reference/writes.md](reference/writes.md) before `exec`, `plan`/`apply`, or a
149
+ transaction. In short:
150
+
151
+ ```bash
152
+ stql exec 'UPDATE jobs SET claimed = 1 WHERE id = $1' --param 42 --idempotency-key claim-job-42
153
+ ```
154
+
155
+ A successful write returns `affected_rows` and `status` (`committed`, or
156
+ `pending` inside a transaction).
157
+
158
+ ## MongoDB and Redis
159
+
160
+ These use native commands, not SQL. Read [reference/native.md](reference/native.md)
161
+ before you use `stql mongo` or `stql redis`.
162
+
163
+ ## Other commands
164
+
165
+ | Command | Use |
166
+ | --- | --- |
167
+ | `stql inspect columns\|indexes\|constraints <table>` | Column, index, and constraint details |
168
+ | `stql history --limit 10` | Recent commands in this session |
169
+ | `stql receipt <operation-handle>` | Full record of a write |
170
+ | `stql session summary` | Open results and recent writes |
171
+ | `stql help` | Command syntax |
@@ -0,0 +1,61 @@
1
+ # MongoDB and Redis
2
+
3
+ SQL commands (`query`, `exec`, `plan`) are rejected on these connections. Pass
4
+ the native command as one JSON argument. In Windows PowerShell 5.1, send it
5
+ through `stql pipe` instead (field `mongo` or `redis`):
6
+
7
+ ```powershell
8
+ '{"command":"mongo.query","mongo":{"operation":"find","collection":"users","filter":{"active":true},"options":{"limit":20}}}' | stql pipe
9
+ ```
10
+
11
+ ## MongoDB
12
+
13
+ Commands use Extended JSON (EJSON): ObjectIds are `{"$oid":"..."}`, dates are
14
+ `{"$date":"2026-01-01T00:00:00Z"}`.
15
+
16
+ ```bash
17
+ stql objects collection # list collections
18
+ stql inspect columns users # fields seen in sampled documents
19
+ stql mongo query '{"operation":"find","collection":"users","filter":{"active":true},"options":{"projection":{"email":1},"sort":{"_id":1},"limit":50}}'
20
+ stql mongo query '{"operation":"aggregate","collection":"orders","pipeline":[{"$match":{"status":"paid"}},{"$group":{"_id":"$user_id","n":{"$sum":1}}}]}'
21
+ ```
22
+
23
+ | Operation | Keys |
24
+ | --- | --- |
25
+ | `find` | `collection`, `filter`, `options`: `projection`, `sort`, `skip`, `limit`, `hint`, `collation` |
26
+ | `aggregate` | `collection`, `pipeline`, `options`: `allowDiskUse`, `hint`, `collation` |
27
+ | `insertOne` / `insertMany` | `document` / `documents` |
28
+ | `updateOne` / `updateMany` | `filter`, `update`, `options`: `upsert`, `collation`, `hint` |
29
+ | `replaceOne` | `filter`, `replacement` |
30
+ | `deleteOne` / `deleteMany` | `filter` |
31
+
32
+ - Writes: `stql mongo exec '<command>'`; review first with `stql mongo plan`.
33
+ Empty filters need `--allow-unbounded`; deletes and replacements need
34
+ `--allow-destructive`. Both need user approval.
35
+ - `$out`, `$merge`, `$where`, `$function`, `$accumulator`, and server-side
36
+ JavaScript are rejected.
37
+ - Documents with different fields come back as objects, not row arrays.
38
+ - The cache cannot see changes made outside this session. Use
39
+ `--cache bypass` for a fresh read.
40
+
41
+ ## Redis
42
+
43
+ Commands are `{"command":"NAME","args":["..."]}`. All arguments are strings.
44
+
45
+ ```bash
46
+ stql objects key --search session: --limit 50 # SCAN-based; continue with --cursor <next_offset>
47
+ stql object key session:42 # type, TTL, and a bounded value
48
+ stql redis query '{"command":"HGET","args":["user:42","email"]}'
49
+ stql redis exec '{"command":"SET","args":["app:status","ready"]}' --idempotency-key status-ready
50
+ ```
51
+
52
+ | Kind | Allowed commands |
53
+ | --- | --- |
54
+ | Read (`redis query`) | `GET`, `MGET`, `TYPE`, `EXISTS`, `TTL`, `PTTL`, `HGET`, `HMGET`, bounded `LRANGE`, bounded `SCAN`/`HSCAN`/`SSCAN`/`ZSCAN` |
55
+ | Write (`redis exec`, `redis plan`) | one key: `SET`, `DEL`, `HSET`, `HDEL`, `LPUSH`, `RPUSH`, `SADD`, `SREM`, `ZADD`, `ZREM` |
56
+
57
+ - `KEYS`, scripts, pub/sub, blocking commands, and admin commands are rejected.
58
+ - Key pages can be empty or repeat keys while data changes. Keep following
59
+ `next_offset` until it is absent.
60
+ - `redis plan` then `stql apply` fails with `ROW_CONFLICT` if the key changed
61
+ in between. There are no staged transactions.
@@ -0,0 +1,70 @@
1
+ # Writes, plans, and transactions
2
+
3
+ All writes need a read-write connection (`stql connect ... --read-write`) and a
4
+ change the user asked for.
5
+
6
+ ## Safety gates
7
+
8
+ | Statement | Needs |
9
+ | --- | --- |
10
+ | `UPDATE`/`DELETE` without `WHERE`, `TRUNCATE` | `--allow-unbounded` |
11
+ | `DELETE`, `DROP`, `ALTER`, `TRUNCATE`, `REPLACE`, SQLite `INSERT/UPDATE OR REPLACE` | `--allow-destructive` |
12
+ | MongoDB empty update/replace/delete filter | `--allow-unbounded` |
13
+ | MongoDB `deleteOne`, `deleteMany`, `replaceOne` | `--allow-destructive` |
14
+
15
+ The two flags are independent: a `DELETE` without `WHERE` needs both. Add a
16
+ flag only after the user approved that exact operation. When a gate blocks a
17
+ command, the error has `override_flag`; show the user the statement and ask.
18
+
19
+ ## Direct write
20
+
21
+ ```bash
22
+ stql exec 'UPDATE jobs SET claimed = 1 WHERE id = $1' --param 42 --idempotency-key claim-job-42
23
+ ```
24
+
25
+ ```json
26
+ {"ok":true,"handle":"op_...","statement_type":"update","affected_rows":1,"status":"committed","state_version_after":"sv_1"}
27
+ ```
28
+
29
+ - Check `affected_rows` against what you expected.
30
+ - Use `--idempotency-key` for any write you might retry. The same key never
31
+ runs twice.
32
+ - Running the same statement with the same parameters again returns
33
+ `POTENTIAL_DUPLICATE_WRITE` with `previous_operation_id`. Add `--replay` only
34
+ if the user wants it to run again.
35
+ - `OUTCOME_UNKNOWN` (timeout or lost connection during the write) blocks
36
+ automatic replay. Query the data to find out whether the write happened, tell
37
+ the user, and only then decide about `--replay`.
38
+ - `stql receipt <op-handle>` shows the full record of a write.
39
+
40
+ ## Plan, then apply
41
+
42
+ Use a plan when the user should review a write before it runs.
43
+
44
+ ```bash
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
47
+ stql apply <plan-handle>
48
+ ```
49
+
50
+ - A plan keeps only the approval flags given to `plan`; `apply` never adds any.
51
+ - If data changed after `plan`, `apply` returns `STALE_PLAN`. Create a new plan.
52
+ - Plans expire after 10 minutes.
53
+
54
+ ## Staged transactions
55
+
56
+ ```bash
57
+ stql transaction begin # optional: --isolation 'repeatable read'
58
+ stql exec 'UPDATE accounts SET balance = balance - $1 WHERE id = $2' --params '[50, 1]'
59
+ stql exec 'UPDATE accounts SET balance = balance + $1 WHERE id = $2' --params '[50, 2]'
60
+ stql transaction status
61
+ stql transaction commit # or: stql transaction rollback
62
+ ```
63
+
64
+ - Writes are stored locally (`status: "pending"`) and run atomically at commit.
65
+ - While a transaction is open, reads, plans, and connection changes return
66
+ `TRANSACTION_FAILED`. Query what you need before `begin`.
67
+ - Isolation: SQLite `serializable`; PostgreSQL and MySQL also `repeatable read`,
68
+ `read committed`, `read uncommitted`.
69
+ - MySQL transactions reject DDL. MongoDB transactions need a replica set and use
70
+ `snapshot` isolation. Redis has no staged transactions.
package/docs/agents.md DELETED
@@ -1,72 +0,0 @@
1
- # Agent guide
2
-
3
- [StateQL](../README.md) · [Agents](agents.md) · [Connections](connections.md) · [CLI](cli.md) · [Results](results.md) · [Writes](writes.md) · [Batch](batch.md) · [Databases](databases.md) · [Library](library.md)
4
-
5
- The minimum an agent needs to query a database with `stql`. Read the other pages
6
- only for the topic at hand.
7
-
8
- ## Setup
9
-
10
- ```bash
11
- export STQL_SESSION=task-42 # keeps handles and aliases across calls
12
- stql connect ./app.sqlite # read-only by default
13
- stql connect --env DATABASE_URL # remote URL from an environment variable
14
- ```
15
-
16
- ## Read
17
-
18
- ```bash
19
- stql objects table --search user # find tables
20
- stql object table users # table DDL
21
- stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
22
- ```
23
-
24
- ```json
25
- {"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
26
- ```
27
-
28
- - Rows are arrays in `columns` order. If rows have different keys, they stay
29
- objects and `columns` is omitted.
30
- - `next_offset` is present only when more rows exist.
31
- - Null fields and false `cached`/`duplicate` flags are omitted.
32
- - Long cells come back as `{"type":"text","length":N,"preview":"..."}`.
33
- - `objects` uses the same `columns` + arrays shape.
34
- - `rows`, `count`, and `columns` do not repeat the handle you passed.
35
- - Result handles are short, stable aliases. Full `q_...` IDs also work.
36
- - Writes return `handle`, `statement_type`, `affected_rows`, `status`, and
37
- `state_version_after`.
38
-
39
- ## Reuse a result without querying again
40
-
41
- ```bash
42
- stql rows katcitg6un --offset 5 --limit 20
43
- stql count katcitg6un
44
- stql filter katcitg6un "name LIKE ?" --param "A%"
45
- stql export katcitg6un --output users.csv
46
- ```
47
-
48
- ## Save tokens
49
-
50
- - Select only the columns you need, and add `ORDER BY` and `LIMIT`.
51
- - Use `--preview-rows 0` when you need only the handle and `total`.
52
- - Use `stql pipe` to run several commands in one call:
53
-
54
- ```bash
55
- printf '%s\n' \
56
- '{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
57
- '{"command":"count","handle":"users"}' | stql pipe
58
- ```
59
-
60
- ## Errors
61
-
62
- Errors are `{"ok":false,"error":{"code":...,"message":...}}`. Follow
63
- `suggested_action` or `override_flag` when present. Retry only when
64
- `retryable` is true (lost connection, deadlock, lock timeout). SQL syntax errors
65
- give the line, column, and nearby text. Do not replay a write that
66
- returned `OUTCOME_UNKNOWN` until you have checked the database.
67
-
68
- ## Writes
69
-
70
- Connect with `--read-write`. Use `stql exec` with `--idempotency-key KEY` for
71
- retryable writes. Writes without `WHERE` need `--allow-unbounded`, and
72
- destructive statements need `--allow-destructive`. See [write safety](writes.md).