@fadhilp/stateql 0.8.1 → 0.10.0

package/dist/src/store.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
-import type { Column, CommandOrigin, Driver, MongoWriteOutcome, Row, SqlParameters, StateConfidence } from "./types.js";
+import type { Column, CommandOrigin, Driver, HistoryCategory, MongoWriteOutcome, Row, SqlParameters, StateConfidence } from "./types.js";
 export interface SessionRecord {
     id: string;
     name: string;
@@ -46,6 +46,7 @@ export interface ResultRecord {
     state_confidence: StateConfidence;
     expires_at: string;
     created_at: string;
+    alias?: string;
 }
 export interface OperationRecord {
     id: string;
@@ -101,8 +102,11 @@ export interface HistoryRecord {
     session_id: string;
     actor_id: string;
     origin: CommandOrigin;
+    category: HistoryCategory;
+    internal: number;
     command: string;
     sql: string | null;
+    target: string | null;
     handle: string | null;
     executed: number;
     cached: number;
@@ -141,6 +145,13 @@ export declare class StateStore {
         credentialRef?: string;
         readOnly: boolean;
     }): ProfileRecord;
+    updateProfile(input: {
+        name: string;
+        target: string | null;
+        secretEnv: string | null;
+        credentialRef: string | null;
+        readOnly: boolean;
+    }): ProfileRecord | undefined;
     getProfile(name: string): ProfileRecord | undefined;
     listProfiles(): ProfileRecord[];
     removeProfile(name: string): boolean;
@@ -177,6 +188,9 @@ export declare class StateStore {
     resultRows(result: ResultRecord): Row[];
     resultColumns(result: ResultRecord): Column[];
     setAlias(sessionId: string, name: string, resultId: string): void;
+    generatedAlias(resultId: string): string;
+    private allocateGeneratedAlias;
+    private backfillGeneratedAliases;
     saveOperation(input: {
         sessionId: string;
         actorId: string;
@@ -276,8 +290,11 @@ export declare class StateStore {
         sessionId: string;
         actorId: string;
         origin?: CommandOrigin;
+        category?: HistoryCategory;
+        internal?: boolean;
         command: string;
         sql?: string;
+        target?: string;
         handle?: string;
         executed: boolean;
         cached: boolean;
@@ -285,7 +302,12 @@ export declare class StateStore {
         errorCode?: string;
         id?: string;
     }): HistoryRecord;
-    history(sessionId: string, limit: number, origin?: CommandOrigin): HistoryRecord[];
+    history(sessionId: string, limit: number, input?: CommandOrigin | {
+        origin?: CommandOrigin;
+        category?: HistoryCategory;
+        internal?: boolean;
+        offset?: number;
+    }): HistoryRecord[];
     recentOperations(sessionId: string, limit: number): OperationRecord[];
     knownResults(sessionId: string, limit: number): Array<ResultRecord & {
         alias: string | null;

package/dist/src/store.js

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, statSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { join } from "node:path";
@@ -35,6 +36,7 @@ export class StateStore {
             this.db.exec("PRAGMA busy_timeout = 5000");
             this.db.exec("PRAGMA foreign_keys = ON");
             runMigrations(this.db, this.now);
+            this.backfillGeneratedAliases();
             this.recoverStaleCommittingTransactions();
             this.deleteExpiredData();
         }
@@ -240,6 +242,12 @@ export class StateStore {
             .run(input.name, input.target ?? null, input.secretEnv ?? null, input.credentialRef ?? null, input.readOnly ? 1 : 0, timestamp, timestamp);
         return this.getProfile(input.name);
     }
+    updateProfile(input) {
+        const result = this.db.prepare(`UPDATE profiles
+       SET target = ?, secret_env = ?, credential_ref = ?, read_only = ?, updated_at = ?
+       WHERE name = ?`).run(input.target, input.secretEnv, input.credentialRef, input.readOnly ? 1 : 0, this.now().toISOString(), input.name);
+        return Number(result.changes) === 1 ? this.getProfile(input.name) : undefined;
+    }
     getProfile(name) {
         return this.db
             .prepare("SELECT * FROM profiles WHERE name = ?")
@@ -341,6 +349,7 @@ export class StateStore {
            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
                 .run(id, input.sessionId, input.connectionId, input.fingerprint, input.sql, JSON.stringify(toJsonSafe(input.parameters)), JSON.stringify(toJsonSafe(input.rows)), JSON.stringify(input.columns), input.rows.length, input.stateVersion, input.stateSignature, input.stateConfidence, input.expiresAt, this.now().toISOString());
             this.enforceResultQuota(id);
+            this.allocateGeneratedAlias(input.sessionId, id);
             const result = this.getResult(id);
             this.db.exec("COMMIT");
             return result;
@@ -351,15 +360,18 @@ export class StateStore {
         }
     }
     findResult(fingerprint) {
-        return this.db
+        const result = this.db
             .prepare(`SELECT * FROM results
          WHERE fingerprint = ?
          ORDER BY created_at DESC
          LIMIT 1`)
             .get(fingerprint);
+        if (result)
+            result.alias = this.generatedAlias(result.id);
+        return result;
     }
     getResult(idOrAlias, sessionId) {
-        return this.db
+        const result = this.db
             .prepare(`SELECT results.*
          FROM results
          LEFT JOIN aliases
@@ -369,6 +381,9 @@ export class StateStore {
            AND (? IS NULL OR results.session_id = ?)
          LIMIT 1`)
             .get(idOrAlias, idOrAlias, sessionId ?? null, sessionId ?? null);
+        if (result)
+            result.alias = this.generatedAlias(result.id);
+        return result;
     }
     resultRows(result) {
         return parseJson(result.rows_json, `result "${result.id}" rows`, isRows);
@@ -377,12 +392,55 @@ export class StateStore {
         return parseJson(result.columns_json, `result "${result.id}" columns`, isColumns);
     }
     setAlias(sessionId, name, resultId) {
+        const existing = this.db.prepare("SELECT result_id, generated FROM aliases WHERE session_id = ? AND name = ?").get(sessionId, name);
+        if (existing?.generated) {
+            if (existing.result_id === resultId)
+                return;
+            throw new StateQLError("INVALID_COMMAND", "Generated result aliases cannot be reassigned.");
+        }
         this.db
-            .prepare(`INSERT INTO aliases(session_id, name, result_id)
-         VALUES (?, ?, ?)
+            .prepare(`INSERT INTO aliases(session_id, name, result_id, generated)
+         VALUES (?, ?, ?, 0)
          ON CONFLICT(session_id, name) DO UPDATE SET result_id = excluded.result_id`)
             .run(sessionId, name, resultId);
     }
+    generatedAlias(resultId) {
+        const row = this.db.prepare("SELECT name FROM aliases WHERE result_id = ? AND generated = 1").get(resultId);
+        if (!row)
+            throw new Error(`Result "${resultId}" has no generated alias.`);
+        return row.name;
+    }
+    allocateGeneratedAlias(sessionId, resultId) {
+        const existing = this.db.prepare("SELECT name FROM aliases WHERE result_id = ? AND generated = 1").get(resultId);
+        if (existing)
+            return existing.name;
+        for (let attempt = 0; attempt < 64; attempt++) {
+            const name = randomBase32Alias();
+            this.db.prepare("INSERT OR IGNORE INTO aliases(session_id, name, result_id, generated) VALUES (?, ?, ?, 1)").run(sessionId, name, resultId);
+            const allocated = this.db.prepare("SELECT name FROM aliases WHERE result_id = ? AND generated = 1").get(resultId);
+            if (allocated)
+                return allocated.name;
+        }
+        throw new Error("Could not allocate a unique result alias.");
+    }
+    backfillGeneratedAliases() {
+        const results = this.db.prepare(`SELECT results.id, results.session_id
+       FROM results
+       LEFT JOIN aliases ON aliases.result_id = results.id AND aliases.generated = 1
+       WHERE aliases.result_id IS NULL`).all();
+        if (!results.length)
+            return;
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            for (const result of results)
+                this.allocateGeneratedAlias(result.session_id, result.id);
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
     saveOperation(input) {
         const id = this.nextId("op");
         this.db
@@ -797,10 +855,10 @@ export class StateStore {
         const id = input.id ?? this.nextId("cmd");
         this.db
             .prepare(`INSERT INTO history
-          (id, timestamp, session_id, actor_id, origin, command, sql, handle,
+          (id, timestamp, session_id, actor_id, origin, category, internal, command, sql, target, handle,
            executed, cached, success, error_code)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.origin ?? "legacy", input.command, boundedHistorySql(input.sql), input.handle ?? null, input.executed ? 1 : 0, input.cached ? 1 : 0, input.success ? 1 : 0, input.errorCode ?? null);
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.origin ?? "legacy", input.category ?? "management", input.internal ? 1 : 0, input.command, boundedHistorySql(input.sql), input.target?.slice(0, 1024) ?? null, input.handle ?? null, input.executed ? 1 : 0, input.cached ? 1 : 0, input.success ? 1 : 0, input.errorCode ?? null);
         this.db
             .prepare(`DELETE FROM history
          WHERE rowid IN (
@@ -814,13 +872,29 @@ export class StateStore {
             .prepare("SELECT * FROM history WHERE id = ?")
             .get(id);
     }
-    history(sessionId, limit, origin) {
+    history(sessionId, limit, input = {}) {
+        const options = typeof input === "string" ? { origin: input } : input;
+        const predicates = ["session_id = ?"];
+        const values = [sessionId];
+        if (options.origin !== undefined) {
+            predicates.push("origin = ?");
+            values.push(options.origin);
+        }
+        if (options.category !== undefined) {
+            predicates.push("category = ?");
+            values.push(options.category);
+        }
+        if (options.internal !== undefined) {
+            predicates.push("internal = ?");
+            values.push(options.internal ? 1 : 0);
+        }
+        values.push(limit, options.offset ?? 0);
         return this.db
             .prepare(`SELECT * FROM history
-         WHERE session_id = ?${origin === undefined ? "" : " AND origin = ?"}
+         WHERE ${predicates.join(" AND ")}
          ORDER BY rowid DESC
-         LIMIT ?`)
-            .all(...(origin === undefined ? [sessionId, limit] : [sessionId, origin, limit]));
+         LIMIT ? OFFSET ?`)
+            .all(...values);
     }
     recentOperations(sessionId, limit) {
         return this.db
@@ -837,6 +911,7 @@ export class StateStore {
          LEFT JOIN aliases
            ON aliases.result_id = results.id
           AND aliases.session_id = results.session_id
+          AND aliases.generated = 1
          WHERE results.session_id = ?
          ORDER BY results.created_at DESC
          LIMIT ?`)
@@ -946,12 +1021,13 @@ export class StateStore {
         while (this.resultBytes() > this.maxStateBytes) {
             const candidate = this.db.prepare(`SELECT id FROM results
          WHERE id <> ? AND NOT EXISTS (
-           SELECT 1 FROM aliases WHERE aliases.result_id = results.id
+           SELECT 1 FROM aliases WHERE aliases.result_id = results.id AND aliases.generated = 0
          )
          ORDER BY created_at, rowid LIMIT 1`).get(protectedId);
             if (!candidate) {
                 throw new StateQLError("STATE_QUOTA_EXCEEDED", `Stored results exceed the ${this.maxStateBytes}-byte state quota.`, { suggestedAction: "Purge results or increase maxStateBytes." });
             }
+            this.db.prepare("DELETE FROM aliases WHERE result_id = ? AND generated = 1").run(candidate.id);
             this.db.prepare("DELETE FROM results WHERE id = ?").run(candidate.id);
         }
     }
@@ -1019,6 +1095,10 @@ export class StateStore {
 function outcomeJson(outcome) {
     return outcome === undefined ? null : JSON.stringify(toJsonSafe(outcome));
 }
+function randomBase32Alias() {
+    const alphabet = "abcdefghijklmnopqrstuvwxyz234567";
+    return [...randomBytes(10)].map((value) => alphabet[value & 31]).join("");
+}
 function boundedHistorySql(sql) {
     if (sql === undefined)
         return null;

package/dist/src/table-editor.d.ts

@@ -0,0 +1,41 @@
+import type { Driver, MongoWriteCommand, Row, SqlParameters } from "./types.js";
+export interface TableIdentity {
+    schema?: string;
+    name: string;
+}
+export interface EditableColumn {
+    name: string;
+    type: string;
+    nullable: boolean;
+    generated: boolean;
+    key: number;
+}
+export interface EditableTable {
+    table: TableIdentity;
+    driver: Driver;
+    columns: EditableColumn[];
+    writable: boolean;
+    reason?: string;
+}
+export interface TableChange {
+    set?: Record<string, unknown>;
+    unset?: string[];
+}
+export interface TableUpdate {
+    metadata: EditableTable;
+    original: Row;
+    changes: TableChange;
+}
+export interface TableUpdateBatch {
+    version: 1;
+    updates: TableUpdate[];
+}
+export declare function quoteIdentifier(name: string, driver: Driver): string;
+export declare function editableRow(metadata: EditableTable, row: Row): boolean;
+export declare function compileTableUpdate(update: TableUpdate): {
+    sql: string;
+    params: SqlParameters;
+    mongo?: MongoWriteCommand;
+};
+export declare function parseTableUpdate(parameters: string): TableUpdate;
+export declare function parseTableUpdates(parameters: string): TableUpdate[];

package/dist/src/table-editor.js

@@ -0,0 +1,137 @@
+import { BSON } from "mongodb";
+import { StateQLError } from "./errors.js";
+export function quoteIdentifier(name, driver) {
+    if (!name || name.length > 500 || name.includes("\0"))
+        throw new StateQLError("INVALID_COMMAND", "Invalid database identifier.");
+    return driver === "mysql" ? "`" + name.replaceAll("`", "``") + "`" : '"' + name.replaceAll('"', '""') + '"';
+}
+function comparable(value, column) {
+    if (value === null)
+        return column.nullable;
+    const type = column.type.toLowerCase();
+    if (/^(?:tinyint|smallint|mediumint|int|integer|bigint|int2|int4|int8)(?:\b|$)/u.test(type))
+        return typeof value === "number" ? Number.isSafeInteger(value) : typeof value === "string" && /^-?\d+$/u.test(value);
+    if (/^(?:numeric|decimal)(?:\b|$)/u.test(type))
+        return typeof value === "string" && /^-?\d+(?:\.\d+)?$/u.test(value);
+    if (/^(?:boolean|bool)$/u.test(type))
+        return typeof value === "boolean";
+    if (/^(?:text|varchar|character varying|nvarchar|ntext|longtext|mediumtext|tinytext)(?:\b|$)/u.test(type))
+        return typeof value === "string" && value.length <= 16_384;
+    return false;
+}
+function mongoScalarType(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return "string";
+    if (typeof value === "boolean")
+        return "bool";
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length !== 1)
+        return undefined;
+    const types = { $oid: "objectId", $numberInt: "int", $numberLong: "long", $numberDecimal: "decimal", $date: "date" };
+    return types[Object.keys(value)[0]];
+}
+export function editableRow(metadata, row) {
+    if (!metadata.writable || Buffer.byteLength(JSON.stringify(row), "utf8") > 32 * 1024)
+        return false;
+    if (metadata.driver === "mongodb")
+        return Object.hasOwn(row, "_id") && Object.entries(row).every(([key, value]) => !key.startsWith("$") && !key.includes(".") && mongoScalarType(value) !== undefined);
+    const keys = metadata.columns.filter(column => column.key > 0);
+    return keys.length > 0 && keys.every(column => row[column.name] !== null && row[column.name] !== undefined) &&
+        metadata.columns.length === Object.keys(row).length && metadata.columns.every(column => Object.hasOwn(row, column.name) && comparable(row[column.name], column));
+}
+export function compileTableUpdate(update) {
+    const { metadata, original, changes } = update;
+    if (!editableRow(metadata, original))
+        throw new StateQLError("INVALID_COMMAND", "This row has no safe editable identity or comparison types.");
+    const entries = Object.entries(changes.set ?? {});
+    const unset = changes.unset ?? [];
+    if ((!entries.length && !unset.length) || entries.length + unset.length > 100 || Buffer.byteLength(JSON.stringify(changes), "utf8") > 32 * 1024)
+        throw new StateQLError("INVALID_COMMAND", "Provide bounded changed cells.");
+    if (metadata.driver === "mongodb") {
+        for (const name of [...entries.map(([name]) => name), ...unset]) {
+            if (name === "_id" || !Object.hasOwn(original, name) || name.startsWith("$") || name.includes("."))
+                throw new StateQLError("INVALID_COMMAND", "Only existing non-key fields can be changed.");
+        }
+        const document = BSON.EJSON.deserialize(original, { relaxed: false });
+        const mongo = {
+            operation: "updateOne", collection: metadata.table.name,
+            filter: { _id: document._id, $expr: { $and: [
+                        { $eq: ["$$ROOT", { $literal: document }] },
+                        ...Object.entries(original).map(([name, value]) => ({ $eq: [{ $type: "$" + name }, mongoScalarType(value)] })),
+                    ] } },
+            update: { ...(entries.length ? { $set: BSON.EJSON.deserialize(Object.fromEntries(entries), { relaxed: false }) } : {}), ...(unset.length ? { $unset: Object.fromEntries(unset.map(name => [name, ""])) } : {}) },
+            options: { upsert: false, collation: { locale: "simple" } },
+        };
+        return { sql: "MongoDB conditional row update", params: [], mongo };
+    }
+    if (unset.length)
+        throw new StateQLError("INVALID_COMMAND", "SQL columns cannot be unset; use null where allowed.");
+    const driver = metadata.driver;
+    const quote = (name) => quoteIdentifier(name, driver);
+    const params = [];
+    const parameter = (value) => { params.push(value); return driver === "postgres" ? "$" + params.length : "?"; };
+    const assignments = entries.map(([name, value]) => {
+        const column = metadata.columns.find(column => column.name === name);
+        if (!column || column.key || column.generated || !comparable(value, column))
+            throw new StateQLError("INVALID_COMMAND", "A changed column is generated, a key, or has an unsupported value.");
+        return quote(name) + " = " + parameter(value);
+    });
+    const predicates = metadata.columns.map(column => {
+        const name = quote(column.name);
+        if (original[column.name] === null)
+            return name + " IS NULL";
+        const placeholder = parameter(original[column.name]);
+        const isText = /text|varchar|character varying/u.test(column.type.toLowerCase());
+        if (driver === "postgres") {
+            const left = isText ? "convert_to(" + name + ", 'UTF8')" : name;
+            const right = isText ? "convert_to(" + placeholder + ", 'UTF8')" : placeholder;
+            return left + " = " + right;
+        }
+        if (driver === "mysql")
+            return isText ? "CAST(" + name + " AS BINARY) = CAST(" + placeholder + " AS BINARY)" : name + " = " + placeholder;
+        return isText ? "CAST(" + name + " AS BLOB) IS CAST(" + placeholder + " AS BLOB)" : name + " IS " + placeholder;
+    });
+    const table = [metadata.table.schema, metadata.table.name].filter((name) => Boolean(name)).map(quote).join(".");
+    return { sql: "UPDATE " + table + " SET " + assignments.join(", ") + " WHERE " + predicates.join(" AND "), params };
+}
+export function parseTableUpdate(parameters) {
+    try {
+        const outer = JSON.parse(parameters);
+        if (!Array.isArray(outer) || outer.length !== 1 || typeof outer[0] !== "string" || outer[0].length > 128 * 1024)
+            throw new Error();
+        const update = JSON.parse(outer[0]);
+        if (!update || !update.metadata || !["sqlite", "postgres", "mysql", "mongodb"].includes(update.metadata.driver) ||
+            !Array.isArray(update.metadata.columns) || update.metadata.columns.length > 100 ||
+            !update.metadata.columns.every(column => typeof column.name === "string" && typeof column.type === "string" && typeof column.nullable === "boolean" && typeof column.generated === "boolean" && Number.isSafeInteger(column.key)) ||
+            !update.original || !update.changes || typeof update.changes !== "object")
+            throw new Error();
+        compileTableUpdate(update);
+        return update;
+    }
+    catch {
+        throw new StateQLError("STALE_PLAN", "The stored table update is invalid. Reload the row and plan again.");
+    }
+}
+export function parseTableUpdates(parameters) {
+    try {
+        const outer = JSON.parse(parameters);
+        if (!Array.isArray(outer) || outer.length !== 1 || typeof outer[0] !== "string" || outer[0].length > 512 * 1024)
+            throw new Error();
+        const batch = JSON.parse(outer[0]);
+        if (!batch || batch.version !== 1 || !Array.isArray(batch.updates) || batch.updates.length < 1 || batch.updates.length > 100)
+            throw new Error();
+        for (const update of batch.updates) {
+            if (!update?.metadata || !["sqlite", "postgres", "mysql", "mongodb"].includes(update.metadata.driver) ||
+                !Array.isArray(update.metadata.columns) || update.metadata.columns.length > 100 ||
+                !update.metadata.columns.every(column => typeof column.name === "string" && typeof column.type === "string" && typeof column.nullable === "boolean" && typeof column.generated === "boolean" && Number.isSafeInteger(column.key)) ||
+                !update.original || !update.changes || typeof update.changes !== "object")
+                throw new Error();
+            compileTableUpdate(update);
+        }
+        return batch.updates;
+    }
+    catch {
+        throw new StateQLError("STALE_PLAN", "The stored table update batch is invalid. Reload the rows and plan again.");
+    }
+}

package/dist/src/types.d.ts

@@ -1,10 +1,13 @@
 export type SqlDriver = "sqlite" | "postgres" | "mysql";
-export type Driver = SqlDriver | "mongodb";
+export type Driver = SqlDriver | "mongodb" | "redis";
 export type CommandOrigin = "legacy" | "user" | "model" | "system" | "api";
+export type HistoryCategory = "statement" | "introspection" | "management";
 /** Trusted host metadata for one executeCommand call; never part of BatchCommand input. */
 export interface CommandExecutionContext {
     signal?: AbortSignal;
     origin?: CommandOrigin;
+    /** Marks host-generated setup or introspection separately from user statements. */
+    internal?: boolean;
 }
 export type CredentialAccess = "read" | "write";
 export type CredentialOperation = "connect" | "query" | "inspect" | "plan" | "exec" | "apply" | "transaction.commit";
@@ -78,14 +81,22 @@ export interface HistoryEntry {
     session_id: string;
     actor_id: string;
     origin: CommandOrigin;
+    category: HistoryCategory;
+    internal: boolean;
     command: string;
     sql: string | null;
+    target?: string | null;
     handle: string | null;
     executed: boolean;
     cached: boolean;
     success: boolean;
     error_code: string | null;
 }
+export interface StateQLSnapshotOptions {
+    historyLimit?: number;
+    historyCategory?: HistoryCategory;
+    historyInternal?: boolean;
+}
 export interface StateQLSnapshot {
     session: {
         session_id: string;
@@ -194,12 +205,49 @@ export interface MongoWriteOutcome {
     upserted_id?: unknown;
     deleted_count?: number;
 }
+export interface RedisCommand {
+    command: string;
+    args?: string[];
+}
+export interface RedisWriteOutcome extends MongoWriteOutcome {
+    result: string | number | null;
+}
+export type CatalogObjectKind = "table" | "view" | "collection" | "function" | "trigger" | "enum" | "key";
+export interface CatalogObject {
+    kind: CatalogObjectKind;
+    schema?: string;
+    name: string;
+    /** Stable database-native overload/object identity when name alone is ambiguous. */
+    identity?: string;
+    [key: string]: unknown;
+}
+export interface ListObjectsFilter {
+    kind?: CatalogObjectKind;
+    schema?: string;
+    search?: string;
+    /** Numeric for SQL/MongoDB; Redis uses its opaque SCAN cursor string. */
+    offset?: number | string;
+    limit?: number;
+}
+export interface ListObjectsData {
+    objects: CatalogObject[];
+    next_offset: number | string | null;
+    supported_kinds: CatalogObjectKind[];
+}
+export interface DescribeObjectData {
+    object: CatalogObject;
+    definition?: string | Record<string, unknown> | unknown[] | null;
+    [key: string]: unknown;
+}
 export interface ExecutionOptions {
     timeoutMs?: number;
     signal?: AbortSignal;
 }
 export interface HistoryOptions {
     origin?: CommandOrigin;
+    category?: HistoryCategory;
+    internal?: boolean;
+    offset?: number;
 }
 export interface StateQLOptions extends ExecutionOptions {
     home?: string;
@@ -255,6 +303,21 @@ export interface ProfileOptions {
     secretEnv?: string;
     credentialRef?: string;
 }
+export interface ProfileUpdateOptions {
+    target?: string | null;
+    secretEnv?: string | null;
+    credentialRef?: string | null;
+    readOnly?: boolean;
+}
+export interface RedisQueryOptions extends ExecutionOptions {
+    cache?: "auto" | "bypass" | "require";
+}
+export interface RedisExecOptions extends ExecutionOptions {
+    replay?: boolean;
+    idempotencyKey?: string;
+}
+export interface RedisPlanOptions extends ExecutionOptions {
+}
 export interface RowsOptions {
     offset?: number;
     limit?: number;
@@ -268,7 +331,7 @@ export interface MongoPlanOptions extends ExecutionOptions {
     allowUnbounded?: boolean;
     allowDestructive?: boolean;
 }
-export type BatchCommandName = "connect" | "disconnect" | "status" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "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" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
+export type BatchCommandName = "connect" | "disconnect" | "status" | "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";
 export interface BatchCommand {
     command: BatchCommandName;
     target?: string;
@@ -281,6 +344,8 @@ export interface BatchCommand {
     table?: string;
     params?: SqlParameters;
     mongo?: MongoReadCommand | MongoWriteCommand;
+    redis?: RedisCommand;
+    object?: CatalogObject;
     cache?: "auto" | "bypass" | "require";
     read_only?: boolean;
     secret_env?: string;
@@ -291,11 +356,14 @@ export interface BatchCommand {
     allow_unbounded?: boolean;
     allow_destructive?: boolean;
     offset?: number;
+    cursor?: string;
     limit?: number;
     isolation?: string;
     timeout_ms?: number;
     /** Retrieval filter for the history command; does not attribute this command. */
     history_origin?: CommandOrigin;
+    history_category?: HistoryCategory;
+    history_internal?: boolean;
     scope?: "expired" | "results" | "history" | "all";
 }
 export interface BatchOptions {
@@ -415,6 +483,9 @@ export interface SessionSummaryData {
 }
 export interface ResultData {
     result_id: string;
+    alias: string;
+    /** Canonical generated alias; remains stable even when alias is an explicit caller alias. */
+    display_alias: string;
     rows: number;
     columns: Column[];
     preview: Row[];
@@ -427,6 +498,7 @@ export interface ResultData {
         mode: string;
         expires_at: string;
     };
+    next_cursor?: string | null;
 }
 export interface RowsData {
     result_id: string;
@@ -467,7 +539,7 @@ export interface OperationData {
     state_version_before: string;
     state_version_after: string | null;
     replay_of?: string;
-    outcome?: MongoWriteOutcome;
+    outcome?: MongoWriteOutcome | RedisWriteOutcome;
 }
 export interface ExecData extends OperationData {
     duplicate?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/mongodb.test.js dist/test/mysql.test.js dist/test/postgres.test.js dist/test/query.test.js dist/test/sqlite.test.js dist/test/store.test.js dist/test/terminal.test.js dist/test/transaction.test.js dist/test/write.test.js",
+    "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/mongodb.test.js dist/test/mysql.test.js dist/test/postgres.test.js dist/test/query.test.js dist/test/redis.test.js dist/test/sqlite.test.js dist/test/store.test.js dist/test/terminal.test.js dist/test/transaction.test.js dist/test/write.test.js dist/test/panel.test.js",
     "release": "npm version",
     "version": "npm install",
     "prepack": "npm test"
@@ -37,6 +37,7 @@
     "postgresql",
     "cli",
     "agents",
+    "redis",
     "sql"
   ],
   "license": "MIT",
@@ -44,6 +45,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
+    "@redis/client": "^5.12.1",
     "mongodb": "^6.21.0",
     "mysql2": "^3.23.1",
     "node-sql-parser": "^5.4.0",