@procedures/sqlite 0.3.0 → 0.5.0

package/src/module.ts

@@ -3,12 +3,14 @@
  *
  * Procedure Registration for SQLite
  *
- * Registers database and logging procedures with the client system: db.query, db.execute,
- * db.tables, db.schema, db.transaction, db.migrate, db.backup, logs.store and logs.query.
+ * The module has the database and logging procedures: sqlite.query, sqlite.execute,
+ * sqlite.tables, sqlite.schema, sqlite.transaction, sqlite.migrate, sqlite.backup, logs.store
+ * and logs.query. The old names db.* stay for one release as deprecated aliases (refer to
+ * `deprecatedDbAlias`).
  * This file is referenced by package.json's client.procedures field.
  */
 
-import { createProcedure, zodAdapter, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import { createProcedure, zodAdapter, defineModule, type AnyProcedure, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
 import { z } from "zod";
 import {
   withConnection,
@@ -64,10 +66,11 @@ import {
 // Real schemas (roadmap 2.1): the input is validated before the handler, and the MCP tool list
 // and the help of mark describe each field. zodAdapter<T> checks each schema against its type.
 
+// The description is the same on each computer: it does not show the home folder of this one
 const dbPathField = z
   .string()
   .optional()
-  .describe(`The SQLite database file (default: ${DEFAULT_DB_PATH}). A query does not make a missing file.`);
+  .describe("The SQLite database file (default: the CLI log database, ~/logs/cli/cli.db). A query does not make a missing file.");
 const paramsField = z
   .array(z.unknown())
   .optional()
@@ -190,11 +193,11 @@ async function ensureLogsTable(dbPath: string): Promise<void> {
 }
 
 // =============================================================================
-// db.query Procedure
+// sqlite.query Procedure
 // =============================================================================
 
-const dbQueryProcedure = createProcedure()
-  .path(["db", "query"])
+const sqliteQueryProcedure = createProcedure()
+  .path(["sqlite", "query"])
   .input(dbQueryInputSchema)
   .output(dbQueryOutputSchema)
   .meta({
@@ -219,11 +222,11 @@ const dbQueryProcedure = createProcedure()
   .build();
 
 // =============================================================================
-// db.execute Procedure
+// sqlite.execute Procedure
 // =============================================================================
 
-const dbExecuteProcedure = createProcedure()
-  .path(["db", "execute"])
+const sqliteExecuteProcedure = createProcedure()
+  .path(["sqlite", "execute"])
   .input(dbExecuteInputSchema)
   .output(dbExecuteOutputSchema)
   .meta({
@@ -412,11 +415,11 @@ const logsQueryProcedure = createProcedure()
   .build();
 
 // =============================================================================
-// db.tables, db.schema, db.transaction, db.migrate and db.backup (roadmap R44)
+// sqlite.tables, sqlite.schema, sqlite.transaction, sqlite.migrate and sqlite.backup (roadmap R44)
 // =============================================================================
 
-const dbTablesProcedure = createProcedure()
-  .path(["db", "tables"])
+const sqliteTablesProcedure = createProcedure()
+  .path(["sqlite", "tables"])
   .input(zodAdapter<DbTablesInput>(DbTablesInputSchema))
   .output(zodAdapter<DbTablesOutput>(DbTablesOutputSchema))
   .meta({
@@ -429,8 +432,8 @@ const dbTablesProcedure = createProcedure()
   .handler(async (input: DbTablesInput): Promise<DbTablesOutput> => dbTables(input))
   .build();
 
-const dbSchemaProcedure = createProcedure()
-  .path(["db", "schema"])
+const sqliteSchemaProcedure = createProcedure()
+  .path(["sqlite", "schema"])
   .input(zodAdapter<DbSchemaInput>(DbSchemaInputSchema))
   .output(zodAdapter<DbSchemaOutput>(DbSchemaOutputSchema))
   .meta({
@@ -443,8 +446,8 @@ const dbSchemaProcedure = createProcedure()
   .handler(async (input: DbSchemaInput): Promise<DbSchemaOutput> => dbSchema(input))
   .build();
 
-const dbTransactionProcedure = createProcedure()
-  .path(["db", "transaction"])
+const sqliteTransactionProcedure = createProcedure()
+  .path(["sqlite", "transaction"])
   .input(zodAdapter<DbTransactionInput>(DbTransactionInputSchema))
   .output(zodAdapter<DbTransactionOutput>(DbTransactionOutputSchema))
   .meta({
@@ -458,8 +461,8 @@ const dbTransactionProcedure = createProcedure()
   .handler(async (input: DbTransactionInput): Promise<DbTransactionOutput> => dbTransaction(input))
   .build();
 
-const dbMigrateProcedure = createProcedure()
-  .path(["db", "migrate"])
+const sqliteMigrateProcedure = createProcedure()
+  .path(["sqlite", "migrate"])
   .input(zodAdapter<DbMigrateInput>(DbMigrateInputSchema))
   .output(zodAdapter<DbMigrateOutput>(DbMigrateOutputSchema))
   .meta({
@@ -473,8 +476,8 @@ const dbMigrateProcedure = createProcedure()
   .handler(async (input: DbMigrateInput): Promise<DbMigrateOutput> => dbMigrate(input))
   .build();
 
-const dbBackupProcedure = createProcedure()
-  .path(["db", "backup"])
+const sqliteBackupProcedure = createProcedure()
+  .path(["sqlite", "backup"])
   .input(zodAdapter<DbBackupInput>(DbBackupInputSchema))
   .output(zodAdapter<DbBackupOutput>(DbBackupOutputSchema))
   .meta({
@@ -488,6 +491,44 @@ const dbBackupProcedure = createProcedure()
   .handler(async (input: DbBackupInput): Promise<DbBackupOutput> => dbBackup(input))
   .build();
 
+// =============================================================================
+// The deprecated db.* aliases (one release)
+// =============================================================================
+
+/** The procedures of the `sqlite` namespace. Each one has a deprecated alias in `db`. */
+const sqliteProcedures: readonly AnyProcedure[] = [
+  sqliteQueryProcedure,
+  sqliteExecuteProcedure,
+  sqliteTablesProcedure,
+  sqliteSchemaProcedure,
+  sqliteTransactionProcedure,
+  sqliteMigrateProcedure,
+  sqliteBackupProcedure,
+];
+
+/**
+ * This function gives the deprecated alias `db.<name>` of the procedure `sqlite.<name>`. The alias
+ * has the same schemas, handler and effects. Its description names the new procedure. The aliases
+ * go away in the next release. The MCP server does not expose them (`bundle-mcp`).
+ */
+export function deprecatedDbAlias(procedure: AnyProcedure): AnyProcedure {
+  const name = procedure.path.slice(1).join(".");
+  const description = typeof procedure.metadata.description === "string" ? ` ${procedure.metadata.description}` : "";
+  return {
+    ...procedure,
+    path: ["db", ...procedure.path.slice(1)],
+    metadata: {
+      ...procedure.metadata,
+      description: `Deprecated: use sqlite.${name}.${description}`,
+      deprecated: true,
+      deprecationMessage: `Use sqlite.${name}. The alias db.${name} goes away in the next release.`,
+    },
+  };
+}
+
+/** The deprecated aliases `db.query`, `db.execute`, `db.tables`, `db.schema`, `db.transaction`, `db.migrate` and `db.backup`. */
+export const dbAliasProcedures: readonly AnyProcedure[] = sqliteProcedures.map(deprecatedDbAlias);
+
 // =============================================================================
 // Registration
 // =============================================================================
@@ -497,15 +538,11 @@ const dbBackupProcedure = createProcedure()
  * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
  */
 export const sqliteModule: ProcedureModule = defineModule("@procedures/sqlite", [
-    dbQueryProcedure,
-    dbExecuteProcedure,
+    ...sqliteProcedures,
     logsStoreProcedure,
     logsQueryProcedure,
-    dbTablesProcedure,
-    dbSchemaProcedure,
-    dbTransactionProcedure,
-    dbMigrateProcedure,
-    dbBackupProcedure,
+    // The old names, for one release
+    ...dbAliasProcedures,
   ]);
 
 export default sqliteModule;

package/src/procedures/db/backup.ts

@@ -1,5 +1,5 @@
 /**
- * db.backup procedure (roadmap R44)
+ * sqlite.backup procedure (roadmap R44)
  *
  * A copy of a database in a new file. The package runs SQLite in WebAssembly (sql.js): the
  * database is in the memory of the module, and `VACUUM INTO` and the backup API write into the
@@ -30,13 +30,13 @@ function fileKey(path: string): string {
  */
 export async function dbBackup(input: DbBackupInput): Promise<DbBackupOutput> {
   const source = databasePath(input.dbPath);
-  requireDatabaseFile("db.backup", source);
+  requireDatabaseFile("sqlite.backup", source);
   const target = resolve(input.to);
   if (source !== ":memory:" && fileKey(source) === fileKey(target)) {
-    throw new Error("db.backup: the copy cannot be the database file itself");
+    throw new Error("sqlite.backup: the copy cannot be the database file itself");
   }
   if (existsSync(target)) {
-    const error = new Error(`db.backup: the file exists already: ${target}. The procedure does not replace a file.`) as NodeJS.ErrnoException;
+    const error = new Error(`sqlite.backup: the file exists already: ${target}. The procedure does not replace a file.`) as NodeJS.ErrnoException;
     error.code = "EEXIST";
     throw error;
   }
@@ -51,8 +51,8 @@ export async function dbBackup(input: DbBackupInput): Promise<DbBackupOutput> {
     }
     const check = await withConnection({ dbPath: temporary }, (db) => query<{ integrity_check: string }>(db, "PRAGMA integrity_check").rows);
     const verdict = check.map((row) => row.integrity_check).join("; ");
-    if (verdict !== "ok") throw new Error(`db.backup: the copy is not valid: ${verdict}`);
-    if (existsSync(target)) throw new Error(`db.backup: the file exists already: ${target}. The procedure does not replace a file.`);
+    if (verdict !== "ok") throw new Error(`sqlite.backup: the copy is not valid: ${verdict}`);
+    if (existsSync(target)) throw new Error(`sqlite.backup: the file exists already: ${target}. The procedure does not replace a file.`);
     await rename(temporary, target);
   } catch (error) {
     await unlink(temporary).catch(() => undefined);

package/src/procedures/db/migrate.ts

@@ -1,5 +1,5 @@
 /**
- * db.migrate procedure (roadmap R44)
+ * sqlite.migrate procedure (roadmap R44)
  *
  * The procedure applies the numbered migrations that the database does not have, in the order
  * of their numbers. The migrations come from a folder (files named `<number>_<name>.sql`) or
@@ -44,7 +44,7 @@ export async function migrationsOfFolder(folder: string): Promise<DbMigration[]>
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".sql")) continue;
     const match = MIGRATION_FILE.exec(entry.name);
-    if (!match) throw new Error(`db.migrate: the file ${entry.name} has no number: name it <number>_<name>.sql`);
+    if (!match) throw new Error(`sqlite.migrate: the file ${entry.name} has no number: name it <number>_<name>.sql`);
     migrations.push({ version: Number(match[1]), name: match[2]!, sql: await readFile(join(folder, entry.name), "utf8") });
   }
   return migrations;
@@ -55,9 +55,9 @@ function ordered(migrations: DbMigration[]): Migration[] {
   const byVersion = new Map<number, Migration>();
   for (const migration of migrations) {
     if (!Number.isSafeInteger(migration.version) || migration.version < 1) {
-      throw new Error(`db.migrate: the version ${migration.version} is not a whole number of 1 or more`);
+      throw new Error(`sqlite.migrate: the version ${migration.version} is not a whole number of 1 or more`);
     }
-    if (byVersion.has(migration.version)) throw new Error(`db.migrate: two migrations have the version ${migration.version}`);
+    if (byVersion.has(migration.version)) throw new Error(`sqlite.migrate: two migrations have the version ${migration.version}`);
     const name = migration.name ?? `migration ${migration.version}`;
     byVersion.set(migration.version, { version: migration.version, name, sql: migration.sql, checksum: checksum(migration.sql) });
   }
@@ -69,10 +69,10 @@ function ordered(migrations: DbMigration[]): Migration[] {
  */
 export async function dbMigrate(input: DbMigrateInput): Promise<DbMigrateOutput> {
   if ((input.folder === undefined) === (input.migrations === undefined)) {
-    throw new Error("db.migrate: give exactly one of folder or migrations");
+    throw new Error("sqlite.migrate: give exactly one of folder or migrations");
   }
   const table = input.table ?? DEFAULT_MIGRATION_TABLE;
-  if (!MIGRATION_TABLE_PATTERN.test(table)) throw new Error(`db.migrate: the table name ${JSON.stringify(table)} is not valid`);
+  if (!MIGRATION_TABLE_PATTERN.test(table)) throw new Error(`sqlite.migrate: the table name ${JSON.stringify(table)} is not valid`);
   const migrations = ordered(input.folder !== undefined ? await migrationsOfFolder(input.folder) : input.migrations!);
 
   return withConnection({ dbPath: databasePath(input.dbPath) }, (db) => {
@@ -87,7 +87,7 @@ export async function dbMigrate(input: DbMigrateInput): Promise<DbMigrateOutput>
       for (const migration of migrations) {
         const known = applied.get(migration.version);
         if (known !== undefined && known !== migration.checksum) {
-          throw new Error(`db.migrate: the migration ${migration.version} (${migration.name}) changed after it was applied: its sha256 is different`);
+          throw new Error(`sqlite.migrate: the migration ${migration.version} (${migration.name}) changed after it was applied: its sha256 is different`);
         }
       }
       const pending = migrations.filter((migration) => !applied.has(migration.version));
@@ -97,7 +97,7 @@ export async function dbMigrate(input: DbMigrateInput): Promise<DbMigrateOutput>
           runStatements(db, migration.sql, [], label);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          throw new Error(message.startsWith(label) ? `db.migrate: ${message}` : `db.migrate: ${label} failed: ${message}`);
+          throw new Error(message.startsWith(label) ? `sqlite.migrate: ${message}` : `sqlite.migrate: ${label} failed: ${message}`);
         }
         db.run(`INSERT INTO "${table}" (version, name, checksum) VALUES (?, ?, ?)`, [migration.version, migration.name, migration.checksum]);
       }

package/src/procedures/db/schema.ts

@@ -1,5 +1,5 @@
 /**
- * db.schema procedure (roadmap R44)
+ * sqlite.schema procedure (roadmap R44)
  *
  * The columns, the indexes and the foreign keys of a table (or the columns of a view). The
  * procedure reads them with the table-valued PRAGMA functions, so the name of the table is a
@@ -38,7 +38,7 @@ interface ForeignKeyRow {
  */
 export async function dbSchema(input: DbSchemaInput): Promise<DbSchemaOutput> {
   const path = databasePath(input.dbPath);
-  requireDatabaseFile("db.schema", path);
+  requireDatabaseFile("sqlite.schema", path);
   return withConnection({ dbPath: path }, (db) => {
     db.run("PRAGMA query_only = 1");
     const found = query<{ type: "table" | "view"; sql: string | null }>(
@@ -46,7 +46,7 @@ export async function dbSchema(input: DbSchemaInput): Promise<DbSchemaOutput> {
       "SELECT type, sql FROM sqlite_master WHERE name = ? AND type IN ('table', 'view')",
       [input.table],
     ).rows[0];
-    if (!found) throw new Error(`db.schema: no table or view named ${JSON.stringify(input.table)}`);
+    if (!found) throw new Error(`sqlite.schema: no table or view named ${JSON.stringify(input.table)}`);
 
     const columns: DbColumnInfo[] = query<ColumnRow>(db, "SELECT name, type, \"notnull\", dflt_value, pk FROM pragma_table_info(?) ORDER BY cid", [input.table]).rows.map(
       (row) => ({ name: row.name, type: row.type, notNull: row.notnull === 1, defaultValue: row.dflt_value, primaryKey: row.pk }),

package/src/procedures/db/shared.ts

@@ -1,5 +1,5 @@
 /**
- * The helpers of the db.* procedures of roadmap R44.
+ * The helpers of the sqlite.* procedures of roadmap R44.
  */
 
 import { existsSync } from "node:fs";

package/src/procedures/db/tables.ts

@@ -1,5 +1,5 @@
 /**
- * db.tables procedure (roadmap R44)
+ * sqlite.tables procedure (roadmap R44)
  *
  * The tables and the views of a database, without the internal `sqlite_` tables. The connection
  * is read only (PRAGMA query_only), and a missing file is an error: it does not make one.
@@ -14,7 +14,7 @@ import { databasePath, requireDatabaseFile } from "./shared.js";
  */
 export async function dbTables(input: DbTablesInput): Promise<DbTablesOutput> {
   const path = databasePath(input.dbPath);
-  requireDatabaseFile("db.tables", path);
+  requireDatabaseFile("sqlite.tables", path);
   const types = input.views === false ? "('table')" : "('table', 'view')";
   return withConnection({ dbPath: path }, (db) => {
     db.run("PRAGMA query_only = 1");

package/src/procedures/db/transaction.ts

@@ -1,5 +1,5 @@
 /**
- * db.transaction procedure (roadmap R44)
+ * sqlite.transaction procedure (roadmap R44)
  *
  * The statements of the input run in order in one transaction. When one fails, the procedure
  * rolls back the transaction and does not save the file: the database stays as it was. A
@@ -20,7 +20,7 @@ export async function dbTransaction(input: DbTransactionInput): Promise<DbTransa
     const results: DbStatementResult[] = [];
     try {
       input.statements.forEach((statement, index) => {
-        const label = `db.transaction: statements[${index}]`;
+        const label = `sqlite.transaction: statements[${index}]`;
         try {
           results.push(runStatements(db, statement.sql, statement.params ?? [], label));
         } catch (error) {