@fadhilp/stateql 0.5.4 → 0.6.0

package/README.md

@@ -2,8 +2,8 @@
 
 StateQL is a stateful database CLI and TypeScript library for AI agents and
 automation. It provides a safe interface for querying, changing, and inspecting
-SQLite, PostgreSQL, and MySQL databases while keeping results reusable and
-operations traceable across commands.
+SQLite, PostgreSQL, MySQL, and MongoDB databases while keeping results reusable
+and operations traceable across commands.
 
 StateQL is built around durable handles:
 
@@ -80,7 +80,7 @@ A connection accepts exactly one source: a direct target, `--env`, or
 `--profile`.
 
 ```bash
-stql connect <sqlite-path|postgres-url|mysql-url> [--name NAME] [--read-write]
+stql connect <sqlite-path|postgres-url|mysql-url|mongodb-url> [--name NAME] [--read-write]
 stql connect --env ENV [--name NAME] [--read-write]
 stql connect --profile NAME
 stql disconnect
@@ -89,9 +89,9 @@ stql status
 
 ### Environment-backed credentials
 
-PostgreSQL and MySQL credentials should come from environment variables. The
-variable must contain the complete connection URL, not only its password.
-Environment-backed SQLite paths require an explicit `sqlite:` prefix.
+PostgreSQL, MySQL, and MongoDB credentials should come from environment
+variables. The variable must contain the complete connection URL, not only its
+password. Environment-backed SQLite paths require an explicit `sqlite:` prefix.
 
 ```bash
 export APP_DATABASE_URL='postgres://user:password@host/app'
@@ -100,12 +100,16 @@ stql connect --env APP_DATABASE_URL --name app --read-only
 export MYSQL_DATABASE_URL='mysql://user:password@host/app'
 stql connect --env MYSQL_DATABASE_URL --name mysql-app --read-only
 
+export MONGODB_URL='mongodb://user:password@host/app'
+stql connect --env MONGODB_URL --name mongo-app --read-only
+
 export SQLITE_DATABASE='sqlite:./app.sqlite'
 stql connect --env SQLITE_DATABASE --name local --read-only
 ```
 
-StateQL stores no PostgreSQL or MySQL password. Credential-bearing URLs must be
-supplied through `--env`. SQLite paths remain persisted as connection metadata.
+StateQL stores no PostgreSQL, MySQL, or MongoDB password. Credential-bearing
+URLs must be supplied through `--env`. SQLite paths remain persisted as
+connection metadata.
 
 ### Local profiles
 
@@ -135,11 +139,13 @@ otherwise it remains a path or database URL.
   `uselibpqcompat=true` opts out and keeps libpq-compatible SSL semantics.
 - **MySQL:** uses positional `?` parameters. MariaDB compatibility is not
   currently claimed.
+- **MongoDB:** supports `mongodb://` and `mongodb+srv://` URLs with an explicit
+  database path. SQL methods are rejected; use the native MongoDB methods below.
 
 ## CLI reference
 
 ```text
-stql connect <sqlite-path|postgres-url|mysql-url> [--name NAME] [--read-write]
+stql connect <sqlite-path|postgres-url|mysql-url|mongodb-url> [--name NAME] [--read-write]
 stql connect --env ENV [--name NAME] [--read-write]
 stql connect --profile NAME
 stql disconnect
@@ -150,11 +156,13 @@ 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 mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
+                                  [--replay] [--allow-unbounded] [--allow-destructive]
 stql show|count|columns <result-handle>
 stql rows <result-handle> [--offset N] [--limit N]
 stql alias set <name> <result-handle>
 stql export <result-handle> --output FILE [--format json|jsonl|csv]
-stql inspect schema|table|columns|indexes|constraints [table]
+stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
 stql transaction begin|status|commit|rollback [--isolation LEVEL]
 stql plan <sql> [--allow-unbounded] [--allow-destructive]
 stql apply <plan-handle>
@@ -181,6 +189,38 @@ Use `--params JSON` for a JSON array or named parameters. Use
 `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
 JSON from standard input.
 
+### Native MongoDB
+
+MongoDB commands use official Extended JSON (EJSON), so BSON values survive the
+CLI boundary:
+
+```bash
+stql mongo query '{"operation":"find","collection":"users","filter":{"_id":{"$oid":"507f1f77bcf86cd799439011"}}}'
+stql mongo exec '{"operation":"updateOne","collection":"users","filter":{"_id":{"$oid":"507f1f77bcf86cd799439011"}},"update":{"$set":{"seen_at":{"$date":"2026-01-01T00:00:00Z"}}}}'
+stql mongo plan '{"operation":"deleteMany","collection":"users","filter":{"disabled":true}}' --allow-destructive
+```
+
+The TypeScript equivalents are `mongoQuery(command)`, `mongoExec(command)`, and
+`mongoPlan(command)`. Supported reads are `find` and `aggregate`; writes are
+`insertOne`, `insertMany`, `updateOne`, `updateMany`, `replaceOne`, `deleteOne`,
+and `deleteMany`. Result documents are JSON-safe, order-preserving EJSON: for example,
+ObjectIds and dates appear as `{ "$oid": "..." }` and
+`{ "$date": { "$numberLong": "..." } }`.
+
+Empty update, replacement, or delete filters require `--allow-unbounded`;
+deletes and replacements also require `--allow-destructive`. Mongo inspection accepts `collections`,
+`collection`, `columns`, `indexes`, and `constraints` (`schema` and `table`
+remain aliases shared with SQL drivers). MongoDB cache confidence is TTL-based:
+external writes are not detected, so use `--cache bypass` for a fresh read.
+
+```ts
+const result = await stateql.mongoQuery({
+  operation: "find",
+  collection: "users",
+  filter: { active: true },
+  options: { sort: { _id: 1 }, limit: 50 },
+});
+```
 ### Output modes
 
 CLI output defaults to compact, one-line `agent` JSON. Successful responses
@@ -211,6 +251,7 @@ cancels active work.
   block StateQL's event loop.
 - PostgreSQL combines server-side `statement_timeout` with client deadlines.
 - MySQL deadlines destroy the active connection.
+- MongoDB uses driver deadlines and closes stopped operations.
 
 A timed-out write may return `OUTCOME_UNKNOWN` when its commit status cannot be
 proven.
@@ -243,8 +284,8 @@ These caps bound persisted materialization; the independent deadline bounds
 execution time.
 
 Command history keeps the latest 10,000 entries per session. SQLite cache reuse
-also checks the database file signature. PostgreSQL and MySQL cache reuse is
-labeled `ttl_based` and is never authoritative.
+also checks the database file signature. PostgreSQL, MySQL, and MongoDB cache
+reuse is labeled `ttl_based` and is never authoritative.
 
 StateQL limits persisted result payloads to 256 MiB by default. When that quota
 is reached it removes the oldest unaliased results; aliases remain protected. A
@@ -303,6 +344,8 @@ SQLite supports `serializable`. PostgreSQL and MySQL also support
 `repeatable read`, `read committed`, and `read uncommitted`. Server reads run
 inside database-enforced read-only transactions. MySQL staged transactions
 reject DDL because MySQL implicitly commits those statements.
+MongoDB transactions use `snapshot` isolation and require a replica set or
+sharded deployment; standalone servers do not support them.
 
 ## Batch and pipes
 
@@ -345,9 +388,10 @@ 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`. Database commands may set `timeout_ms`; otherwise they use the
-30-second default.
+`apply`. Native MongoDB batches use `mongo.query`, `mongo.exec`, or `mongo.plan`
+with the command object in `mongo`; the same cache, replay, idempotency, safety,
+and timeout fields apply. Database commands may set `timeout_ms`; otherwise they
+use the 30-second default.
 
 ## TypeScript library
 
@@ -440,13 +484,12 @@ safety and duplicate checks. Requests contain actor and session identity, the
 operation's effective read/write access, an abort signal, and sanitized
 connection metadata.
 
-Returned values must be complete PostgreSQL or MySQL URLs, or explicit
+Returned values must be complete PostgreSQL, MySQL, or MongoDB URLs, or explicit
 `sqlite:` sources. StateQL validates the source and its stored driver before
-adapter construction and normalizes SQLite paths. Credential-bearing
-PostgreSQL and MySQL URLs are redacted before connection metadata is persisted
-and never enter history, snapshots, cache keys, or responses. SQLite paths
-remain persisted connection metadata, as they are for direct SQLite
-connections.
+adapter construction and normalizes SQLite paths. Credential-bearing database
+URLs are redacted before connection metadata is persisted and never enter
+history, snapshots, cache keys, or responses. SQLite paths remain persisted
+connection metadata, as they are for direct SQLite connections.
 
 Harnesses remain responsible for approval policy, binding lifetime, revocation,
 and keeping values out of their own logs and model-visible data.

package/dist/src/adapters.d.ts

@@ -26,6 +26,7 @@ export declare class AdapterWriteError extends Error {
 }
 export interface Adapter {
     readonly confidence: StateConfidence;
+    ping(): Promise<void>;
     read(sql: string, params: SqlParameters): Promise<ReadResult>;
     write(sql: string, params: SqlParameters): Promise<WriteResult>;
     writeBatch(operations: OperationRecord[], isolation: string): Promise<WriteResult[]>;

package/dist/src/adapters.js

@@ -1,6 +1,7 @@
 import { fork } from "node:child_process";
 import { createConnection as createMySqlConnection, } from "mysql2";
 import { Client, types as pgTypes } from "pg";
+import { StateQLError } from "./errors.js";
 import { isSqlParameters, parseJson, toJsonSafe } from "./util.js";
 export class AdapterExecutionError extends Error {
     reason;
@@ -36,13 +37,16 @@ export function createAdapterContext(timeoutMs, signal) {
 }
 export async function createAdapter(connection, context, input) {
     const { source } = input;
-    if (connection.driver === "sqlite") {
-        return new SQLiteAdapter(source, Boolean(connection.read_only), context);
+    switch (connection.driver) {
+        case "sqlite":
+            return new SQLiteAdapter(source, Boolean(connection.read_only), context);
+        case "postgres":
+            return new PostgresAdapter(source, Boolean(connection.read_only), context);
+        case "mysql":
+            return new MySqlAdapter(source, Boolean(connection.read_only), context);
+        case "mongodb":
+            throw new StateQLError("UNSUPPORTED_DRIVER", "MongoDB uses the native MongoDB adapter.");
     }
-    if (connection.driver === "postgres") {
-        return new PostgresAdapter(source, Boolean(connection.read_only), context);
-    }
-    return new MySqlAdapter(source, Boolean(connection.read_only), context);
 }
 class SQLiteAdapter {
     source;
@@ -85,6 +89,9 @@ class SQLiteAdapter {
             }
         });
     }
+    async ping() {
+        await this.read("SELECT 1", []);
+    }
     async read(sql, params) {
         return this.call("read", [sql, params], false, false);
     }
@@ -219,6 +226,9 @@ class PostgresAdapter {
             statement_timeout: timeout,
         });
     }
+    async ping() {
+        await this.read("SELECT 1", []);
+    }
     async read(sql, params) {
         await this.connect();
         await this.query("BEGIN READ ONLY", [], false);
@@ -440,6 +450,9 @@ class MySqlAdapter {
         this.readOnly = readOnly;
         this.context = context;
     }
+    async ping() {
+        await this.read("SELECT 1", []);
+    }
     async read(sql, params) {
         await this.query("START TRANSACTION READ ONLY", [], false, false);
         try {

package/dist/src/cli.js

@@ -3,6 +3,7 @@ import { createReadStream, readFileSync } from "node:fs";
 import { extname, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { parseArgs } from "node:util";
+import { BSON } from "mongodb";
 import { exitCodeFor } from "./errors.js";
 import { StateQL } from "./stateql.js";
 const parsed = parseArgs({
@@ -85,7 +86,10 @@ async function runSingle() {
     catch (error) {
         response = cliFailure(error);
     }
-    print(response, mode, command ?? "");
+    const responseCommand = command === "mongo" && subcommand
+        ? `mongo.${subcommand}`
+        : command ?? "";
+    print(response, mode, responseCommand);
     if (!response.ok)
         process.exitCode = exitCodeFor(response.error.code);
 }
@@ -155,6 +159,8 @@ async function dispatch() {
             return dispatchProfile(subcommand, rest);
         case "session":
             return dispatchSession(subcommand, rest);
+        case "mongo":
+            return dispatchMongo(subcommand, rest);
         case "query":
             return stateql.query(sql, {
                 params,
@@ -217,6 +223,41 @@ async function dispatch() {
             throw new Error(`Unknown command "${command}".`);
     }
 }
+async function dispatchMongo(action, args) {
+    const payload = requireValue(args.join(" ").trim(), "MongoDB EJSON command");
+    switch (action) {
+        case "query":
+            return stateql.mongoQuery(parseMongoCommand(payload), {
+                cache: cacheMode(values.cache),
+            });
+        case "exec":
+            return stateql.mongoExec(parseMongoCommand(payload), {
+                replay: values.replay ?? false,
+                ...(values["idempotency-key"]
+                    ? { idempotencyKey: values["idempotency-key"] }
+                    : {}),
+                allowUnbounded: values["allow-unbounded"] ?? false,
+                allowDestructive: values["allow-destructive"] ?? false,
+            });
+        case "plan":
+            return stateql.mongoPlan(parseMongoCommand(payload), {
+                allowUnbounded: values["allow-unbounded"] ?? false,
+                ...(values["allow-destructive"]
+                    ? { allowDestructive: true }
+                    : {}),
+            });
+        default:
+            throw new Error(`Unknown MongoDB command "${action ?? ""}".`);
+    }
+}
+function parseMongoCommand(value) {
+    try {
+        return BSON.EJSON.parse(value, { relaxed: false });
+    }
+    catch {
+        throw new Error("Invalid MongoDB EJSON command.");
+    }
+}
 async function dispatchSession(action, args) {
     switch (action) {
         case "start":
@@ -427,6 +468,7 @@ function toAgentResponse(result, currentCommand) {
     if (handle && handleKey)
         delete data[handleKey];
     if ((currentCommand === "query" ||
+        currentCommand === "mongo.query" ||
         currentCommand === "filter" ||
         currentCommand === "show") &&
         typeof data.rows === "number" &&
@@ -469,6 +511,7 @@ function toAgentResponse(result, currentCommand) {
 function primaryHandleKey(currentCommand) {
     const keys = {
         query: "result_id",
+        "mongo.query": "result_id",
         filter: "result_id",
         show: "result_id",
         rows: "result_id",
@@ -478,9 +521,11 @@ function primaryHandleKey(currentCommand) {
         alias: "result_id",
         "alias.set": "result_id",
         exec: "operation_id",
+        "mongo.exec": "operation_id",
         receipt: "operation_id",
         apply: "operation_id",
         plan: "plan_id",
+        "mongo.plan": "plan_id",
         connect: "connection_id",
         transaction: "transaction_id",
         "transaction.begin": "transaction_id",
@@ -535,8 +580,9 @@ Commands:
   profile add|list|show|remove
   session start|list|show|summary|close
   query, filter, exec, show, rows, count, columns, export
+  mongo query|exec|plan '<EJSON command>'
   alias set
-  inspect schema|table|columns|indexes|constraints
+  inspect schema|table|collection|collections|columns|indexes|constraints
   transaction begin|status|commit|rollback
   plan, apply, history, receipt, doctor, purge, capabilities
   batch [file.json|file.jsonl|-]

package/dist/src/connection.d.ts

@@ -2,6 +2,7 @@ import type { ConnectionRecord } from "./store.js";
 import type { Driver, StateConfidence } from "./types.js";
 export declare function databaseIdentity(connection: ConnectionRecord): unknown;
 export declare function detectDriver(target: string): Driver;
+export declare function mongoDatabaseName(target: string): string;
 export declare function credentialSource(value: string, expectedDriver?: Driver): {
     driver: Driver;
     source: string;

package/dist/src/connection.js

@@ -13,16 +13,41 @@ export function detectDriver(target) {
         return "postgres";
     if (/^mysql:\/\//i.test(target))
         return "mysql";
+    if (/^mongodb(?:\+srv)?:\/\//i.test(target))
+        return "mongodb";
     if (/^[a-z][a-z\d+.-]*:\/\//i.test(target)) {
-        throw new StateQLError("UNSUPPORTED_DRIVER", "Only MySQL, PostgreSQL, and SQLite are supported.");
+        throw new StateQLError("UNSUPPORTED_DRIVER", "Only MongoDB, MySQL, PostgreSQL, and SQLite are supported.");
     }
     return "sqlite";
 }
+export function mongoDatabaseName(target) {
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        throw new StateQLError("INVALID_COMMAND", "Invalid MongoDB URL.");
+    }
+    if (!["mongodb:", "mongodb+srv:"].includes(url.protocol.toLowerCase()) ||
+        !url.hostname) {
+        throw new StateQLError("INVALID_COMMAND", "Invalid MongoDB URL.");
+    }
+    try {
+        const database = decodeURIComponent(url.pathname.replace(/^\//, ""));
+        if (database && !database.includes("/") && !database.includes("\0")) {
+            return database;
+        }
+    }
+    catch {
+        // Report malformed escaping as an invalid explicit database name.
+    }
+    throw new StateQLError("INVALID_COMMAND", "MongoDB URL must include an explicit database name.");
+}
 export function credentialSource(value, expectedDriver) {
     const explicitSqlite = /^sqlite:(?!\/\/)/i.test(value);
     const driver = explicitSqlite ? "sqlite" : detectDriver(value);
     if (driver === "sqlite" && (!explicitSqlite || value.length === 7)) {
-        throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source.", {
+        throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source; MongoDB URLs are also supported.", {
             suggestedAction: "Store the full database URL, or prefix an SQLite path with sqlite:.",
         });
     }
@@ -54,7 +79,8 @@ export function normalizeSqliteSource(target) {
 export function databaseUrlHasSecret(target) {
     try {
         const url = new URL(target);
-        return (Boolean(url.password) ||
+        return (Boolean(url.username) ||
+            Boolean(url.password) ||
             [...url.searchParams.keys()].some((key) => /pass|token|secret|private[_-]?key|api[_-]?key/i.test(key)));
     }
     catch {

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
 export { StateQL } from "./stateql.js";
 export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
 export type { CredentialResolutionFailure } from "./errors.js";
-export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
+export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";

package/dist/src/migrations.js

@@ -55,6 +55,15 @@ const MIGRATIONS = [
             requireColumns(db, "history", ["sql"]);
         },
     },
+    {
+        name: "operation_outcomes_v1",
+        apply(db) {
+            addColumn(db, "operations", "outcome_json", "TEXT");
+        },
+        validate(db) {
+            requireColumns(db, "operations", ["outcome_json"]);
+        },
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -169,6 +178,7 @@ function createInitialSchema(db) {
       idempotency_key TEXT,
       state_version_before TEXT NOT NULL,
       state_version_after TEXT,
+      outcome_json TEXT,
       created_at TEXT NOT NULL
     );
     CREATE INDEX IF NOT EXISTS operations_fingerprint

package/dist/src/mongodb.d.ts

@@ -0,0 +1,48 @@
+import { type AdapterContext } from "./adapters.js";
+import type { ConnectionRecord } from "./store.js";
+import type { Column, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, Row } from "./types.js";
+interface MongoReadResult {
+    rows: Row[];
+    columns: Column[];
+}
+interface MongoWriteResult {
+    affectedRows: number;
+    outcome: MongoWriteOutcome;
+}
+interface MongoWriteSafety {
+    unbounded: boolean;
+    destructive: boolean;
+}
+export declare function validateMongoReadCommand(value: unknown): MongoReadCommand;
+export declare function validateMongoWriteCommand(value: unknown): MongoWriteCommand;
+export declare function analyzeMongoWriteSafety(command: MongoWriteCommand): MongoWriteSafety;
+/** Deterministic EJSON preserves BSON types and property order. */
+export declare function serializeMongoCommand(command: MongoReadCommand | MongoWriteCommand): string;
+export declare function deserializeMongoWriteCommand(value: string): MongoWriteCommand;
+export declare class MongoAdapter {
+    private readonly context;
+    readonly confidence: "ttl_based";
+    private readonly client;
+    private readonly databaseName;
+    private readonly readOnly;
+    private connected;
+    private closed;
+    private connecting?;
+    constructor(connection: ConnectionRecord, context: AdapterContext, input: {
+        source: string;
+    });
+    ping(): Promise<void>;
+    signature(): Promise<string>;
+    read(command: MongoReadCommand, maxRows: number): Promise<MongoReadResult>;
+    write(command: MongoWriteCommand): Promise<MongoWriteResult>;
+    writeBatch(commands: MongoWriteCommand[], isolation: string): Promise<MongoWriteResult[]>;
+    inspect(kind: string, name?: string): Promise<unknown>;
+    close(): Promise<void>;
+    private connect;
+    private executeWrite;
+    private requireCollection;
+    private sampleColumns;
+    private collectionIndexes;
+    private stop;
+}
+export {};