@fadhilp/stateql 0.9.0 → 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,6 +102,8 @@ export interface HistoryRecord {
     session_id: string;
     actor_id: string;
     origin: CommandOrigin;
+    category: HistoryCategory;
+    internal: number;
     command: string;
     sql: string | null;
     target: string | null;
@@ -142,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;
@@ -178,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;
@@ -277,6 +290,8 @@ export declare class StateStore {
         sessionId: string;
         actorId: string;
         origin?: CommandOrigin;
+        category?: HistoryCategory;
+        internal?: boolean;
         command: string;
         sql?: string;
         target?: string;
@@ -287,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, target, 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.target?.slice(0, 1024) ?? null, 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

@@ -26,6 +26,10 @@ export interface TableUpdate {
     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): {
@@ -34,3 +38,4 @@ export declare function compileTableUpdate(update: TableUpdate): {
     mongo?: MongoWriteCommand;
 };
 export declare function parseTableUpdate(parameters: string): TableUpdate;
+export declare function parseTableUpdates(parameters: string): TableUpdate[];

package/dist/src/table-editor.js

@@ -113,3 +113,25 @@ export function parseTableUpdate(parameters) {
         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,6 +81,8 @@ export interface HistoryEntry {
     session_id: string;
     actor_id: string;
     origin: CommandOrigin;
+    category: HistoryCategory;
+    internal: boolean;
     command: string;
     sql: string | null;
     target?: string | null;
@@ -87,6 +92,11 @@ export interface HistoryEntry {
     success: boolean;
     error_code: string | null;
 }
+export interface StateQLSnapshotOptions {
+    historyLimit?: number;
+    historyCategory?: HistoryCategory;
+    historyInternal?: boolean;
+}
 export interface StateQLSnapshot {
     session: {
         session_id: string;
@@ -195,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;
@@ -256,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;
@@ -269,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;
@@ -282,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;
@@ -292,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 {
@@ -416,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[];
@@ -428,6 +498,7 @@ export interface ResultData {
         mode: string;
         expires_at: string;
     };
+    next_cursor?: string | null;
 }
 export interface RowsData {
     result_id: string;
@@ -468,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.9.0",
+  "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 dist/test/panel.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",