@fadhilp/stateql 0.13.2 → 0.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -85,7 +85,6 @@ See [write safety](docs/usage.md#write-safety),
85
85
  | [Usage](docs/usage.md) | Connections, CLI reference, results, sessions, limits, writes, transactions, batch and pipes |
86
86
  | [Database support](docs/databases.md) | SQL dialects, diagnostics, maintenance, native MongoDB and Redis commands |
87
87
  | [TypeScript library](docs/library.md) | Connection setup, response handling, cleanup, actors, workspaces, and credential resolution |
88
- | [SQL command roadmap](SQL_COMMAND_ROADMAP.md) | Development priorities and requirements for extending SQL support |
89
88
 
90
89
  Run `stql --help` for command syntax or `stql capabilities` for capability details.
91
90
 
@@ -1,8 +1,12 @@
1
1
  import { fork } from "node:child_process";
2
- import { createConnection as createMySqlConnection, } from "mysql2";
3
- import { Client, types as pgTypes } from "pg";
2
+ import { createRequire } from "node:module";
4
3
  import { StateQLError } from "./errors.js";
5
4
  import { isSqlParameters, parseJson, toJsonSafe } from "./util.js";
5
+ const require = createRequire(import.meta.url);
6
+ let mysqlModule;
7
+ let postgresModule;
8
+ const mysql = () => (mysqlModule ??= require("mysql2"));
9
+ const postgres = () => (postgresModule ??= require("pg"));
6
10
  export class AdapterExecutionError extends Error {
7
11
  reason;
8
12
  outcomeUnknown;
@@ -237,11 +241,14 @@ class PostgresAdapter {
237
241
  context;
238
242
  confidence = "ttl_based";
239
243
  client;
244
+ pgTypes;
240
245
  connected = false;
241
246
  ending;
242
247
  constructor(source, readOnly, context) {
243
248
  this.readOnly = readOnly;
244
249
  this.context = context;
250
+ const { Client, types } = postgres();
251
+ this.pgTypes = types;
245
252
  const timeout = Math.min(2_147_483_647, remainingMilliseconds(context));
246
253
  this.client = new Client({
247
254
  connectionString: normalizePostgresConnectionString(source),
@@ -263,7 +270,7 @@ class PostgresAdapter {
263
270
  rows: toJsonSafe(result.rows),
264
271
  columns: result.fields.map((field) => ({
265
272
  name: field.name,
266
- type: pgTypes.getTypeParser(field.dataTypeID).name ||
273
+ type: this.pgTypes.getTypeParser(field.dataTypeID).name ||
267
274
  `oid_${field.dataTypeID}`,
268
275
  })),
269
276
  };
@@ -884,7 +891,7 @@ class MySqlAdapter {
884
891
  throwIfStopped(this.context, false);
885
892
  if (this.closed)
886
893
  throw new Error("MySQL adapter is closed.");
887
- const rawClient = createMySqlConnection({
894
+ const rawClient = mysql().createConnection({
888
895
  uri: this.source,
889
896
  connectTimeout: remainingMilliseconds(this.context),
890
897
  multipleStatements: false,
package/dist/src/cli.js CHANGED
@@ -164,6 +164,8 @@ async function dispatch() {
164
164
  return stateql.disconnect();
165
165
  case "status":
166
166
  return stateql.status();
167
+ case "actor":
168
+ return dispatchActor(subcommand, rest);
167
169
  case "profile":
168
170
  return dispatchProfile(subcommand, rest);
169
171
  case "session":
@@ -315,6 +317,16 @@ function parseMongoCommand(value) {
315
317
  throw new Error("Invalid MongoDB EJSON command.");
316
318
  }
317
319
  }
320
+ async function dispatchActor(action, args) {
321
+ switch (action) {
322
+ case "show":
323
+ return stateql.showActor();
324
+ case "set-name":
325
+ return stateql.setActorName(requireValue(args.join(" ").trim(), "actor name"));
326
+ default:
327
+ throw new Error(`Unknown actor command "${action ?? ""}".`);
328
+ }
329
+ }
318
330
  async function dispatchSession(action, args) {
319
331
  switch (action) {
320
332
  case "start":
@@ -645,6 +657,7 @@ Usage: stql <command> [arguments] [options]
645
657
  Commands:
646
658
  connect TARGET | --env ENV | --credential-ref REF | --profile NAME
647
659
  disconnect, status
660
+ actor show | set-name NAME
648
661
  profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
649
662
  profile list|show|remove
650
663
  query, filter, exec, show, rows, count, columns, export
@@ -131,6 +131,26 @@ const MIGRATIONS = [
131
131
  apply: migratePasswordRefs,
132
132
  validate: validatePasswordRefs,
133
133
  },
134
+ {
135
+ name: "actor_display_names_v1",
136
+ apply(db) {
137
+ addColumn(db, "session_members", "actor_name", "TEXT");
138
+ addColumn(db, "history", "actor_name", "TEXT");
139
+ db.exec(`
140
+ UPDATE session_members SET actor_name = actor_id WHERE actor_name IS NULL;
141
+ UPDATE history SET actor_name = actor_id WHERE actor_name IS NULL;
142
+ `);
143
+ },
144
+ validate(db) {
145
+ requireColumns(db, "session_members", ["actor_name"]);
146
+ requireColumns(db, "history", ["actor_name"]);
147
+ for (const table of ["session_members", "history"]) {
148
+ const row = db.prepare(`SELECT COUNT(*) AS count FROM ${table} WHERE actor_name IS NULL OR actor_name = ''`).get();
149
+ if (row.count)
150
+ throw new Error(`State migration left ${table}.actor_name empty.`);
151
+ }
152
+ },
153
+ },
134
154
  ];
135
155
  export function runMigrations(db, now) {
136
156
  db.exec(`
@@ -178,6 +198,7 @@ function createInitialSchema(db) {
178
198
  CREATE TABLE IF NOT EXISTS session_members (
179
199
  session_id TEXT NOT NULL,
180
200
  actor_id TEXT NOT NULL UNIQUE,
201
+ actor_name TEXT NOT NULL,
181
202
  attached_at TEXT NOT NULL,
182
203
  PRIMARY KEY(session_id, actor_id),
183
204
  FOREIGN KEY(session_id) REFERENCES sessions(id)
@@ -294,6 +315,7 @@ function createInitialSchema(db) {
294
315
  timestamp TEXT NOT NULL,
295
316
  session_id TEXT NOT NULL,
296
317
  actor_id TEXT NOT NULL,
318
+ actor_name TEXT NOT NULL,
297
319
  command TEXT NOT NULL,
298
320
  origin TEXT NOT NULL DEFAULT 'legacy',
299
321
  category TEXT NOT NULL DEFAULT 'management',
@@ -313,19 +335,22 @@ function migrateSharedSessionActors(db) {
313
335
  CREATE TABLE IF NOT EXISTS session_members (
314
336
  session_id TEXT NOT NULL,
315
337
  actor_id TEXT NOT NULL UNIQUE,
338
+ actor_name TEXT,
316
339
  attached_at TEXT NOT NULL,
317
340
  PRIMARY KEY(session_id, actor_id),
318
341
  FOREIGN KEY(session_id) REFERENCES sessions(id)
319
342
  )
320
343
  `);
344
+ addColumn(db, "session_members", "actor_name", "TEXT");
321
345
  addColumn(db, "operations", "actor_id", "TEXT");
322
346
  addColumn(db, "transactions", "owner_actor_id", "TEXT");
323
347
  addColumn(db, "plans", "owner_actor_id", "TEXT");
324
348
  addColumn(db, "plans", "claim_token", "TEXT");
325
349
  addColumn(db, "history", "actor_id", "TEXT");
326
350
  db.exec(`
327
- INSERT OR IGNORE INTO session_members(session_id, actor_id, attached_at)
328
- SELECT id, name, created_at FROM sessions;
351
+ INSERT OR IGNORE INTO session_members(session_id, actor_id, actor_name, attached_at)
352
+ SELECT id, name, name, created_at FROM sessions;
353
+ UPDATE session_members SET actor_name = actor_id WHERE actor_name IS NULL;
329
354
  UPDATE operations SET actor_id = (
330
355
  SELECT name FROM sessions WHERE sessions.id = operations.session_id
331
356
  ) WHERE actor_id IS NULL;
@@ -1,5 +1,9 @@
1
- import { BSON, MongoClient, } from "mongodb";
1
+ import { createRequire } from "node:module";
2
+ import { BSON } from "bson";
2
3
  import { AdapterExecutionError, AdapterWriteError, BatchWriteError, } from "./adapters.js";
4
+ const require = createRequire(import.meta.url);
5
+ let mongodbModule;
6
+ const mongodb = () => (mongodbModule ??= require("mongodb"));
3
7
  const MAX_INSPECTION_ITEMS = 1_000;
4
8
  const FIND_OPTIONS = new Set([
5
9
  "projection",
@@ -170,7 +174,7 @@ export class MongoAdapter {
170
174
  this.databaseName = connection.database_name;
171
175
  this.readOnly = Boolean(connection.read_only);
172
176
  const timeout = remainingMilliseconds(context);
173
- this.client = new MongoClient(input.source, {
177
+ this.client = new (mongodb().MongoClient)(input.source, {
174
178
  connectTimeoutMS: timeout,
175
179
  serverSelectionTimeoutMS: timeout,
176
180
  waitQueueTimeoutMS: timeout,
package/dist/src/redis.js CHANGED
@@ -1,6 +1,9 @@
1
- import { createClient, RESP_TYPES, WatchError } from "@redis/client";
1
+ import { createRequire } from "node:module";
2
2
  import { AdapterExecutionError, AdapterWriteError } from "./adapters.js";
3
3
  import { hash, toJsonSafe } from "./util.js";
4
+ const require = createRequire(import.meta.url);
5
+ let redisModule;
6
+ const redis = () => (redisModule ??= require("@redis/client"));
4
7
  const MAX_ARGUMENTS = 100;
5
8
  const MAX_ARGUMENT_BYTES = 256 * 1024;
6
9
  const MAX_RESPONSE_BYTES = 1024 * 1024;
@@ -105,7 +108,7 @@ export class RedisAdapter {
105
108
  constructor(source, readOnly, context) {
106
109
  this.readOnly = readOnly;
107
110
  this.context = context;
108
- this.client = createClient({
111
+ this.client = redis().createClient({
109
112
  url: source,
110
113
  socket: {
111
114
  connectTimeout: remainingMilliseconds(context),
@@ -183,7 +186,7 @@ export class RedisAdapter {
183
186
  catch (error) {
184
187
  if (error instanceof AdapterWriteError)
185
188
  throw error;
186
- if (error instanceof WatchError)
189
+ if (error instanceof redis().WatchError)
187
190
  throw new AdapterWriteError("ROW_CONFLICT: The Redis key changed. Reload before editing.", false);
188
191
  if (error instanceof AdapterExecutionError)
189
192
  throw error;
@@ -274,7 +277,7 @@ export class RedisAdapter {
274
277
  }
275
278
  const [type, dump] = await Promise.all([
276
279
  this.execute(["TYPE", key], false),
277
- withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
280
+ withDeadline(this.client.sendCommand(["DUMP", key], { typeMapping: { [redis().RESP_TYPES.BLOB_STRING]: Buffer } }), this.context, false, () => this.stop()),
278
281
  ]);
279
282
  const encoded = Buffer.isBuffer(dump) ? dump.toString("base64") : dump;
280
283
  if (Buffer.byteLength(JSON.stringify(encoded), "utf8") > MAX_RESPONSE_BYTES * 2) {
package/dist/src/sql.js CHANGED
@@ -1,7 +1,14 @@
1
1
  import { createRequire } from "node:module";
2
2
  import { StateQLError } from "./errors.js";
3
- const { Parser } = createRequire(import.meta.url)("node-sql-parser");
4
- const parser = new Parser();
3
+ const require = createRequire(import.meta.url);
4
+ let parser;
5
+ function sqlParser() {
6
+ if (!parser) {
7
+ const { Parser } = require("node-sql-parser");
8
+ parser = new Parser();
9
+ }
10
+ return parser;
11
+ }
5
12
  const SUPPORTED_STATEMENTS = new Set([
6
13
  "select",
7
14
  "insert",
@@ -44,6 +51,7 @@ export function analyzeSql(sql, driver) {
44
51
  }
45
52
  }
46
53
  function parseSqlStatement(sql, driver) {
54
+ const parser = sqlParser();
47
55
  const database = driver === "postgres"
48
56
  ? "Postgresql"
49
57
  : driver === "mysql"
@@ -1,5 +1,5 @@
1
1
  import { type TableChange } from "./table-editor.js";
2
- import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
2
+ import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
3
3
  export declare class StateQL {
4
4
  /** Runtime contract marker for passwordRef/password_ref support. */
5
5
  static readonly passwordReferenceVersion: 1;
@@ -39,6 +39,8 @@ export declare class StateQL {
39
39
  status(): Promise<Response<StatusData>>;
40
40
  linkActor(session: string, actorId: string): Promise<Response<ActorLinkData>>;
41
41
  unlinkActor(session: string, actorId: string): Promise<Response<ActorUnlinkData>>;
42
+ showActor(): Promise<Response<ActorData>>;
43
+ setActorName(name: string): Promise<Response<ActorData>>;
42
44
  listActors(session: string): Promise<Response<ActorsData>>;
43
45
  resolveActor(actorId: string): Promise<Response<ActorResolutionData>>;
44
46
  startSession(name: string): Promise<Response<SessionData>>;
@@ -132,6 +134,7 @@ export declare class StateQL {
132
134
  private requireActiveTransaction;
133
135
  private requireSelectedSession;
134
136
  private validateActorId;
137
+ private validateActorName;
135
138
  private throwMembershipDenied;
136
139
  private resolveConnectionSource;
137
140
  private resolveCredential;
@@ -411,6 +411,7 @@ export class StateQL {
411
411
  if (!this.store.isSessionMember(session.id, this.actorId)) {
412
412
  throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
413
413
  }
414
+ const actor = this.store.getActor(session.id, this.actorId);
414
415
  const connection = this.store.activeConnection(session);
415
416
  const transaction = session.active_transaction_id
416
417
  ? this.store.getTransaction(session.active_transaction_id)
@@ -433,6 +434,7 @@ export class StateQL {
433
434
  status: session.status,
434
435
  },
435
436
  actor_id: this.actorId,
437
+ actor_name: actor.actor_name,
436
438
  connection: connection
437
439
  ? {
438
440
  connection_id: connection.id,
@@ -479,11 +481,13 @@ export class StateQL {
479
481
  const transaction = session.active_transaction_id
480
482
  ? this.store.getTransaction(session.active_transaction_id)
481
483
  : undefined;
484
+ const actor = this.store.getActor(session.id, this.actorId);
482
485
  return {
483
486
  data: {
484
487
  session_id: session.id,
485
488
  session_name: session.name,
486
489
  actor_id: this.actorId,
490
+ actor_name: actor.actor_name,
487
491
  connection: connection
488
492
  ? {
489
493
  connection_id: connection.id,
@@ -547,6 +551,42 @@ export class StateQL {
547
551
  };
548
552
  });
549
553
  }
554
+ async showActor() {
555
+ return this.run("actor.show", async (current) => {
556
+ const actor = this.store.getActor(current.id, this.actorId);
557
+ return {
558
+ data: {
559
+ actor_id: actor.actor_id,
560
+ actor_name: actor.actor_name,
561
+ attached_at: actor.attached_at,
562
+ },
563
+ };
564
+ });
565
+ }
566
+ async setActorName(name) {
567
+ return this.run("actor.set-name", async (current) => {
568
+ const actorName = this.validateActorName(name);
569
+ const existing = this.store.getActor(current.id, this.actorId);
570
+ if (existing.actor_name === actorName) {
571
+ return {
572
+ data: {
573
+ actor_id: existing.actor_id,
574
+ actor_name: existing.actor_name,
575
+ attached_at: existing.attached_at,
576
+ },
577
+ };
578
+ }
579
+ const actor = this.store.setActorName(current.id, this.actorId, actorName);
580
+ return {
581
+ data: {
582
+ actor_id: actor.actor_id,
583
+ actor_name: actor.actor_name,
584
+ attached_at: actor.attached_at,
585
+ },
586
+ executed: true,
587
+ };
588
+ }, undefined, actorNameHistoryTarget(name));
589
+ }
550
590
  async listActors(session) {
551
591
  return this.run("actor.list", async (current) => {
552
592
  this.requireSelectedSession(current, session);
@@ -555,6 +595,7 @@ export class StateQL {
555
595
  session_id: current.id,
556
596
  actors: this.store.listActors(current.id).map((member) => ({
557
597
  actor_id: member.actor_id,
598
+ actor_name: member.actor_name,
558
599
  attached_at: member.attached_at,
559
600
  })),
560
601
  },
@@ -1943,6 +1984,7 @@ export class StateQL {
1943
1984
  generated_aliases: true,
1944
1985
  multi_row_table_plans: true,
1945
1986
  history_classification: true,
1987
+ actor_display_names: true,
1946
1988
  },
1947
1989
  driver_features: {
1948
1990
  mongodb: {
@@ -1995,6 +2037,10 @@ export class StateQL {
1995
2037
  return this.disconnect();
1996
2038
  case "status":
1997
2039
  return this.status();
2040
+ case "actor.show":
2041
+ return this.showActor();
2042
+ case "actor.set-name":
2043
+ return this.setActorName(batchString(command.name, "name"));
1998
2044
  case "profile.add":
1999
2045
  return this.addProfile(batchString(command.name, "name"), command.target, {
2000
2046
  readOnly: command.read_only ?? true,
@@ -2817,6 +2863,21 @@ export class StateQL {
2817
2863
  throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
2818
2864
  }
2819
2865
  }
2866
+ validateActorName(value) {
2867
+ if (typeof value !== "string") {
2868
+ throw new StateQLError("INVALID_COMMAND", "Actor name must be a string.");
2869
+ }
2870
+ const name = value.trim();
2871
+ if (!name)
2872
+ throw new StateQLError("INVALID_COMMAND", "Actor name is required.");
2873
+ if ([...name].length > 80) {
2874
+ throw new StateQLError("INVALID_COMMAND", "Actor name cannot exceed 80 characters.");
2875
+ }
2876
+ if (/[\u0000-\u001f\u007f]/u.test(name)) {
2877
+ throw new StateQLError("INVALID_COMMAND", "Actor name cannot contain control characters.");
2878
+ }
2879
+ return name;
2880
+ }
2820
2881
  throwMembershipDenied(session) {
2821
2882
  throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
2822
2883
  }
@@ -2984,6 +3045,7 @@ export class StateQL {
2984
3045
  },
2985
3046
  };
2986
3047
  }
3048
+ const actorName = this.store.getActor(session.id, this.actorId).actor_name;
2987
3049
  try {
2988
3050
  const result = await action(session);
2989
3051
  const responseSession = result.session ?? session;
@@ -2991,6 +3053,7 @@ export class StateQL {
2991
3053
  const history = this.store.addHistory({
2992
3054
  sessionId: session.id,
2993
3055
  actorId: this.actorId,
3056
+ actorName,
2994
3057
  origin,
2995
3058
  category,
2996
3059
  internal,
@@ -3025,6 +3088,7 @@ export class StateQL {
3025
3088
  const history = this.store.addHistory({
3026
3089
  sessionId: session.id,
3027
3090
  actorId: this.actorId,
3091
+ actorName,
3028
3092
  origin,
3029
3093
  category,
3030
3094
  internal,
@@ -3057,6 +3121,7 @@ function historyEntry(item) {
3057
3121
  timestamp: item.timestamp,
3058
3122
  session_id: item.session_id,
3059
3123
  actor_id: item.actor_id,
3124
+ actor_name: item.actor_name,
3060
3125
  origin: item.origin,
3061
3126
  category: item.category,
3062
3127
  internal: Boolean(item.internal),
@@ -3070,6 +3135,12 @@ function historyEntry(item) {
3070
3135
  error_code: item.error_code,
3071
3136
  };
3072
3137
  }
3138
+ function actorNameHistoryTarget(value) {
3139
+ if (typeof value !== "string" || /[\u0000-\u001f\u007f]/u.test(value))
3140
+ return undefined;
3141
+ const name = value.trim();
3142
+ return name ? [...name].slice(0, 80).join("") : undefined;
3143
+ }
3073
3144
  const COMMAND_ORIGINS = new Set([
3074
3145
  "legacy",
3075
3146
  "user",
@@ -104,6 +104,7 @@ export interface HistoryRecord {
104
104
  timestamp: string;
105
105
  session_id: string;
106
106
  actor_id: string;
107
+ actor_name: string;
107
108
  origin: CommandOrigin;
108
109
  category: HistoryCategory;
109
110
  internal: number;
@@ -119,6 +120,7 @@ export interface HistoryRecord {
119
120
  export interface SessionMemberRecord {
120
121
  session_id: string;
121
122
  actor_id: string;
123
+ actor_name: string;
122
124
  attached_at: string;
123
125
  }
124
126
  export declare class StateStore {
@@ -137,6 +139,8 @@ export declare class StateStore {
137
139
  isSessionMember(sessionId: string, actorId: string): boolean;
138
140
  linkActor(sessionId: string, requestingActorId: string, actorId: string): "linked" | "already_linked" | "actor_conflict" | "denied";
139
141
  unlinkActor(sessionId: string, requestingActorId: string, actorId: string): "unlinked" | "not_linked" | "owns_transaction" | "denied";
142
+ getActor(sessionId: string, actorId: string): SessionMemberRecord | undefined;
143
+ setActorName(sessionId: string, actorId: string, actorName: string): SessionMemberRecord | undefined;
140
144
  listActors(sessionId: string): SessionMemberRecord[];
141
145
  resolveActor(actorId: string): SessionRecord | undefined;
142
146
  getSession(idOrName: string): SessionRecord | undefined;
@@ -299,6 +303,7 @@ export declare class StateStore {
299
303
  addHistory(input: {
300
304
  sessionId: string;
301
305
  actorId: string;
306
+ actorName?: string;
302
307
  origin?: CommandOrigin;
303
308
  category?: HistoryCategory;
304
309
  internal?: boolean;
package/dist/src/store.js CHANGED
@@ -113,16 +113,16 @@ export class StateStore {
113
113
  }
114
114
  if (created) {
115
115
  this.db
116
- .prepare(`INSERT INTO session_members(session_id, actor_id, attached_at)
117
- VALUES (?, ?, ?)`)
118
- .run(row.id, actorId, timestamp);
116
+ .prepare(`INSERT INTO session_members(session_id, actor_id, actor_name, attached_at)
117
+ VALUES (?, ?, ?, ?)`)
118
+ .run(row.id, actorId, actorId, timestamp);
119
119
  }
120
120
  else if (ensureLegacyMembership) {
121
121
  this.db
122
122
  .prepare(`INSERT OR IGNORE INTO session_members
123
- (session_id, actor_id, attached_at)
124
- VALUES (?, ?, ?)`)
125
- .run(row.id, actorId, timestamp);
123
+ (session_id, actor_id, actor_name, attached_at)
124
+ VALUES (?, ?, ?, ?)`)
125
+ .run(row.id, actorId, actorId, timestamp);
126
126
  }
127
127
  this.db.exec("COMMIT");
128
128
  return this.getSession(row.id);
@@ -167,9 +167,9 @@ export class StateStore {
167
167
  if (this.isSessionMember(row.id, identity))
168
168
  continue;
169
169
  this.db
170
- .prepare(`INSERT INTO session_members(session_id, actor_id, attached_at)
171
- VALUES (?, ?, ?)`)
172
- .run(row.id, identity, timestamp);
170
+ .prepare(`INSERT INTO session_members(session_id, actor_id, actor_name, attached_at)
171
+ VALUES (?, ?, ?, ?)`)
172
+ .run(row.id, identity, identity, timestamp);
173
173
  }
174
174
  const session = this.getSessionByName(name);
175
175
  if (!session)
@@ -204,9 +204,9 @@ export class StateStore {
204
204
  return existing.id === sessionId ? "already_linked" : "actor_conflict";
205
205
  }
206
206
  this.db
207
- .prepare(`INSERT INTO session_members(session_id, actor_id, attached_at)
208
- VALUES (?, ?, ?)`)
209
- .run(sessionId, actorId, this.now().toISOString());
207
+ .prepare(`INSERT INTO session_members(session_id, actor_id, actor_name, attached_at)
208
+ VALUES (?, ?, ?, ?)`)
209
+ .run(sessionId, actorId, actorId, this.now().toISOString());
210
210
  this.db.exec("COMMIT");
211
211
  return "linked";
212
212
  }
@@ -243,6 +243,19 @@ export class StateStore {
243
243
  throw error;
244
244
  }
245
245
  }
246
+ getActor(sessionId, actorId) {
247
+ return this.db
248
+ .prepare(`SELECT * FROM session_members
249
+ WHERE session_id = ? AND actor_id = ?`)
250
+ .get(sessionId, actorId);
251
+ }
252
+ setActorName(sessionId, actorId, actorName) {
253
+ return this.db
254
+ .prepare(`UPDATE session_members SET actor_name = ?
255
+ WHERE session_id = ? AND actor_id = ?
256
+ RETURNING *`)
257
+ .get(actorName, sessionId, actorId);
258
+ }
246
259
  listActors(sessionId) {
247
260
  return this.db
248
261
  .prepare(`SELECT * FROM session_members
@@ -943,10 +956,10 @@ export class StateStore {
943
956
  const insert = (id) => {
944
957
  this.db
945
958
  .prepare(`INSERT INTO history
946
- (id, timestamp, session_id, actor_id, origin, category, internal, command, sql, target, handle,
959
+ (id, timestamp, session_id, actor_id, actor_name, origin, category, internal, command, sql, target, handle,
947
960
  executed, cached, success, error_code)
948
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
949
- .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);
961
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
962
+ .run(id, this.now().toISOString(), input.sessionId, input.actorId, input.actorName ?? this.getActor(input.sessionId, input.actorId)?.actor_name ?? 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);
950
963
  };
951
964
  const id = input.id ?? this.insertWithRandomId("cmd", "history", insert);
952
965
  if (input.id !== undefined)
@@ -1,4 +1,4 @@
1
- import { BSON } from "mongodb";
1
+ import { BSON } from "bson";
2
2
  import { StateQLError } from "./errors.js";
3
3
  export function quoteIdentifier(name, driver) {
4
4
  if (!name || name.length > 500 || name.includes("\0"))
@@ -83,6 +83,7 @@ export interface HistoryEntry {
83
83
  timestamp: string;
84
84
  session_id: string;
85
85
  actor_id: string;
86
+ actor_name: string;
86
87
  origin: CommandOrigin;
87
88
  category: HistoryCategory;
88
89
  internal: boolean;
@@ -107,6 +108,7 @@ export interface StateQLSnapshot {
107
108
  status: string;
108
109
  };
109
110
  actor_id: string;
111
+ actor_name: string;
110
112
  connection: {
111
113
  connection_id: string;
112
114
  /** Generated display identity; optional for older snapshot producers. */
@@ -345,7 +347,7 @@ export interface MongoPlanOptions extends ExecutionOptions {
345
347
  allowUnbounded?: boolean;
346
348
  allowDestructive?: boolean;
347
349
  }
348
- 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";
350
+ export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "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";
349
351
  export interface BatchCommand {
350
352
  command: BatchCommandName;
351
353
  target?: string;
@@ -433,6 +435,7 @@ export interface StatusData {
433
435
  session_id: string;
434
436
  session_name: string;
435
437
  actor_id: string;
438
+ actor_name: string;
436
439
  connection: StatusConnectionData | null;
437
440
  transaction: TransactionReferenceData | null;
438
441
  state_version: string | null;
@@ -449,6 +452,7 @@ export interface ActorUnlinkData {
449
452
  }
450
453
  export interface ActorData {
451
454
  actor_id: string;
455
+ actor_name: string;
452
456
  attached_at: string;
453
457
  }
454
458
  export interface ActorsData {
package/docs/databases.md CHANGED
@@ -40,9 +40,7 @@ transaction-control SQL is unsupported: use
40
40
  [staged transactions](usage.md#transactions), not `BEGIN` or `COMMIT` statements.
41
41
  MongoDB and Redis use separate native command APIs.
42
42
 
43
- Unrecognized or parser-unsupported forms remain blocked. The
44
- [SQL command roadmap](../SQL_COMMAND_ROADMAP.md) describes future categories,
45
- not permission to execute them.
43
+ Unrecognized or parser-unsupported forms remain blocked.
46
44
 
47
45
  ## Dialect upserts
48
46
 
package/docs/library.md CHANGED
@@ -130,6 +130,14 @@ available through `linkActor(session, actorId)`, `unlinkActor(session, actorId)`
130
130
  user confirmation before changing membership or the shared connection; a host
131
131
  calling `forWorkspace` is responsible for authorizing that workspace access.
132
132
 
133
+ An actor can inspect itself with `showActor()` and set its own contextual display
134
+ name with `setActorName(name)`. The display name is trimmed, limited to 80
135
+ characters, and rejects control characters. It never replaces `actor_id` in
136
+ membership, authorization, plan ownership, or transaction ownership. History
137
+ snapshots the display name at command start, so later renames do not alter prior
138
+ audit entries; the corresponding batch commands are `actor.show` and
139
+ `actor.set-name` (using the `name` field).
140
+
133
141
  ## Credential resolution
134
142
 
135
143
  Library integrations can resolve environment-variable names, opaque full-URL
package/docs/usage.md CHANGED
@@ -100,6 +100,8 @@ stql connect --credential-ref REF [--name NAME] [--read-only|--read-write]
100
100
  stql connect --profile NAME
101
101
  stql disconnect
102
102
  stql status
103
+ stql actor show
104
+ stql actor set-name <display-name>
103
105
  stql profile add|update NAME [TARGET | --env ENV | --credential-ref REF]
104
106
  [--read-only|--read-write]
105
107
  stql profile list|show|remove
@@ -227,6 +229,17 @@ transactions remain owned by the actor that created them.
227
229
  Callers that omit `actor` keep the legacy behavior where the actor ID is the
228
230
  session name.
229
231
 
232
+ Actor IDs are immutable authorization and ownership identities. Each actor also
233
+ has a mutable display name, initially equal to its ID. The selected actor may
234
+ change only its own display name with `stql actor set-name <display-name>`;
235
+ names are trimmed, limited to 80 characters, and cannot contain control
236
+ characters. Display names are contextual metadata and must not be used for
237
+ authorization.
238
+
239
+ History records both the stable `actor_id` and the `actor_name` in effect when
240
+ the command began. Renaming therefore does not rewrite earlier attribution; the
241
+ rename is itself recorded as an `actor.set-name` management command.
242
+
230
243
  ### Result lifetime and limits
231
244
 
232
245
  Result rows are materialized locally for durable access. By default, read cache
@@ -350,8 +363,9 @@ stql batch commands.json
350
363
  ```
351
364
 
352
365
  Batch fields use snake case. Supported command names match CLI paths, such as
353
- `filter`, `transaction.begin`, `session.summary`, `alias.set`, `plan`, and
354
- `apply`. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
366
+ `actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
367
+ `alias.set`, `plan`, and `apply`. `actor.set-name` takes the display name in the
368
+ `name` field. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
355
369
  batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
356
370
  in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
357
371
  apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.13.2",
3
+ "version": "0.13.3",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -22,12 +22,11 @@
22
22
  "dist/src",
23
23
  "README.md",
24
24
  "docs",
25
- "SQL_COMMAND_ROADMAP.md",
26
25
  "LICENSE"
27
26
  ],
28
27
  "scripts": {
29
28
  "build": "tsc -p tsconfig.json",
30
- "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",
29
+ "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/import.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",
31
30
  "release": "npm version",
32
31
  "version": "npm install",
33
32
  "prepack": "npm test"
@@ -48,6 +47,7 @@
48
47
  },
49
48
  "dependencies": {
50
49
  "@redis/client": "^5.12.1",
50
+ "bson": "^6.10.4",
51
51
  "mongodb": "^6.21.0",
52
52
  "mysql2": "^3.23.1",
53
53
  "node-sql-parser": "^5.4.0",