@aigne/afs-sqlite 1.0.1-beta

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [1.0.1-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-sqlite-v1.0.0...afs-sqlite-v1.0.1-beta) (2026-01-15)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.69-beta.23
+
+## 1.0.0 (2026-01-15)
+
+
+### Features
+
+* **afs:** add generic AFS adapter for sqlite databases ([#908](https://github.com/AIGNE-io/aigne-framework/issues/908)) ([b9b5a8f](https://github.com/AIGNE-io/aigne-framework/commit/b9b5a8fc2680e8e3ae7f28dd720b0089520981b9))
+
+
+### Bug Fixes
+
+* update @aigne/afs-sqlite release config ([ef0f254](https://github.com/AIGNE-io/aigne-framework/commit/ef0f2547920e0e95545c57c7dd55ff059b5a2e7a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @aigne/test-utils bumped to 0.5.69-beta.22

package/LICENSE.md

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,277 @@
+# @aigne/afs-sqlite
+
+**@aigne/afs-sqlite** is an AFS module that exposes SQLite databases as virtual file system nodes with full CRUD support, schema introspection, FTS5 search, and virtual paths.
+
+## Overview
+
+This module allows AI agents to interact with SQLite databases through the AFS interface. It automatically introspects database schemas and exposes tables, rows, and columns as navigable paths.
+
+## Features
+
+- **Schema Introspection**: Automatically discovers tables, columns, primary keys, foreign keys, and indexes
+- **CRUD Operations**: Full create, read, update, delete support for database rows
+- **FTS5 Search**: Full-text search support with SQLite FTS5
+- **Virtual Paths**: Access row attributes (`@attr`), metadata (`@meta`), schema (`@schema`), and actions (`@actions`)
+- **Built-in Actions**: validate, duplicate, refresh, export, count
+- **Custom Actions**: Register custom actions for domain-specific operations
+- **Readonly Mode**: Optional readonly access mode for safety
+
+## Installation
+
+```bash
+npm install @aigne/afs-sqlite
+# or
+yarn add @aigne/afs-sqlite
+# or
+pnpm add @aigne/afs-sqlite
+```
+
+## Quick Start
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { SQLiteAFS } from "@aigne/afs-sqlite";
+
+// Create AFS instance
+const afs = new AFS();
+
+// Mount SQLite module
+afs.mount(new SQLiteAFS({
+  url: "file:./database.sqlite3",
+  accessMode: "readwrite"
+}));
+
+// List all tables
+const tables = await afs.list("/modules/sqlite-afs");
+
+// List rows in a table
+const users = await afs.list("/modules/sqlite-afs/users");
+
+// Read a specific row
+const user = await afs.read("/modules/sqlite-afs/users/1");
+
+// Create a new row
+await afs.write("/modules/sqlite-afs/users", {
+  content: { name: "John", email: "john@example.com" }
+});
+
+// Update an existing row
+await afs.write("/modules/sqlite-afs/users/1", {
+  content: { name: "John Doe" }
+});
+
+// Delete a row
+await afs.delete("/modules/sqlite-afs/users/1");
+
+// Search for content
+const results = await afs.search("/modules/sqlite-afs", "john");
+```
+
+## Configuration
+
+```typescript
+interface SQLiteAFSOptions {
+  // Database connection URL (required)
+  url: string;
+
+  // Module name (default: "sqlite-afs")
+  name?: string;
+
+  // Module description
+  description?: string;
+
+  // Access mode: "readonly" or "readwrite" (default: "readwrite")
+  accessMode?: "readonly" | "readwrite";
+
+  // Enable WAL mode (default: true)
+  wal?: boolean;
+
+  // Table whitelist (optional, include only these tables)
+  tables?: string[];
+
+  // Table blacklist (optional, exclude these tables)
+  excludeTables?: string[];
+
+  // FTS configuration (optional)
+  fts?: {
+    enabled?: boolean;
+    tables?: Record<string, string[]>; // table -> columns to index
+  };
+}
+```
+
+## Path Structure
+
+The module exposes the following path patterns:
+
+| Path | Description |
+|------|-------------|
+| `/` | List all tables |
+| `/:table` | List rows in table or create new row |
+| `/:table/@schema` | Get table schema |
+| `/:table/:pk` | Read/update/delete specific row |
+| `/:table/:pk/@attr` | List row attributes (columns) |
+| `/:table/:pk/@attr/:column` | Get specific column value |
+| `/:table/:pk/@meta` | Get row metadata |
+| `/:table/:pk/@actions` | List available actions |
+| `/:table/:pk/@actions/:action` | Execute an action |
+
+## Built-in Actions
+
+### Row-level Actions
+
+- **validate**: Validate row data against schema constraints (NOT NULL, foreign keys)
+- **duplicate**: Create a copy of the row
+
+### Table-level Actions
+
+- **refresh**: Refresh the schema cache
+- **count**: Get total row count
+- **export**: Export table data as JSON or CSV
+
+```typescript
+// Validate a row
+const result = await afs.write("/modules/sqlite-afs/users/1/@actions/validate", {
+  content: {}
+});
+
+// Duplicate a row
+const result = await afs.write("/modules/sqlite-afs/users/1/@actions/duplicate", {
+  content: {}
+});
+
+// Export table data
+const jsonData = await sqliteAfs.exportTable("users", "json");
+const csvData = await sqliteAfs.exportTable("users", "csv");
+```
+
+## Custom Actions
+
+Register custom actions for domain-specific operations:
+
+```typescript
+const sqliteAfs = new SQLiteAFS({ url: "file:./db.sqlite3" });
+
+sqliteAfs.registerAction(
+  "archive",
+  async (ctx, params) => {
+    // ctx contains: db, schemas, table, pk, row, module
+    await ctx.db.run(sql.raw(`UPDATE "${ctx.table}" SET archived = 1 WHERE id = '${ctx.pk}'`));
+    return { archived: true };
+  },
+  {
+    description: "Archive the row",
+    rowLevel: true,
+    tableLevel: false
+  }
+);
+```
+
+## FTS5 Search
+
+Enable full-text search for specific columns:
+
+```typescript
+const sqliteAfs = new SQLiteAFS({
+  url: "file:./db.sqlite3",
+  fts: {
+    enabled: true,
+    tables: {
+      posts: ["title", "content"],
+      users: ["name", "bio"]
+    }
+  }
+});
+
+// Search across all FTS-enabled tables
+const results = await afs.search("/modules/sqlite-afs", "search query");
+
+// Search within a specific table
+const postResults = await afs.search("/modules/sqlite-afs/posts", "search query");
+```
+
+## Advanced Usage
+
+### Access Database Directly
+
+```typescript
+const db = sqliteAfs.getDatabase();
+await db.run(sql.raw("SELECT * FROM users"));
+```
+
+### Get Schema Information
+
+```typescript
+const schemas = sqliteAfs.getSchemas();
+const usersSchema = schemas.get("users");
+console.log(usersSchema.columns);
+console.log(usersSchema.primaryKey);
+console.log(usersSchema.foreignKeys);
+```
+
+### Refresh Schema After External Changes
+
+```typescript
+await sqliteAfs.refreshSchema();
+```
+
+## Integration with AI Agents
+
+```typescript
+import { AIAgent, AIGNE } from "@aigne/core";
+import { AFS } from "@aigne/afs";
+import { SQLiteAFS } from "@aigne/afs-sqlite";
+
+const afs = new AFS();
+afs.mount(new SQLiteAFS({
+  url: "file:./database.sqlite3",
+  accessMode: "readwrite"
+}));
+
+const agent = AIAgent.from({
+  name: "database-assistant",
+  afs: afs
+});
+
+const context = aigne.newContext();
+const result = await context.invoke(agent, {
+  message: "Show me all users in the database"
+});
+```
+
+## YAML Configuration
+
+SQLiteAFS can be configured via YAML when using the AIGNE loader:
+
+```yaml
+afs:
+  modules:
+    - module: "@aigne/afs-sqlite"
+      options:
+        url: "file:./database.sqlite3"
+        access_mode: readwrite
+        tables:
+          - users
+          - posts
+        fts:
+          enabled: true
+          tables:
+            posts:
+              - title
+              - content
+```
+
+## Related Packages
+
+- [@aigne/afs](../core/README.md) - Core AFS package
+- [@aigne/afs-history](../history/README.md) - History tracking module
+- [@aigne/afs-local-fs](../local-fs/README.md) - Local file system module
+- [@aigne/sqlite](../../packages/sqlite/README.md) - SQLite utilities
+
+## TypeScript Support
+
+This package includes full TypeScript type definitions.
+
+## License
+
+[Elastic-2.0](../../LICENSE.md)

package/lib/cjs/actions/built-in.d.ts

@@ -0,0 +1,5 @@
+import type { ActionsRegistry } from "./registry.js";
+/**
+ * Registers built-in actions to the registry
+ */
+export declare function registerBuiltInActions(registry: ActionsRegistry): void;

package/lib/cjs/actions/built-in.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBuiltInActions = registerBuiltInActions;
+const sqlite_1 = require("@aigne/sqlite");
+/**
+ * Executes a raw SQL query and returns all rows
+ */
+async function execAll(db, query) {
+    return db.all(sqlite_1.sql.raw(query)).execute();
+}
+/**
+ * Executes a raw SQL query (for INSERT, UPDATE, DELETE)
+ */
+async function execRun(db, query) {
+    await db.run(sqlite_1.sql.raw(query)).execute();
+}
+/**
+ * Registers built-in actions to the registry
+ */
+function registerBuiltInActions(registry) {
+    // Refresh schema action (table level)
+    registry.register({
+        name: "refresh",
+        description: "Refresh the schema cache for this module",
+        tableLevel: true,
+        rowLevel: false,
+        handler: async (ctx) => {
+            await ctx.module.refreshSchema();
+            return {
+                success: true,
+                message: "Schema refreshed successfully",
+            };
+        },
+    });
+    // Export table action (table level)
+    registry.register({
+        name: "export",
+        description: "Export table data in specified format (json, csv)",
+        tableLevel: true,
+        rowLevel: false,
+        inputSchema: {
+            type: "object",
+            properties: {
+                format: {
+                    type: "string",
+                    enum: ["json", "csv"],
+                    default: "json",
+                },
+            },
+        },
+        handler: async (ctx, params) => {
+            const format = params.format ?? "json";
+            const data = await ctx.module.exportTable(ctx.table, format);
+            return {
+                success: true,
+                data,
+            };
+        },
+    });
+    // Count rows action (table level)
+    registry.register({
+        name: "count",
+        description: "Get the total row count for this table",
+        tableLevel: true,
+        rowLevel: false,
+        handler: async (ctx) => {
+            const result = await execAll(ctx.db, `SELECT COUNT(*) as count FROM "${ctx.table}"`);
+            return {
+                success: true,
+                data: { count: result[0]?.count ?? 0 },
+            };
+        },
+    });
+    // Duplicate row action (row level)
+    registry.register({
+        name: "duplicate",
+        description: "Create a copy of this row",
+        tableLevel: false,
+        rowLevel: true,
+        handler: async (ctx) => {
+            if (!ctx.row) {
+                return { success: false, message: "Row data not available" };
+            }
+            const schema = ctx.schemas.get(ctx.table);
+            if (!schema) {
+                return { success: false, message: `Table '${ctx.table}' not found` };
+            }
+            // Create a copy without the primary key
+            const pkColumn = schema.primaryKey[0] ?? "rowid";
+            const rowCopy = { ...ctx.row };
+            delete rowCopy[pkColumn];
+            delete rowCopy.rowid;
+            // Build insert query
+            const columns = Object.keys(rowCopy);
+            const values = columns.map((col) => formatValueForSQL(rowCopy[col]));
+            await execRun(ctx.db, `INSERT INTO "${ctx.table}" (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${values.join(", ")})`);
+            // Get the new row's ID
+            const lastIdResult = await execAll(ctx.db, "SELECT last_insert_rowid() as id");
+            return {
+                success: true,
+                data: { newId: lastIdResult[0]?.id },
+                message: "Row duplicated successfully",
+            };
+        },
+    });
+    // Validate row action (row level)
+    registry.register({
+        name: "validate",
+        description: "Validate row data against schema constraints",
+        tableLevel: false,
+        rowLevel: true,
+        handler: async (ctx) => {
+            if (!ctx.row) {
+                return { success: false, message: "Row data not available" };
+            }
+            const schema = ctx.schemas.get(ctx.table);
+            if (!schema) {
+                return { success: false, message: `Table '${ctx.table}' not found` };
+            }
+            const errors = [];
+            // Check NOT NULL constraints
+            for (const col of schema.columns) {
+                if (col.notnull && (ctx.row[col.name] === null || ctx.row[col.name] === undefined)) {
+                    errors.push(`Column '${col.name}' cannot be null`);
+                }
+            }
+            // Check foreign key references
+            for (const fk of schema.foreignKeys) {
+                const value = ctx.row[fk.from];
+                if (value !== null && value !== undefined) {
+                    const refResult = await execAll(ctx.db, `SELECT COUNT(*) as count FROM "${fk.table}" WHERE "${fk.to}" = '${String(value).replace(/'/g, "''")}'`);
+                    if (refResult[0]?.count === 0) {
+                        errors.push(`Foreign key violation: ${fk.from} references non-existent ${fk.table}.${fk.to}`);
+                    }
+                }
+            }
+            return {
+                success: errors.length === 0,
+                data: { errors, valid: errors.length === 0 },
+                message: errors.length > 0 ? `Validation failed: ${errors.join("; ")}` : "Row is valid",
+            };
+        },
+    });
+}
+/**
+ * Formats a value for SQL insertion
+ */
+function formatValueForSQL(value) {
+    if (value === null || value === undefined) {
+        return "NULL";
+    }
+    if (typeof value === "number") {
+        return String(value);
+    }
+    if (typeof value === "boolean") {
+        return value ? "1" : "0";
+    }
+    if (value instanceof Date) {
+        return `'${value.toISOString()}'`;
+    }
+    if (typeof value === "object") {
+        return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+    }
+    return `'${String(value).replace(/'/g, "''")}'`;
+}

package/lib/cjs/actions/registry.d.ts

@@ -0,0 +1,49 @@
+import type { ActionContext, ActionDefinition, ActionHandler, ActionResult } from "./types.js";
+/**
+ * Registry for managing action handlers
+ */
+export declare class ActionsRegistry {
+    private handlers;
+    /**
+     * Registers an action handler
+     */
+    register(definition: ActionDefinition): void;
+    /**
+     * Registers a simple action with just name and handler
+     */
+    registerSimple(name: string, handler: ActionHandler, options?: {
+        description?: string;
+        tableLevel?: boolean;
+        rowLevel?: boolean;
+    }): void;
+    /**
+     * Unregisters an action
+     */
+    unregister(name: string): boolean;
+    /**
+     * Checks if an action is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Gets an action definition
+     */
+    get(name: string): ActionDefinition | undefined;
+    /**
+     * Lists all registered actions
+     */
+    list(options?: {
+        tableLevel?: boolean;
+        rowLevel?: boolean;
+    }): ActionDefinition[];
+    /**
+     * Lists action names
+     */
+    listNames(options?: {
+        tableLevel?: boolean;
+        rowLevel?: boolean;
+    }): string[];
+    /**
+     * Executes an action
+     */
+    execute(name: string, ctx: ActionContext, params?: Record<string, unknown>): Promise<ActionResult>;
+}