@fadhilp/stateql 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StateQL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# StateQL
+
+StateQL is a stateful database CLI for AI agents and automation. It provides a
+safe interface for querying, changing, and inspecting databases while keeping
+results reusable and operations traceable across commands.
+
+Requires Node.js 22.5 or newer.
+
+## Quick start
+
+Connect to an existing SQLite database, then run a filtered, parameterized
+query. Parameters keep values separate from SQL; `ORDER BY` makes paging
+stable, while `LIMIT` bounds work at the database.
+
+```bash
+npm install --global stateql
+export STQL_SESSION=audit
+stql profile add local ./app.sqlite
+stql connect local
+
+stql query \
+  "SELECT id, name, email FROM users WHERE status = ? AND created_at >= ? ORDER BY id LIMIT 50" \
+  --param active \
+  --param 2026-01-01
+```
+
+Example output:
+
+```json
+{"ok":true,"handle":"q_1","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"},{"id":18,"name":"Linus","email":"linus@kernel.org"}],"truncated":false,"cached":false,"total":3,"next_offset":null}
+```
+
+`q_1` is a durable result handle. Filter its stored snapshot without querying
+the original database; the result becomes another durable handle:
+
+```bash
+stql filter q_1 "email LIKE ?" --param "%@example.com"
+```
+
+```json
+{"ok":true,"handle":"q_2","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"}],"truncated":false,"cached":false,"total":2,"next_offset":null}
+```
+
+Give the derived result a readable alias, page through it, inspect its count,
+or export it—all without rerunning SQL:
+
+```bash
+stql alias set example-users q_2
+stql rows example-users --offset 0 --limit 1
+stql rows example-users --offset 1 --limit 1
+stql count example-users
+stql export example-users --output example-users.csv --format csv
+```
+
+Example first page:
+
+```json
+{"ok":true,"handle":"q_2","rows":[{"id":7,"name":"Ada","email":"ada@example.com"}],"total":2,"truncated":true,"next_offset":1}
+```
+
+Running the same normalized query with the same parameters reuses `q_1` while
+its cache is valid. Use `--cache bypass` when a fresh read is required.
+
+PostgreSQL credentials should come from an environment variable:
+
+```bash
+export APP_DATABASE_URL='postgres://user:password@host/app'
+stql connect --env APP_DATABASE_URL --name app --read-only
+```
+
+## Commands
+
+```text
+stql connect <sqlite-path|postgres-url> [--name NAME] [--env ENV] [--read-write]
+stql connect --profile NAME
+stql status
+stql profile add|list|show|remove
+stql session start|list|show|summary|close
+stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
+stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
+stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
+              [--allow-unbounded] [--allow-destructive]
+stql show|count|columns <result-handle>
+stql rows <result-handle> [--offset N] [--limit N]
+stql export <result-handle> --output FILE [--format json|jsonl|csv]
+stql inspect schema|table|columns|indexes|constraints [table]
+stql transaction begin|status|commit|rollback [--isolation LEVEL]
+stql plan <sql> [--allow-unbounded] [--allow-destructive]
+stql apply <plan-handle>
+stql history [--limit N]
+stql receipt <operation-handle>
+stql capabilities
+stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
+stql pipe [--continue-on-error]
+```
+
+## Output modes
+
+CLI output defaults to compact, one-line `agent` JSON. Successes flatten useful
+data and expose the primary durable ID as `handle`; errors retain their complete
+error object. Empty warnings and tracing metadata are omitted.
+
+```json
+{"ok":false,"error":{"code":"UNBOUNDED_MUTATION","message":"Mutation has no WHERE clause.","retryable":false,"executed":false,"override_flag":"--allow-unbounded"}}
+```
+
+Use `--output json` for the original pretty, verbose envelope, or
+`--output jsonl` for that envelope on one line. `--output text` prints a short
+human status; `--output silent` prints only a successful handle. Set
+`STQL_OUTPUT` to choose a mode globally. For `export`, `--output` names the
+file, so use `STQL_OUTPUT` to choose its response mode. Library responses keep
+the full envelope regardless of CLI mode.
+
+For shell-safe positional parameters, repeat `--param`. JSON scalars become
+their native types; other values remain strings.
+
+```powershell
+stql exec "INSERT INTO users (name, status) VALUES (?, ?)" `
+  --param Ada --param trial
+```
+
+Use `--params-file FILE` for arrays or named parameters that are awkward to
+quote. `--params-file -` reads JSON from standard input.
+
+## Local profiles
+
+Profiles persist under `STQL_HOME` with other StateQL metadata.
+
+```bash
+stql profile add local ./app.sqlite --read-write
+stql profile add production --env PROD_DATABASE_URL --read-only
+stql profile list
+stql connect local
+stql connect --profile production
+```
+
+A bare connection target matching a profile name resolves to that profile;
+otherwise it remains a path or database URL. Profiles store targets, read-only
+policy, and environment-variable names. Credential values are never stored.
+
+## Batch and pipes
+
+`batch` reads a JSON array from a `.json` file or JSONL from a `.jsonl` file.
+`pipe` reads JSONL from standard input. Commands run sequentially and stop on
+the first error unless `--continue-on-error` is set. Output defaults to one
+compact `agent` JSON object per line.
+
+```bash
+printf '%s\n' \
+  '{"command":"query","sql":"SELECT id, email FROM users ORDER BY id","as":"users"}' \
+  '{"command":"filter","handle":"users","where":"email LIKE ?","params":["%@example.com"],"as":"example_users"}' \
+  '{"command":"rows","handle":"example_users","limit":10}' |
+  stql pipe
+```
+
+```json
+[
+  {
+    "command": "exec",
+    "sql": "UPDATE jobs SET claimed = 1 WHERE id = ?",
+    "params": [42],
+    "idempotency_key": "claim-job-42"
+  },
+  {
+    "command": "query",
+    "sql": "SELECT * FROM jobs WHERE id = ?",
+    "params": [42]
+  }
+]
+```
+
+Run the array with `stql batch commands.json`. Batch fields use snake case;
+supported command names match CLI paths, such as `filter`,
+`transaction.begin`, `session.summary`, `alias.set`, `plan`, and `apply`.
+Batch filters use `where` for the predicate and may assign the derived result
+with `as`.
+
+State metadata lives under `STQL_HOME`, or the platform data directory when
+unset. Set `STQL_SESSION` to select a named session.
+
+Read cache entries expire after five minutes; materialized handles expire after
+24 hours. Queries exceeding 10,000 rows fail before materialization; add a
+narrower `WHERE` clause or `LIMIT`. Command history keeps the latest 10,000
+entries per session. SQLite cache reuse also checks
+the database file signature; PostgreSQL reuse is labeled `ttl_based`, never
+authoritative. Transactions are staged in local state so they survive CLI
+invocations, then executed atomically on commit. Connections cannot be changed
+or disconnected while a transaction is active. SQLite supports `serializable`;
+PostgreSQL also supports `repeatable read`, `read committed`, and
+`read uncommitted`. PostgreSQL reads run inside database-enforced read-only
+transactions.
+
+StateQL stores no PostgreSQL password. Credential-bearing URLs must be supplied
+through `--env`. SQLite result rows are materialized locally for durable access.
+`filter` evaluates one scalar SQLite predicate against those stored rows, keeps
+source order, state metadata, and expiry, and never accesses the original
+database. Use parameters for values. Subqueries, query-shaping clauses, and
+non-allowlisted functions are rejected; common deterministic functions such as
+`lower`, `upper`, `length`, and `coalesce` are supported.
+
+Destructive and unbounded operations require their respective flags
+independently. Plans persist only flags explicitly supplied when the plan is
+created; `apply` never adds authorization. If a database write starts but its
+final outcome cannot be recorded safely, StateQL returns `OUTCOME_UNKNOWN` and
+blocks automatic replay. Inspect database state before using `--replay`.
+Interrupted commits remain fail-closed; stale `committing` records become
+`outcome_unknown` after five minutes.
+
+## Library
+
+```ts
+import { StateQL } from "stateql";
+
+const stateql = new StateQL({ home: "./.stql" });
+const response = await stateql.query("SELECT * FROM users");
+if (response.ok) {
+  const handle = (response.data as { result_id: string }).result_id;
+  await stateql.filter(handle, "email LIKE ?", {
+    params: ["%@example.com"],
+  });
+}
+```

package/dist/src/adapters.d.ts

@@ -0,0 +1,23 @@
+import type { Column, Row, SqlParameters, StateConfidence } from "./types.js";
+import type { ConnectionRecord, OperationRecord } from "./store.js";
+export interface ReadResult {
+    rows: Row[];
+    columns: Column[];
+}
+export interface WriteResult {
+    affectedRows: number;
+}
+export declare class BatchWriteError extends Error {
+    readonly outcomeUnknown: boolean;
+    constructor(message: string, outcomeUnknown: boolean);
+}
+export interface Adapter {
+    readonly confidence: StateConfidence;
+    read(sql: string, params: SqlParameters): Promise<ReadResult>;
+    write(sql: string, params: SqlParameters): Promise<WriteResult>;
+    writeBatch(operations: OperationRecord[], isolation: string): Promise<WriteResult[]>;
+    signature(): Promise<string>;
+    inspect(kind: string, table?: string): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare function createAdapter(connection: ConnectionRecord): Promise<Adapter>;

package/dist/src/adapters.js

@@ -0,0 +1,346 @@
+import { existsSync, statSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { Client, types as pgTypes } from "pg";
+import { hash, parseJson, toJsonSafe } from "./util.js";
+export class BatchWriteError extends Error {
+    outcomeUnknown;
+    constructor(message, outcomeUnknown) {
+        super(message);
+        this.outcomeUnknown = outcomeUnknown;
+        this.name = "BatchWriteError";
+    }
+}
+export async function createAdapter(connection) {
+    const source = connection.secret_env
+        ? process.env[connection.secret_env]
+        : connection.source;
+    if (!source) {
+        throw new Error(`Environment variable ${connection.secret_env ?? "(missing)"} is not set.`);
+    }
+    if (connection.driver === "sqlite") {
+        return new SQLiteAdapter(source, Boolean(connection.read_only));
+    }
+    return new PostgresAdapter(source, Boolean(connection.read_only));
+}
+class SQLiteAdapter {
+    source;
+    readOnly;
+    confidence = "database_reported";
+    db;
+    constructor(source, readOnly) {
+        this.source = source;
+        this.readOnly = readOnly;
+        this.db = new DatabaseSync(source, {
+            readOnly,
+            enableForeignKeyConstraints: true,
+        });
+        this.db.exec("PRAGMA busy_timeout = 5000");
+    }
+    async read(sql, params) {
+        const statement = this.db.prepare(sql);
+        const rows = bindAll(statement, params);
+        return {
+            rows: toJsonSafe(rows),
+            columns: statement.columns().map((column) => ({
+                name: column.name,
+                type: column.type?.toLowerCase() ?? inferType(rows, column.name),
+            })),
+        };
+    }
+    async write(sql, params) {
+        if (this.readOnly)
+            throw new Error("Connection is read-only.");
+        const result = bindRun(this.db.prepare(sql), params);
+        return { affectedRows: Number(result.changes) };
+    }
+    async writeBatch(operations, isolation) {
+        if (this.readOnly)
+            throw new Error("Connection is read-only.");
+        if (isolation !== "serializable") {
+            throw new Error(`SQLite does not support isolation level "${isolation}".`);
+        }
+        const results = [];
+        try {
+            this.db.exec("BEGIN");
+        }
+        catch (error) {
+            throw new BatchWriteError(errorText(error), false);
+        }
+        try {
+            for (const operation of operations) {
+                results.push(await this.write(operation.sql, parseJson(operation.parameters, [])));
+            }
+        }
+        catch (error) {
+            try {
+                this.db.exec("ROLLBACK");
+            }
+            catch {
+                throw new BatchWriteError(errorText(error), true);
+            }
+            throw new BatchWriteError(errorText(error), false);
+        }
+        try {
+            this.db.exec("COMMIT");
+            return results;
+        }
+        catch (error) {
+            try {
+                this.db.exec("ROLLBACK");
+                throw new BatchWriteError(errorText(error), false);
+            }
+            catch (rollbackError) {
+                if (rollbackError instanceof BatchWriteError)
+                    throw rollbackError;
+                throw new BatchWriteError(errorText(error), true);
+            }
+        }
+    }
+    async signature() {
+        if (this.source === ":memory:")
+            return "memory";
+        const stats = statSync(this.source, { bigint: true });
+        const walPath = `${this.source}-wal`;
+        const wal = existsSync(walPath)
+            ? statSync(walPath, { bigint: true })
+            : undefined;
+        return hash({
+            size: stats.size.toString(),
+            modified: stats.mtimeNs.toString(),
+            walSize: wal?.size.toString() ?? "0",
+            walModified: wal?.mtimeNs.toString() ?? "0",
+        });
+    }
+    async inspect(kind, table) {
+        if (kind === "schema") {
+            const tables = this.db
+                .prepare(`SELECT name, type
+           FROM sqlite_master
+           WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'
+           ORDER BY name`)
+                .all();
+            return { schema: "main", tables };
+        }
+        if (!table)
+            throw new Error(`Table is required for inspect ${kind}.`);
+        const quoted = quoteSqliteLiteral(table);
+        const columns = this.db
+            .prepare(`PRAGMA table_info(${quoted})`)
+            .all();
+        if (columns.length === 0)
+            throw new Error(`Table "${table}" was not found.`);
+        const indexes = this.db
+            .prepare(`PRAGMA index_list(${quoted})`)
+            .all();
+        const foreignKeys = this.db
+            .prepare(`PRAGMA foreign_key_list(${quoted})`)
+            .all();
+        if (kind === "columns")
+            return { table, columns };
+        if (kind === "indexes")
+            return { table, indexes };
+        if (kind === "constraints") {
+            return {
+                table,
+                primary_key: columns
+                    .filter((column) => Number(column.pk) > 0)
+                    .map((column) => column.name),
+                foreign_keys: foreignKeys,
+            };
+        }
+        if (kind !== "table")
+            throw new Error(`Unknown inspection kind "${kind}".`);
+        return {
+            table,
+            schema: "main",
+            columns: columns.map((column) => ({
+                name: column.name,
+                type: String(column.type).toLowerCase(),
+                nullable: column.notnull === 0 && Number(column.pk) === 0,
+                primary_key: Number(column.pk) > 0,
+            })),
+            indexes: indexes.length,
+            foreign_keys: foreignKeys.length,
+        };
+    }
+    async close() {
+        this.db.close();
+    }
+}
+class PostgresAdapter {
+    readOnly;
+    confidence = "ttl_based";
+    client;
+    connected = false;
+    constructor(source, readOnly) {
+        this.readOnly = readOnly;
+        this.client = new Client({ connectionString: source });
+    }
+    async read(sql, params) {
+        await this.connect();
+        await this.client.query("BEGIN READ ONLY");
+        try {
+            const result = await this.client.query(sql, postgresParams(params));
+            await this.client.query("COMMIT");
+            return {
+                rows: toJsonSafe(result.rows),
+                columns: result.fields.map((field) => ({
+                    name: field.name,
+                    type: pgTypes.getTypeParser(field.dataTypeID).name ||
+                        `oid_${field.dataTypeID}`,
+                })),
+            };
+        }
+        catch (error) {
+            await this.client.query("ROLLBACK");
+            throw error;
+        }
+    }
+    async write(sql, params) {
+        if (this.readOnly)
+            throw new Error("Connection is read-only.");
+        await this.connect();
+        const result = await this.client.query(sql, postgresParams(params));
+        return { affectedRows: result.rowCount ?? 0 };
+    }
+    async writeBatch(operations, isolation) {
+        if (this.readOnly)
+            throw new Error("Connection is read-only.");
+        await this.connect();
+        const level = isolation.toUpperCase();
+        if (!POSTGRES_ISOLATION_LEVELS.has(level)) {
+            throw new Error(`Unsupported PostgreSQL isolation level "${isolation}".`);
+        }
+        try {
+            await this.client.query(`BEGIN ISOLATION LEVEL ${level}`);
+        }
+        catch (error) {
+            throw new BatchWriteError(errorText(error), false);
+        }
+        const results = [];
+        try {
+            for (const operation of operations) {
+                results.push(await this.write(operation.sql, parseJson(operation.parameters, [])));
+            }
+        }
+        catch (error) {
+            try {
+                await this.client.query("ROLLBACK");
+            }
+            catch {
+                throw new BatchWriteError(errorText(error), true);
+            }
+            throw new BatchWriteError(errorText(error), false);
+        }
+        try {
+            await this.client.query("COMMIT");
+            return results;
+        }
+        catch (error) {
+            try {
+                await this.client.query("ROLLBACK");
+            }
+            catch {
+                // COMMIT response was lost; rollback cannot establish outcome.
+            }
+            throw new BatchWriteError(errorText(error), true);
+        }
+    }
+    async signature() {
+        return "ttl";
+    }
+    async inspect(kind, table) {
+        await this.connect();
+        if (kind === "schema") {
+            const result = await this.client.query(`SELECT table_schema AS schema, table_name AS name, table_type AS type
+         FROM information_schema.tables
+         WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+         ORDER BY table_schema, table_name`);
+            return { tables: result.rows };
+        }
+        if (!table)
+            throw new Error(`Table is required for inspect ${kind}.`);
+        const [schema, name] = table.includes(".")
+            ? table.split(".", 2)
+            : ["public", table];
+        const columns = await this.client.query(`SELECT column_name AS name, data_type AS type,
+              is_nullable = 'YES' AS nullable
+       FROM information_schema.columns
+       WHERE table_schema = $1 AND table_name = $2
+       ORDER BY ordinal_position`, [schema, name]);
+        if (columns.rows.length === 0) {
+            throw new Error(`Table "${table}" was not found.`);
+        }
+        if (kind === "columns")
+            return { table: name, schema, columns: columns.rows };
+        const indexes = await this.client.query(`SELECT indexname AS name, indexdef AS definition
+       FROM pg_indexes WHERE schemaname = $1 AND tablename = $2
+       ORDER BY indexname`, [schema, name]);
+        const constraints = await this.client.query(`SELECT constraint_name AS name, constraint_type AS type
+       FROM information_schema.table_constraints
+       WHERE table_schema = $1 AND table_name = $2
+       ORDER BY constraint_name`, [schema, name]);
+        if (kind === "indexes")
+            return { table: name, schema, indexes: indexes.rows };
+        if (kind === "constraints") {
+            return { table: name, schema, constraints: constraints.rows };
+        }
+        if (kind !== "table")
+            throw new Error(`Unknown inspection kind "${kind}".`);
+        return {
+            table: name,
+            schema,
+            columns: columns.rows,
+            indexes: indexes.rows.length,
+            constraints: constraints.rows.length,
+        };
+    }
+    async close() {
+        if (this.connected)
+            await this.client.end();
+    }
+    async connect() {
+        if (this.connected)
+            return;
+        await this.client.connect();
+        this.connected = true;
+        if (this.readOnly) {
+            await this.client.query("SET default_transaction_read_only = on");
+        }
+    }
+}
+const POSTGRES_ISOLATION_LEVELS = new Set([
+    "SERIALIZABLE",
+    "REPEATABLE READ",
+    "READ COMMITTED",
+    "READ UNCOMMITTED",
+]);
+function bindAll(statement, params) {
+    if (Array.isArray(params))
+        return statement.all(...params);
+    return statement.all(params);
+}
+function bindRun(statement, params) {
+    if (Array.isArray(params))
+        return statement.run(...params);
+    return statement.run(params);
+}
+function postgresParams(params) {
+    if (Array.isArray(params))
+        return params;
+    throw new Error("PostgreSQL parameters must be a JSON array.");
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function inferType(rows, name) {
+    const value = rows.find((row) => row[name] !== null)?.[name];
+    if (value === undefined)
+        return "unknown";
+    if (Buffer.isBuffer(value))
+        return "binary";
+    return typeof value;
+}
+function quoteSqliteLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};