@aigne/afs-sqlite 1.11.0-beta.1 → 1.11.0-beta.10

package/dist/sqlite-afs.mjs

@@ -1,34 +1,48 @@
+import { __require } from "./_virtual/rolldown_runtime.mjs";
 import { registerBuiltInActions } from "./actions/built-in.mjs";
 import { ActionsRegistry } from "./actions/registry.mjs";
 import { sqliteAFSConfigSchema } from "./config.mjs";
-import { buildActionsListEntry } from "./node/builder.mjs";
+import { buildActionsListEntry, buildRootActionsListEntry, buildRootEntry, buildTableActionsListEntry, buildTableEntry } from "./node/builder.mjs";
 import { CRUDOperations } from "./operations/crud.mjs";
 import { FTSSearch, createFTSConfig } from "./operations/search.mjs";
-import { createPathRouter, matchPath } from "./router/path-router.mjs";
-import { SchemaIntrospector } from "./schema/introspector.mjs";
-import { initDatabase } from "@aigne/sqlite";
+import { SchemaService } from "./schema/service.mjs";
+import { __decorate } from "./_virtual/_@oxc-project_runtime@0.108.0/helpers/decorate.mjs";
+import { initDatabase, sql } from "@aigne/sqlite";
+import { AFSNotFoundError } from "@aigne/afs";
+import { z } from "zod";
+import { AFSBaseProvider, Actions, Delete, Explain, List, Meta, Read, Search, Stat, Write } from "@aigne/afs/provider";
 
 //#region src/sqlite-afs.ts
 /**
 * SQLite AFS Module
 *
 * Exposes SQLite databases as AFS nodes with full CRUD support,
-* schema introspection, FTS5 search, and virtual paths (@attr, @meta, @actions).
+* schema introspection, FTS5 search, and virtual paths (.meta, .actions).
 */
-var SQLiteAFS = class SQLiteAFS {
+var SQLiteAFS = class SQLiteAFS extends AFSBaseProvider {
 	name;
 	description;
 	accessMode;
 	db;
-	schemas = /* @__PURE__ */ new Map();
-	router;
+	schemaService;
 	crud;
 	ftsSearch;
 	actions;
 	ftsConfig;
 	initialized = false;
 	constructor(options) {
+		super();
 		this.options = options;
+		if (options.localPath && !options.url) options.url = `file:${options.localPath}`;
+		if (options.url.startsWith("file:")) {
+			const { existsSync, mkdirSync, writeFileSync } = __require("node:fs");
+			const { dirname } = __require("node:path");
+			const dbPath = options.url.slice(5);
+			if (!existsSync(dbPath)) {
+				mkdirSync(dirname(dbPath), { recursive: true });
+				writeFileSync(dbPath, "");
+			}
+		}
 		this.name = options.name ?? "sqlite-afs";
 		this.description = options.description ?? `SQLite database: ${options.url}`;
 		this.accessMode = options.accessMode ?? "readwrite";
@@ -42,20 +56,24 @@ var SQLiteAFS = class SQLiteAFS {
 	static schema() {
 		return sqliteAFSConfigSchema;
 	}
-	/**
-	* Loads a module instance from configuration
-	*/
-	static async load({ parsed }) {
-		return new SQLiteAFS(sqliteAFSConfigSchema.parse(parsed));
+	static manifest() {
+		return {
+			name: "sqlite",
+			description: "SQLite database — tables as directories, rows as nodes.\n- Browse tables and rows, full-text search (FTS5), schema introspection\n- Exec actions: `insert`, `update`, `delete` at table/row level, custom SQL\n- Path structure: `/{table}/{primary-key}`",
+			uriTemplate: "sqlite://{localPath+}",
+			category: "database",
+			schema: z.object({ localPath: z.string() }),
+			tags: ["sqlite", "database"]
+		};
 	}
 	/**
-	* Called when the module is mounted to AFS
+	* Loads a module instance from configuration
 	*/
-	async onMount(_afs) {
-		await this.initialize();
+	static async load({ config } = {}) {
+		return new SQLiteAFS(sqliteAFSConfigSchema.parse(config));
 	}
 	/**
-	* Initializes the database connection and introspects schema
+	* Initializes the database connection and schema service
 	*/
 	async initialize() {
 		if (this.initialized) return;
@@ -64,158 +82,672 @@ var SQLiteAFS = class SQLiteAFS {
 			wal: this.options.wal ?? true
 		});
 		const db = this.db;
-		this.schemas = await new SchemaIntrospector().introspect(db, {
+		this.schemaService = new SchemaService(db, {
 			tables: this.options.tables,
 			excludeTables: this.options.excludeTables
 		});
-		this.router = createPathRouter();
-		this.crud = new CRUDOperations(db, this.schemas, "");
-		this.ftsSearch = new FTSSearch(db, this.schemas, this.ftsConfig, "");
+		this.crud = new CRUDOperations(db, this.schemaService, "");
+		this.ftsSearch = new FTSSearch(db, this.schemaService, this.ftsConfig, "");
 		this.initialized = true;
 	}
 	/**
-	* Ensures the module is initialized
+	* Ensures the module is initialized.
+	* This is called automatically by handlers, but can also be called
+	* manually to trigger initialization (e.g., in tests).
 	*/
 	async ensureInitialized() {
 		if (!this.initialized) await this.initialize();
 	}
 	/**
-	* Lists entries at a path
-	*/
-	async list(path, options) {
-		await this.ensureInitialized();
-		const match = matchPath(this.router, path);
-		if (!match) return { data: [] };
-		switch (match.action) {
-			case "listTables": return this.crud.listTables();
-			case "listTable":
-				if (!match.params.table) return { data: [] };
-				return this.crud.listTable(match.params.table, options);
-			case "listAttributes":
-				if (!match.params.table || !match.params.pk) return { data: [] };
-				return this.crud.listAttributes(match.params.table, match.params.pk);
-			case "listActions":
-				if (!match.params.table || !match.params.pk) return { data: [] };
-				return this.listActions(match.params.table, match.params.pk);
-			default: return { data: [] };
-		}
+	* List all tables
+	* Note: list() returns only children, never the path itself (per new semantics)
+	*/
+	async listTablesHandler(_ctx) {
+		await this.ensureInitialized();
+		return { data: (await this.crud.listTables()).data };
+	}
+	/**
+	* List rows in a table
+	* Note: list() returns only children (rows), never the table itself (per new semantics)
+	*/
+	async listTableHandler(ctx) {
+		await this.ensureInitialized();
+		if (!await this.schemaService.getSchema(ctx.params.table)) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		return { data: (await this.crud.listTable(ctx.params.table, ctx.options)).data };
+	}
+	/**
+	* List a row - rows are leaf nodes with no children
+	* Note: list() returns only children, never the path itself (per new semantics)
+	*/
+	async listRowHandler(ctx) {
+		await this.ensureInitialized();
+		if (!(await this.crud.readRow(ctx.params.table, ctx.params.pk)).data) throw new AFSNotFoundError(`/${ctx.params.table}/${ctx.params.pk}`);
+		return { data: [] };
+	}
+	/**
+	* List actions for a row
+	*/
+	async listActionsHandler(ctx) {
+		await this.ensureInitialized();
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		const actions = this.actions.listWithInfo({ rowLevel: true }, {
+			tableSchema: schema,
+			tableName: ctx.params.table,
+			schemaService: this.schemaService
+		});
+		return { data: buildActionsListEntry(ctx.params.table, ctx.params.pk, actions, { basePath: "" }) };
+	}
+	/**
+	* List actions for a table (table-level actions)
+	*/
+	async listTableActionsHandler(ctx) {
+		await this.ensureInitialized();
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		const actions = this.actions.listWithInfo({ tableLevel: true }, {
+			tableSchema: schema,
+			tableName: ctx.params.table,
+			schemaService: this.schemaService
+		});
+		return { data: buildTableActionsListEntry(ctx.params.table, actions, { basePath: "" }) };
+	}
+	/**
+	* List actions at root level (database-level actions)
+	*/
+	async listRootActionsHandler(_ctx) {
+		await this.ensureInitialized();
+		return { data: buildRootActionsListEntry(this.actions.listWithInfo({ rootLevel: true }, { schemaService: this.schemaService }), { basePath: "" }) };
+	}
+	/**
+	* Read root (database) entry
+	*/
+	async readRootHandler(_ctx) {
+		await this.ensureInitialized();
+		return buildRootEntry(await this.schemaService.getAllSchemas(), { basePath: "" });
+	}
+	/**
+	* Read root metadata (database-level schema information)
+	*/
+	async readRootMetaHandler(_ctx) {
+		await this.ensureInitialized();
+		const schemas = await this.schemaService.getAllSchemas();
+		const tables = Array.from(schemas.entries()).sort((a, b) => a[0].localeCompare(b[0])).map(([name, schema]) => ({
+			name,
+			description: `Table with ${schema.columns.length} columns`,
+			columnCount: schema.columns.length,
+			primaryKey: schema.primaryKey
+		}));
+		return {
+			id: "root:.meta",
+			path: "/.meta",
+			content: {
+				type: "sqlite",
+				tableCount: schemas.size,
+				tables
+			},
+			meta: {
+				childrenCount: tables.length,
+				tables: tables.map((t) => t.name)
+			}
+		};
+	}
+	/**
+	* Read capabilities manifest
+	* Returns information about available actions at different levels
+	*/
+	async readCapabilitiesHandler(_ctx) {
+		await this.ensureInitialized();
+		const actionCatalogs = [];
+		const rootActions = this.actions.listWithInfo({ rootLevel: true }, { schemaService: this.schemaService });
+		if (rootActions.length > 0) actionCatalogs.push({
+			kind: "sqlite:root",
+			description: "Database-level operations",
+			catalog: rootActions.map((a) => ({
+				name: a.name,
+				description: a.description,
+				inputSchema: a.inputSchema
+			})),
+			discovery: {
+				pathTemplate: "/.actions",
+				note: "Available at database root"
+			}
+		});
+		const tableActions = this.actions.listWithInfo({ tableLevel: true }, { schemaService: this.schemaService });
+		if (tableActions.length > 0) actionCatalogs.push({
+			kind: "sqlite:table",
+			description: "Table-level operations",
+			catalog: tableActions.map((a) => ({
+				name: a.name,
+				description: a.description,
+				inputSchema: a.inputSchema
+			})),
+			discovery: {
+				pathTemplate: "/:table/.actions",
+				note: "Replace :table with actual table name"
+			}
+		});
+		const rowActions = this.actions.listWithInfo({ rowLevel: true }, { schemaService: this.schemaService });
+		if (rowActions.length > 0) actionCatalogs.push({
+			kind: "sqlite:row",
+			description: "Row-level operations",
+			catalog: rowActions.map((a) => ({
+				name: a.name,
+				description: a.description,
+				inputSchema: a.inputSchema
+			})),
+			discovery: {
+				pathTemplate: "/:table/:pk/.actions",
+				note: "Replace :table with table name, :pk with primary key value"
+			}
+		});
+		return {
+			id: "/.meta/.capabilities",
+			path: "/.meta/.capabilities",
+			content: {
+				schemaVersion: 1,
+				provider: this.name,
+				version: "1.0.0",
+				description: this.description,
+				tools: [],
+				actions: actionCatalogs,
+				operations: this.getOperationsDeclaration()
+			},
+			meta: { kind: "afs:capabilities" }
+		};
+	}
+	/**
+	* Read table (directory) entry
+	*/
+	async readTableHandler(ctx) {
+		await this.ensureInitialized();
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		const rowCount = (await this.db.all(sql.raw(`SELECT COUNT(*) as count FROM "${ctx.params.table}"`)))[0]?.count ?? 0;
+		return buildTableEntry(ctx.params.table, schema, {
+			basePath: "",
+			rowCount
+		});
+	}
+	/**
+	* Read table metadata (table-level schema information)
+	*/
+	async readTableMetaHandler(ctx) {
+		await this.ensureInitialized();
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		const rowCount = (await this.db.all(sql.raw(`SELECT COUNT(*) as count FROM "${ctx.params.table}"`)))[0]?.count ?? 0;
+		const columns = schema.columns.map((col) => ({
+			name: col.name,
+			type: col.type,
+			nullable: !col.notnull,
+			primaryKey: col.pk > 0,
+			defaultValue: col.dfltValue
+		}));
+		return {
+			id: `${ctx.params.table}:.meta`,
+			path: `/${ctx.params.table}/.meta`,
+			content: {
+				table: ctx.params.table,
+				columns,
+				primaryKey: schema.primaryKey,
+				foreignKeys: schema.foreignKeys.map((fk) => ({
+					column: fk.from,
+					referencesTable: fk.table,
+					referencesColumn: fk.to,
+					onUpdate: fk.onUpdate,
+					onDelete: fk.onDelete
+				})),
+				indexes: schema.indexes.map((idx) => ({
+					name: idx.name,
+					unique: idx.unique,
+					origin: idx.origin
+				})),
+				rowCount
+			},
+			meta: {
+				table: ctx.params.table,
+				description: `Table "${ctx.params.table}" with ${columns.length} columns`,
+				childrenCount: rowCount,
+				columnCount: columns.length,
+				columns: columns.map((c) => c.name),
+				primaryKey: schema.primaryKey
+			}
+		};
+	}
+	/**
+	* Read a row
+	*/
+	async readRowHandler(ctx) {
+		await this.ensureInitialized();
+		return (await this.crud.readRow(ctx.params.table, ctx.params.pk)).data;
+	}
+	/**
+	* Get row metadata (@meta suffix - SQLite-specific)
+	*/
+	async getMetaHandler(ctx) {
+		await this.ensureInitialized();
+		return (await this.crud.getMeta(ctx.params.table, ctx.params.pk)).data;
+	}
+	/**
+	* Get row metadata (.meta suffix - row-level schema information)
+	*/
+	async getRowDotMetaHandler(ctx) {
+		await this.ensureInitialized();
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		if (!(await this.crud.readRow(ctx.params.table, ctx.params.pk)).data) throw new AFSNotFoundError(`/${ctx.params.table}/${ctx.params.pk}`);
+		const pkColumn = schema.primaryKey[0] ?? "rowid";
+		return {
+			id: `${ctx.params.table}:${ctx.params.pk}:.meta`,
+			path: `/${ctx.params.table}/${ctx.params.pk}/.meta`,
+			content: {
+				table: ctx.params.table,
+				primaryKey: pkColumn,
+				primaryKeyValue: ctx.params.pk,
+				columns: schema.columns.map((col) => ({
+					name: col.name,
+					type: col.type,
+					nullable: !col.notnull,
+					primaryKey: col.pk > 0
+				})),
+				foreignKeys: schema.foreignKeys.map((fk) => ({
+					column: fk.from,
+					referencesTable: fk.table,
+					referencesColumn: fk.to
+				}))
+			},
+			meta: {
+				table: ctx.params.table,
+				primaryKeyValue: ctx.params.pk,
+				columns: schema.columns.map((col) => col.name)
+			}
+		};
+	}
+	/**
+	* Create a new row
+	*/
+	async createRowHandler(ctx, content) {
+		await this.ensureInitialized();
+		return this.crud.createRow(ctx.params.table, content.content ?? content);
+	}
+	/**
+	* Update an existing row
+	*/
+	async updateRowHandler(ctx, content) {
+		await this.ensureInitialized();
+		return this.crud.updateRow(ctx.params.table, ctx.params.pk, content.content ?? content);
+	}
+	/**
+	* Execute action via write (for triggering row-level actions)
+	*/
+	async executeActionWriteHandler(ctx, content) {
+		await this.ensureInitialized();
+		return this.executeAction(ctx.params.table, ctx.params.pk, ctx.params.action, content.content ?? content);
+	}
+	/**
+	* Execute action via write (for triggering table-level actions)
+	*/
+	async executeTableActionWriteHandler(ctx, content) {
+		await this.ensureInitialized();
+		return this.executeAction(ctx.params.table, void 0, ctx.params.action, content.content ?? content);
+	}
+	/**
+	* Execute action via write (for triggering root-level actions)
+	*/
+	async executeRootActionWriteHandler(ctx, content) {
+		await this.ensureInitialized();
+		return this.executeRootAction(ctx.params.action, content.content ?? content);
+	}
+	/**
+	* Delete a table entry (not supported - always throws)
+	*/
+	async deleteTableHandler(ctx) {
+		await this.ensureInitialized();
+		if (!await this.schemaService.hasTable(ctx.params.table)) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		throw new Error(`Cannot delete table '${ctx.params.table}'. Use SQL directly to drop tables.`);
+	}
+	/**
+	* Delete a row
+	*/
+	async deleteRowHandler(ctx) {
+		await this.ensureInitialized();
+		return this.crud.deleteRow(ctx.params.table, ctx.params.pk);
+	}
+	/**
+	* Search all tables
+	*/
+	async searchAllHandler(_ctx, query, options) {
+		await this.ensureInitialized();
+		return this.ftsSearch.search(query, options);
+	}
+	/**
+	* Search a specific table
+	*/
+	async searchTableHandler(ctx, query, options) {
+		await this.ensureInitialized();
+		return this.ftsSearch.searchTable(ctx.params.table, query, options);
+	}
+	/**
+	* Get stat for root (database level)
+	*/
+	async statRootHandler(_ctx) {
+		await this.ensureInitialized();
+		const schemas = await this.schemaService.getAllSchemas();
+		const actions = this.actions.listWithInfo({ rootLevel: true }, { schemaService: this.schemaService });
+		return { data: {
+			id: "/",
+			path: "/",
+			meta: {
+				kind: "sqlite:database",
+				kinds: ["sqlite:database", "afs:node"],
+				tableCount: schemas.size,
+				childrenCount: schemas.size
+			},
+			actions: actions.length > 0 ? actions.map((a) => ({
+				name: a.name,
+				description: a.description
+			})) : void 0
+		} };
 	}
 	/**
-	* Reads an entry at a path
-	*/
-	async read(path, _options) {
-		await this.ensureInitialized();
-		const match = matchPath(this.router, path);
-		if (!match) return {};
-		switch (match.action) {
-			case "readRow":
-				if (!match.params.table || !match.params.pk) return {};
-				return this.crud.readRow(match.params.table, match.params.pk);
-			case "getSchema":
-				if (!match.params.table) return {};
-				return this.crud.getSchema(match.params.table);
-			case "getAttribute":
-				if (!match.params.table || !match.params.pk || !match.params.column) return {};
-				return this.crud.getAttribute(match.params.table, match.params.pk, match.params.column);
-			case "getMeta":
-				if (!match.params.table || !match.params.pk) return {};
-				return this.crud.getMeta(match.params.table, match.params.pk);
-			default: return {};
+	* Get stat for a table
+	*/
+	async statTableHandler(ctx) {
+		await this.ensureInitialized();
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		const rowCount = (await this.db.all(sql.raw(`SELECT COUNT(*) as count FROM "${ctx.params.table}"`)))[0]?.count ?? 0;
+		const actions = this.actions.listWithInfo({ tableLevel: true }, {
+			tableSchema: schema,
+			tableName: ctx.params.table,
+			schemaService: this.schemaService
+		});
+		const columns = schema.columns.map((col) => ({
+			name: col.name,
+			type: col.type,
+			nullable: !col.notnull,
+			primaryKey: col.pk > 0
+		}));
+		return { data: {
+			id: ctx.params.table,
+			path: `/${ctx.params.table}`,
+			meta: {
+				kind: "sqlite:table",
+				kinds: ["sqlite:table", "afs:node"],
+				table: ctx.params.table,
+				columnCount: schema.columns.length,
+				columns,
+				primaryKey: schema.primaryKey[0],
+				childrenCount: rowCount
+			},
+			actions: actions.length > 0 ? actions.map((a) => ({
+				name: a.name,
+				description: a.description
+			})) : void 0
+		} };
+	}
+	/**
+	* Get stat for a row
+	*/
+	async statRowHandler(ctx) {
+		await this.ensureInitialized();
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		if (!(await this.crud.readRow(ctx.params.table, ctx.params.pk)).data) throw new AFSNotFoundError(`/${ctx.params.table}/${ctx.params.pk}`);
+		const actions = this.actions.listWithInfo({ rowLevel: true }, {
+			tableSchema: schema,
+			tableName: ctx.params.table,
+			schemaService: this.schemaService
+		});
+		const columns = schema.columns.map((col) => ({
+			name: col.name,
+			type: col.type,
+			nullable: !col.notnull,
+			primaryKey: col.pk > 0
+		}));
+		return { data: {
+			id: ctx.params.pk,
+			path: `/${ctx.params.table}/${ctx.params.pk}`,
+			meta: {
+				kind: "sqlite:row",
+				kinds: ["sqlite:row", "afs:node"],
+				table: ctx.params.table,
+				primaryKey: ctx.params.pk,
+				columnCount: schema.columns.length,
+				columns,
+				childrenCount: 0
+			},
+			actions: actions.length > 0 ? actions.map((a) => ({
+				name: a.name,
+				description: a.description
+			})) : void 0
+		} };
+	}
+	/**
+	* Explain root (database level)
+	*/
+	async explainRootHandler(ctx) {
+		await this.ensureInitialized();
+		const format = ctx.options?.format || "markdown";
+		const schemas = await this.schemaService.getAllSchemas();
+		const tables = Array.from(schemas.values());
+		const lines = [];
+		if (format === "markdown") {
+			lines.push(`# ${this.name}`);
+			lines.push("");
+			lines.push(`**Type:** SQLite Database`);
+			lines.push(`**Tables:** ${tables.length}`);
+			lines.push("");
+			if (tables.length > 0) {
+				lines.push("## Tables");
+				lines.push("");
+				lines.push("| Table | Columns | Primary Key |");
+				lines.push("|-------|---------|-------------|");
+				for (const table of tables) {
+					const pk = table.primaryKey.join(", ") || "rowid";
+					lines.push(`| ${table.name} | ${table.columns.length} | ${pk} |`);
+				}
+			}
+		} else {
+			lines.push(`${this.name} (SQLite Database)`);
+			lines.push(`Tables: ${tables.length}`);
+			for (const table of tables) lines.push(`  - ${table.name} (${table.columns.length} columns)`);
 		}
+		return {
+			content: lines.join("\n"),
+			format
+		};
 	}
 	/**
-	* Writes an entry at a path
-	*/
-	async write(path, content, _options) {
-		await this.ensureInitialized();
-		if (this.accessMode === "readonly") throw new Error("Module is in readonly mode");
-		const match = matchPath(this.router, path);
-		if (!match) throw new Error(`Invalid path: ${path}`);
-		switch (match.action) {
-			case "createRow":
-				if (!match.params.table) throw new Error("Table name required for create");
-				return this.crud.createRow(match.params.table, content.content ?? content);
-			case "readRow":
-				if (!match.params.table || !match.params.pk) throw new Error("Table and primary key required for update");
-				return this.crud.updateRow(match.params.table, match.params.pk, content.content ?? content);
-			case "executeAction":
-				if (!match.params.table || !match.params.action) throw new Error("Table and action name required");
-				return this.executeAction(match.params.table, match.params.pk, match.params.action, content.content ?? content);
-			default: throw new Error(`Write not supported for path: ${path}`);
+	* Explain a table
+	*/
+	async explainTableHandler(ctx) {
+		await this.ensureInitialized();
+		const format = ctx.options?.format || "markdown";
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		const rowCount = (await this.db.all(sql.raw(`SELECT COUNT(*) as count FROM "${ctx.params.table}"`)))[0]?.count ?? 0;
+		const lines = [];
+		if (format === "markdown") {
+			lines.push(`# ${ctx.params.table}`);
+			lines.push("");
+			lines.push(`**Type:** SQLite Table`);
+			lines.push(`**Rows:** ${rowCount}`);
+			lines.push(`**Primary Key:** ${schema.primaryKey.join(", ") || "rowid"}`);
+			lines.push("");
+			lines.push("## Columns");
+			lines.push("");
+			lines.push("| Column | Type | Nullable | Primary Key | Default |");
+			lines.push("|--------|------|----------|-------------|---------|");
+			for (const col of schema.columns) {
+				const nullable = col.notnull ? "NO" : "YES";
+				const pk = col.pk > 0 ? "YES" : "";
+				const dflt = col.dfltValue !== null && col.dfltValue !== void 0 ? String(col.dfltValue) : "";
+				lines.push(`| ${col.name} | ${col.type} | ${nullable} | ${pk} | ${dflt} |`);
+			}
+			if (schema.indexes.length > 0) {
+				lines.push("");
+				lines.push("## Indexes");
+				lines.push("");
+				for (const idx of schema.indexes) {
+					const uniqueStr = idx.unique ? " (UNIQUE)" : "";
+					lines.push(`- **${idx.name}**${uniqueStr}`);
+				}
+			}
+			if (schema.foreignKeys.length > 0) {
+				lines.push("");
+				lines.push("## Foreign Keys");
+				lines.push("");
+				for (const fk of schema.foreignKeys) lines.push(`- \`${fk.from}\` → \`${fk.table}\`(\`${fk.to}\`) ON DELETE ${fk.onDelete}`);
+			}
+		} else {
+			lines.push(`${ctx.params.table} (SQLite Table)`);
+			lines.push(`Rows: ${rowCount}`);
+			lines.push(`Primary Key: ${schema.primaryKey.join(", ") || "rowid"}`);
+			lines.push(`Columns: ${schema.columns.map((c) => `${c.name} (${c.type})`).join(", ")}`);
+			if (schema.indexes.length > 0) lines.push(`Indexes: ${schema.indexes.map((i) => i.name).join(", ")}`);
+			if (schema.foreignKeys.length > 0) lines.push(`Foreign Keys: ${schema.foreignKeys.map((fk) => `${fk.from} → ${fk.table}(${fk.to})`).join(", ")}`);
 		}
+		return {
+			content: lines.join("\n"),
+			format
+		};
 	}
 	/**
-	* Deletes an entry at a path
+	* Explain a row
 	*/
-	async delete(path, _options) {
+	async explainRowHandler(ctx) {
 		await this.ensureInitialized();
-		if (this.accessMode === "readonly") throw new Error("Module is in readonly mode");
-		const match = matchPath(this.router, path);
-		if (!match || match.action !== "readRow") throw new Error(`Delete not supported for path: ${path}`);
-		if (!match.params.table || !match.params.pk) throw new Error("Table and primary key required for delete");
-		return this.crud.deleteRow(match.params.table, match.params.pk);
+		const format = ctx.options?.format || "markdown";
+		const schema = await this.schemaService.getSchema(ctx.params.table);
+		if (!schema) throw new AFSNotFoundError(`/${ctx.params.table}`);
+		const result = await this.crud.readRow(ctx.params.table, ctx.params.pk);
+		if (!result.data) throw new AFSNotFoundError(`/${ctx.params.table}/${ctx.params.pk}`);
+		const rowContent = result.data.content;
+		const pkColumn = schema.primaryKey[0] ?? "rowid";
+		const lines = [];
+		if (format === "markdown") {
+			lines.push(`# ${ctx.params.table}/${ctx.params.pk}`);
+			lines.push("");
+			lines.push(`**Table:** ${ctx.params.table}`);
+			lines.push(`**Primary Key:** ${pkColumn} = ${ctx.params.pk}`);
+			lines.push("");
+			if (rowContent) {
+				lines.push("## Values");
+				lines.push("");
+				lines.push("| Column | Value |");
+				lines.push("|--------|-------|");
+				for (const col of schema.columns) {
+					const val = rowContent[col.name];
+					const displayVal = val === null || val === void 0 ? "*null*" : truncateValue(String(val), 100);
+					lines.push(`| ${col.name} | ${displayVal} |`);
+				}
+			}
+		} else {
+			lines.push(`${ctx.params.table}/${ctx.params.pk} (SQLite Row)`);
+			lines.push(`Table: ${ctx.params.table}, ${pkColumn} = ${ctx.params.pk}`);
+			if (rowContent) for (const col of schema.columns) {
+				const val = rowContent[col.name];
+				lines.push(`  ${col.name}: ${val === null || val === void 0 ? "null" : truncateValue(String(val), 100)}`);
+			}
+		}
+		return {
+			content: lines.join("\n"),
+			format
+		};
 	}
 	/**
-	* Searches for entries matching a query
+	* Execute action via exec (row-level)
 	*/
-	async search(path, query, options) {
+	async handleRowActionExec(ctx, args) {
 		await this.ensureInitialized();
-		const match = matchPath(this.router, path);
-		if (match?.params.table) return this.ftsSearch.searchTable(match.params.table, query, options);
-		return this.ftsSearch.search(query, options);
+		return this.executeActionRaw(ctx.params.table, ctx.params.pk, ctx.params.action, args);
 	}
 	/**
-	* Executes a module operation
+	* Execute action via exec (table-level)
 	*/
-	async exec(path, args, _options) {
+	async handleTableActionExec(ctx, args) {
 		await this.ensureInitialized();
-		const match = matchPath(this.router, path);
-		if (match?.action === "executeAction" && match.params.table && match.params.action) return { data: (await this.executeAction(match.params.table, match.params.pk, match.params.action, args)).data };
-		throw new Error(`Exec not supported for path: ${path}`);
+		return this.executeActionRaw(ctx.params.table, void 0, ctx.params.action, args);
 	}
 	/**
-	* Lists available actions for a row
+	* Execute action via exec (root-level)
 	*/
-	listActions(table, pk) {
-		return { data: buildActionsListEntry(table, pk, this.actions.listNames({ rowLevel: true }), { basePath: "" }) };
+	async handleRootActionExec(ctx, args) {
+		await this.ensureInitialized();
+		return this.executeRootActionRaw(ctx.params.action, args);
 	}
 	/**
-	* Executes an action
+	* Executes an action and returns raw result (for exec handlers)
+	* Returns AFSExecResult structure: { success: boolean, data?: Record<string, unknown> }
 	*/
-	async executeAction(table, pk, actionName, params) {
-		if (!this.schemas.get(table)) throw new Error(`Table '${table}' not found`);
+	async executeActionRaw(table, pk, actionName, params) {
+		if (!await this.schemaService.getSchema(table)) throw new AFSNotFoundError(`/${table}`);
 		let row;
 		if (pk) row = (await this.crud.readRow(table, pk)).data?.content;
 		const ctx = {
 			db: this.db,
-			schemas: this.schemas,
+			schemaService: this.schemaService,
 			table,
 			pk,
 			row,
-			module: {
-				refreshSchema: () => this.refreshSchema(),
-				exportTable: (t, f) => this.exportTable(t, f)
-			}
+			module: { exportTable: (t, f) => this.exportTable(t, f) }
 		};
 		const result = await this.actions.execute(actionName, ctx, params);
 		if (!result.success) throw new Error(result.message ?? "Action failed");
+		if (Array.isArray(result.data)) return {
+			success: true,
+			data: { data: result.data }
+		};
+		return {
+			success: true,
+			data: result.data
+		};
+	}
+	/**
+	* Executes a root-level action and returns raw result (for exec handlers)
+	* Returns AFSExecResult structure: { success: boolean, data?: Record<string, unknown> }
+	*/
+	async executeRootActionRaw(actionName, params) {
+		const ctx = {
+			db: this.db,
+			schemaService: this.schemaService,
+			table: "",
+			module: { exportTable: (t, f) => this.exportTable(t, f) }
+		};
+		const result = await this.actions.execute(actionName, ctx, params);
+		if (!result.success) throw new Error(result.message ?? "Action failed");
+		if (Array.isArray(result.data)) return {
+			success: true,
+			data: { data: result.data }
+		};
+		return {
+			success: true,
+			data: result.data
+		};
+	}
+	/**
+	* Executes an action (for write handlers - wraps in AFSEntry)
+	*/
+	async executeAction(table, pk, actionName, params) {
+		const result = await this.executeActionRaw(table, pk, actionName, params);
 		return { data: {
-			id: `${table}:${pk ?? ""}:@actions:${actionName}`,
-			path: pk ? `/${table}/${pk}/@actions/${actionName}` : `/${table}/@actions/${actionName}`,
-			content: result.data
+			id: `${table}:${pk ?? ""}:.actions:${actionName}`,
+			path: pk ? `/${table}/${pk}/.actions/${actionName}` : `/${table}/.actions/${actionName}`,
+			content: result
 		} };
 	}
 	/**
-	* Refreshes the schema cache
+	* Executes a root-level action (for write handlers - wraps in AFSEntry)
 	*/
-	async refreshSchema() {
-		const db = this.db;
-		this.schemas = await new SchemaIntrospector().introspect(db, {
-			tables: this.options.tables,
-			excludeTables: this.options.excludeTables
-		});
-		this.crud.setSchemas(this.schemas);
-		this.ftsSearch.setSchemas(this.schemas);
+	async executeRootAction(actionName, params) {
+		const result = await this.executeRootActionRaw(actionName, params);
+		return { data: {
+			id: `:.actions:${actionName}`,
+			path: `/.actions/${actionName}`,
+			content: result
+		} };
 	}
 	/**
 	* Exports table data in specified format
@@ -223,8 +755,8 @@ var SQLiteAFS = class SQLiteAFS {
 	async exportTable(table, format) {
 		const listResult = await this.crud.listTable(table, { limit: 1e4 });
 		if (format === "csv") {
-			const schema = this.schemas.get(table);
-			if (!schema) throw new Error(`Table '${table}' not found`);
+			const schema = await this.schemaService.getSchema(table);
+			if (!schema) throw new AFSNotFoundError(`/${table}`);
 			return `${schema.columns.map((c) => c.name).join(",")}\n${listResult.data.map((entry) => {
 				const content = entry.content;
 				return schema.columns.map((c) => {
@@ -248,9 +780,11 @@ var SQLiteAFS = class SQLiteAFS {
 	}
 	/**
 	* Gets table schemas (for external access)
+	* Note: This queries the database on-demand
 	*/
-	getSchemas() {
-		return this.schemas;
+	async getSchemas() {
+		await this.ensureInitialized();
+		return this.schemaService.getAllSchemas();
 	}
 	/**
 	* Gets the database instance (for advanced operations)
@@ -259,6 +793,45 @@ var SQLiteAFS = class SQLiteAFS {
 		return this.db;
 	}
 };
+__decorate([List("/")], SQLiteAFS.prototype, "listTablesHandler", null);
+__decorate([List("/:table")], SQLiteAFS.prototype, "listTableHandler", null);
+__decorate([List("/:table/:pk")], SQLiteAFS.prototype, "listRowHandler", null);
+__decorate([Actions("/:table/:pk")], SQLiteAFS.prototype, "listActionsHandler", null);
+__decorate([Actions("/:table")], SQLiteAFS.prototype, "listTableActionsHandler", null);
+__decorate([Actions("/")], SQLiteAFS.prototype, "listRootActionsHandler", null);
+__decorate([Read("/")], SQLiteAFS.prototype, "readRootHandler", null);
+__decorate([Meta("/")], SQLiteAFS.prototype, "readRootMetaHandler", null);
+__decorate([Read("/.meta/.capabilities")], SQLiteAFS.prototype, "readCapabilitiesHandler", null);
+__decorate([Read("/:table")], SQLiteAFS.prototype, "readTableHandler", null);
+__decorate([Meta("/:table")], SQLiteAFS.prototype, "readTableMetaHandler", null);
+__decorate([Read("/:table/:pk")], SQLiteAFS.prototype, "readRowHandler", null);
+__decorate([Read("/:table/:pk/@meta")], SQLiteAFS.prototype, "getMetaHandler", null);
+__decorate([Meta("/:table/:pk")], SQLiteAFS.prototype, "getRowDotMetaHandler", null);
+__decorate([Write("/:table/new")], SQLiteAFS.prototype, "createRowHandler", null);
+__decorate([Write("/:table/:pk")], SQLiteAFS.prototype, "updateRowHandler", null);
+__decorate([Write("/:table/:pk/.actions/:action")], SQLiteAFS.prototype, "executeActionWriteHandler", null);
+__decorate([Write("/:table/.actions/:action")], SQLiteAFS.prototype, "executeTableActionWriteHandler", null);
+__decorate([Write("/.actions/:action")], SQLiteAFS.prototype, "executeRootActionWriteHandler", null);
+__decorate([Delete("/:table")], SQLiteAFS.prototype, "deleteTableHandler", null);
+__decorate([Delete("/:table/:pk")], SQLiteAFS.prototype, "deleteRowHandler", null);
+__decorate([Search("/")], SQLiteAFS.prototype, "searchAllHandler", null);
+__decorate([Search("/:table")], SQLiteAFS.prototype, "searchTableHandler", null);
+__decorate([Stat("/")], SQLiteAFS.prototype, "statRootHandler", null);
+__decorate([Stat("/:table")], SQLiteAFS.prototype, "statTableHandler", null);
+__decorate([Stat("/:table/:pk")], SQLiteAFS.prototype, "statRowHandler", null);
+__decorate([Explain("/")], SQLiteAFS.prototype, "explainRootHandler", null);
+__decorate([Explain("/:table")], SQLiteAFS.prototype, "explainTableHandler", null);
+__decorate([Explain("/:table/:pk")], SQLiteAFS.prototype, "explainRowHandler", null);
+__decorate([Actions.Exec("/:table/:pk")], SQLiteAFS.prototype, "handleRowActionExec", null);
+__decorate([Actions.Exec("/:table")], SQLiteAFS.prototype, "handleTableActionExec", null);
+__decorate([Actions.Exec("/")], SQLiteAFS.prototype, "handleRootActionExec", null);
+/**
+* Truncate a string value for display purposes.
+*/
+function truncateValue(value, maxLength) {
+	if (value.length <= maxLength) return value;
+	return `${value.slice(0, maxLength)}...`;
+}
 
 //#endregion
 export { SQLiteAFS };