@sqg/sqg 0.1.1 → 0.2.1

package/README.md

@@ -0,0 +1,156 @@
+# SQG - SQL Query Generator
+
+Type-safe code generation from SQL. Write SQL, get fully-typed database access code.
+
+## What it does
+
+SQG reads annotated `.sql` files, executes queries against real databases to introspect column types, and generates type-safe  code to execute the SQL queries.
+
+The syntax of the `.sql` file is compatible with [DBeaver](https://dbeaver.io/), this allows to develop the SQL 
+queries with it and then generate the code from the same file.
+
+## Features
+
+- **Type-safe by design** - Generates fully-typed code with accurate column types inferred from your database
+- **Multiple database engines** - Supports SQLite, DuckDB, and (soon) PostgreSQL
+- **Multiple language targets** - Generate TypeScript or Java code from the same SQL files
+- **Arrow API support** - Can generate Apache Arrow API bindings for DuckDB (Java)
+- **DBeaver compatible** - Works seamlessly with DBeaver for database development and testing
+- **Complex type support** - DuckDB: Handles structs, lists, and maps
+- **Migration management** - Built-in support for schema migrations and test data
+
+
+## Installation
+
+```bash
+pnpm add -g @sqg/sqg
+pnpm approve-builds -g  # needed for sqlite dependency
+```
+
+Check if the install was successful:
+```bash
+sqg --help
+```
+
+## Quick Start
+
+### Option 1: Use `sqg init` (Recommended)
+
+```bash
+# Initialize a new project (creates sqg.yaml and queries.sql)
+sqg init
+
+# Or with a specific database engine
+sqg init --engine duckdb
+
+# Generate code
+sqg sqg.yaml
+```
+
+### Option 2: Manual Setup
+
+1. Create `sqg.yaml` in your project root:
+
+```yaml
+version: 1
+name: my-project
+sql:
+  - engine: sqlite    # sqlite, duckdb, or postgres
+    files:
+      - queries.sql
+    gen:
+      - generator: typescript/better-sqlite3
+        output: src/db.ts
+```
+
+2. Write your SQL file with annotations
+
+For example `queries.sql`:
+
+```sql
+-- MIGRATE createUsersTable
+CREATE TABLE users (id INTEGER PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    email TEXT);
+
+-- QUERY getUserById :one
+@set id = 1
+SELECT id, name, email FROM users WHERE id = ${id};
+
+-- QUERY getUsers
+SELECT id, name, email FROM users;
+
+-- EXEC insertUser
+@set name = 'John'
+@set email = 'john@example.com'
+INSERT INTO users (name, email) VALUES (${name}, ${email});
+```
+
+3. Run SQG to generate code:
+
+```bash
+sqg sqg.yaml
+```
+
+4. Use the generated code:
+
+```typescript
+import Database from 'better-sqlite3';
+import { Queries } from './db';
+
+const db = new Database(':memory:');
+const queries = new Queries(db);
+
+// Run migrations
+for (const sql of Queries.getMigrations()) {
+  db.exec(sql);
+}
+
+// Type-safe queries
+queries.insertUser('Alice', 'alice@example.com');
+const user = queries.getUserById(1);
+console.log(user?.name);
+```
+
+## SQL Annotations
+
+| Annotation | Description |
+|------------|-------------|
+| `-- MIGRATE name` | Schema migration (CREATE TABLE, etc.) |
+| `-- QUERY name` | SELECT query returning rows |
+| `-- QUERY name :one` | Query returning single row or undefined |
+| `-- QUERY name :pluck` | Return single (first) column value |
+| `-- EXEC name` | INSERT/UPDATE/DELETE (no result rows) |
+| `-- TESTDATA name` | Test data, runs after migrations |
+| `@set var = value` | Define parameter with sample value |
+| `${var}` | Reference parameter in query |
+
+## Supported Databases & Generators
+
+| Language | Database | API | Generator | Status |
+|----------|----------|-----|-----------|--------|
+| TypeScript | SQLite   | better-sqlite3 | `typescript/better-sqlite3` | Tested |
+| TypeScript | DuckDB   | @duckdb/node-api | `typescript/duckdb` | Tested |
+| Java | Any (JDBC) | JDBC | `java/jdbc` | Tested |
+| Java | DuckDB   | Apache Arrow | `java/duckdb-arrow` | Tested |
+| TypeScript | PostgreSQL | pg (node-postgres) | `typescript/pg` | under development |
+
+## CLI Commands
+
+```bash
+sqg <config>              # Generate code from config file
+sqg init                  # Initialize new project with example files
+sqg init --engine duckdb  # Initialize with specific database engine
+sqg --validate <config>   # Validate config without generating code
+sqg --format json <config> # Output as JSON (for tooling integration)
+sqg syntax                # Show SQL annotation syntax reference
+sqg --help                # Show all options
+```
+
+## Documentation
+
+Full documentation at [sqg.dev](https://sqg.dev)
+
+## License
+
+Apache-2.0

package/dist/sqg.mjs

@@ -2,7 +2,7 @@
 import { exit } from "node:process";
 import { Command } from "commander";
 import consola, { LogLevels } from "consola";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import Handlebars from "handlebars";
@@ -20,6 +20,263 @@ import prettierPluginJava from "prettier-plugin-java";
 import typescriptPlugin from "prettier/parser-typescript";
 import estree from "prettier/plugins/estree";
 
+//#region src/constants.ts
+/**
+* SQG Constants - Centralized definitions for supported engines and generators
+* This file enables self-documenting CLI help and validation.
+*/
+/** Supported database engines */
+const SUPPORTED_ENGINES = [
+	"sqlite",
+	"duckdb",
+	"postgres"
+];
+/** Supported code generators with their descriptions */
+const SUPPORTED_GENERATORS = {
+	"typescript/better-sqlite3": {
+		description: "TypeScript with better-sqlite3 driver",
+		compatibleEngines: ["sqlite"],
+		extension: ".ts"
+	},
+	"typescript/duckdb": {
+		description: "TypeScript with @duckdb/node-api driver",
+		compatibleEngines: ["duckdb"],
+		extension: ".ts"
+	},
+	"java/jdbc": {
+		description: "Java with JDBC (SQLite, DuckDB, PostgreSQL)",
+		compatibleEngines: [
+			"sqlite",
+			"duckdb",
+			"postgres"
+		],
+		extension: ".java"
+	},
+	"java/duckdb-arrow": {
+		description: "Java with DuckDB Arrow API",
+		compatibleEngines: ["duckdb"],
+		extension: ".java"
+	}
+};
+/** List of all generator names for validation */
+const GENERATOR_NAMES = Object.keys(SUPPORTED_GENERATORS);
+/** SQL annotation syntax reference */
+const SQL_SYNTAX_REFERENCE = `
+SQL Annotation Syntax:
+  -- QUERY <name> [:one] [:pluck]   Select query (returns rows)
+  -- EXEC <name>                    Execute statement (INSERT/UPDATE/DELETE)
+  -- MIGRATE <number>               Schema migration (run in order)
+  -- TESTDATA <name>                Test data setup (not generated)
+
+  @set <varName> = <value>          Define a variable
+  \${varName}                        Reference a variable in SQL
+
+Modifiers:
+  :one    Return single row (or null) instead of array
+  :pluck  Return single column value (requires exactly 1 column)
+  :all    Return all rows (default)
+
+Example:
+  -- MIGRATE 1
+  CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
+
+  -- QUERY get_user :one
+  @set id = 1
+  SELECT * FROM users WHERE id = \${id};
+`.trim();
+/**
+* Find similar generator names for typo suggestions
+*/
+function findSimilarGenerators(input) {
+	const normalized = input.toLowerCase();
+	return GENERATOR_NAMES.filter((name) => {
+		const nameLower = name.toLowerCase();
+		if (nameLower.includes(normalized) || normalized.includes(nameLower)) return true;
+		return [
+			normalized.replace("/", "-"),
+			normalized.replace("-", "/"),
+			normalized.replace("_", "/"),
+			normalized.replace("_", "-")
+		].some((v) => nameLower.includes(v) || v.includes(nameLower));
+	});
+}
+/**
+* Format generators for CLI help output
+*/
+function formatGeneratorsHelp() {
+	return Object.entries(SUPPORTED_GENERATORS).map(([name, info]) => `  ${name.padEnd(28)} ${info.description} (${info.compatibleEngines.join(", ")})`).join("\n");
+}
+/**
+* Format engines for CLI help output
+*/
+function formatEnginesHelp() {
+	return SUPPORTED_ENGINES.map((e) => `  ${e}`).join("\n");
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* Base error class for SQG with structured information
+*/
+var SqgError = class SqgError extends Error {
+	constructor(message, code, suggestion, context) {
+		super(message);
+		this.code = code;
+		this.suggestion = suggestion;
+		this.context = context;
+		this.name = "SqgError";
+	}
+	/**
+	* Create error with file context
+	*/
+	static inFile(message, code, file, options) {
+		return new SqgError(`${message} in ${options?.line ? `${file}:${options.line}` : file}`, code, options?.suggestion, {
+			file,
+			line: options?.line,
+			...options?.context
+		});
+	}
+	/**
+	* Create error with query context
+	*/
+	static inQuery(message, code, queryName, file, options) {
+		return new SqgError(`${message} in query '${queryName}' (${file})`, code, options?.suggestion, {
+			file,
+			query: queryName,
+			sql: options?.sql,
+			...options?.context
+		});
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			suggestion: this.suggestion,
+			context: this.context
+		};
+	}
+};
+/**
+* Error for configuration issues
+*/
+var ConfigError = class extends SqgError {
+	constructor(message, suggestion, context) {
+		super(message, "CONFIG_VALIDATION_ERROR", suggestion, context);
+		this.name = "ConfigError";
+	}
+};
+/**
+* Error for invalid generator names
+*/
+var InvalidGeneratorError = class extends SqgError {
+	constructor(generatorName, validGenerators, suggestion) {
+		const similarMsg = suggestion ? ` Did you mean '${suggestion}'?` : "";
+		super(`Invalid generator '${generatorName}'.${similarMsg} Valid generators: ${validGenerators.join(", ")}`, "INVALID_GENERATOR", suggestion ? `Use '${suggestion}' instead` : `Choose from: ${validGenerators.join(", ")}`, { generator: generatorName });
+		this.name = "InvalidGeneratorError";
+	}
+};
+/**
+* Error for invalid engine names
+*/
+var InvalidEngineError = class extends SqgError {
+	constructor(engineName, validEngines) {
+		super(`Invalid engine '${engineName}'. Valid engines: ${validEngines.join(", ")}`, "INVALID_ENGINE", `Choose from: ${validEngines.join(", ")}`, { engine: engineName });
+		this.name = "InvalidEngineError";
+	}
+};
+/**
+* Error for generator/engine compatibility
+*/
+var GeneratorEngineMismatchError = class extends SqgError {
+	constructor(generator, engine, compatibleEngines) {
+		super(`Generator '${generator}' is not compatible with engine '${engine}'`, "GENERATOR_ENGINE_MISMATCH", `Generator '${generator}' works with: ${compatibleEngines.join(", ")}`, {
+			generator,
+			engine
+		});
+		this.name = "GeneratorEngineMismatchError";
+	}
+};
+/**
+* Error for database initialization/connection issues
+*/
+var DatabaseError = class extends SqgError {
+	constructor(message, engine, suggestion, context) {
+		super(message, "DATABASE_ERROR", suggestion, {
+			engine,
+			...context
+		});
+		this.name = "DatabaseError";
+	}
+};
+/**
+* Error for SQL execution issues
+*/
+var SqlExecutionError = class extends SqgError {
+	constructor(message, queryName, file, sql, originalError) {
+		super(`Failed to execute query '${queryName}' in ${file}: ${message}`, "SQL_EXECUTION_ERROR", void 0, {
+			query: queryName,
+			file,
+			sql,
+			originalError: originalError?.message
+		});
+		this.name = "SqlExecutionError";
+	}
+};
+/**
+* Error for type mapping issues
+*/
+var TypeMappingError = class extends SqgError {
+	constructor(message, columnName, queryName, file) {
+		const location = queryName && file ? ` in query '${queryName}' (${file})` : "";
+		super(`Type mapping error for column '${columnName}'${location}: ${message}`, "TYPE_MAPPING_ERROR", void 0, {
+			columnName,
+			query: queryName,
+			file
+		});
+		this.name = "TypeMappingError";
+	}
+};
+/**
+* Error for file not found
+*/
+var FileNotFoundError = class extends SqgError {
+	constructor(filePath, searchedFrom) {
+		const suggestion = searchedFrom ? `Check that the path is relative to ${searchedFrom}` : "Check that the file path is correct";
+		super(`File not found: ${filePath}`, "FILE_NOT_FOUND", suggestion, { file: filePath });
+		this.name = "FileNotFoundError";
+	}
+};
+/**
+* Format any error for JSON output
+*/
+function formatErrorForOutput(err) {
+	if (err instanceof SqgError) return {
+		status: "error",
+		error: {
+			code: err.code,
+			message: err.message,
+			suggestion: err.suggestion,
+			context: err.context
+		}
+	};
+	if (err instanceof Error) return {
+		status: "error",
+		error: {
+			code: "UNKNOWN_ERROR",
+			message: err.message
+		}
+	};
+	return {
+		status: "error",
+		error: {
+			code: "UNKNOWN_ERROR",
+			message: String(err)
+		}
+	};
+}
+
+//#endregion
 //#region src/parser/sql-parser.ts
 const parser = LRParser.deserialize({
 	version: 14,
@@ -162,17 +419,16 @@ function parseSQLQueries(filePath, extraVariables) {
 					variables.set(varName, extraVariable.value);
 					return extraVariable.value;
 				}
-				throw error(`Variable '${varName}' not found`);
+				const definedVars = Array.from(variables.keys());
+				const suggestion = definedVars.length > 0 ? `Add '@set ${varName} = <value>' before the query. Defined variables: ${definedVars.join(", ")}` : `Add '@set ${varName} = <value>' before the query`;
+				throw SqgError.inQuery(`Variable '\${${varName}}' is referenced but not defined`, "MISSING_VARIABLE", name, filePath, { suggestion });
 			}
 			const sqlNode = cursor.node.getChild("SQLBlock");
-			if (!sqlNode) throw new Error(`'SQLBlock' not found`);
+			if (!sqlNode) throw SqgError.inQuery("SQL block not found", "SQL_PARSE_ERROR", name, filePath, { suggestion: "Ensure the query has valid SQL content after the annotation comment" });
 			const sqlContentStr = nodeStr(sqlNode).trim();
 			const sqlCursor = sqlNode.cursor();
 			let from = -1;
 			let to = -1;
-			function error(message) {
-				return /* @__PURE__ */ new Error(`${message} in ${filePath} query '${name}': ${message}`);
-			}
 			class SQLQueryBuilder {
 				sqlParts = [];
 				appendSql(sql$1) {
@@ -214,33 +470,39 @@ function parseSQLQueries(filePath, extraVariables) {
 				}
 				toSqlWithPositionalPlaceholders() {
 					const parameters = [];
-					return {
-						parameters,
-						sqlParts: [],
-						sql: this.sqlParts.map((part) => {
-							if (typeof part === "string") return part;
-							const varName = part.name;
-							const value = part.value;
+					const sqlParts = [];
+					for (const part of this.sqlParts) if (typeof part === "string") sqlParts.push(part);
+					else {
+						const varName = part.name;
+						const value = part.value;
+						if (varName.startsWith("sources_")) sqlParts.push(part);
+						else {
 							let pos = parameters.findIndex((p) => p.name === varName);
 							if (pos < 0) {
 								parameters.push({
 									name: varName,
 									value
 								});
-								pos = parameters.length - 1;
-							}
-							return ` $${pos + 1} `;
-						}).join("").trim()
+								pos = parameters.length;
+							} else pos = pos + 1;
+							sqlParts.push(`$${pos}`);
+						}
+					}
+					return {
+						parameters,
+						sqlParts,
+						sql: sqlParts.map((part) => typeof part === "string" ? part : ` ${part.value} `).join("").trim()
 					};
 				}
 				toSqlWithNamedPlaceholders() {
+					const sqlParts = [];
+					for (const part of this.sqlParts) if (typeof part === "string") sqlParts.push(part);
+					else if (part.name.startsWith("sources_")) sqlParts.push(part);
+					else sqlParts.push(`$${part.name}`);
 					return {
 						parameters: this.parameters(),
-						sqlParts: [],
-						sql: this.sqlParts.map((part) => {
-							if (typeof part === "string") return part;
-							return `$${part.name}`;
-						}).join("").trim()
+						sqlParts,
+						sql: sqlParts.map((part) => typeof part === "string" ? part : `$${part.name}`).join("").trim()
 					};
 				}
 			}
@@ -256,7 +518,7 @@ function parseSQLQueries(filePath, extraVariables) {
 					}
 					if (child.name === "VarRef") {
 						const varRef = nodeStr(child);
-						if (!varRef.startsWith("${") || !varRef.endsWith("}")) throw error(`Invalid variable reference: ${varRef}`);
+						if (!varRef.startsWith("${") || !varRef.endsWith("}")) throw SqgError.inQuery(`Invalid variable reference: ${varRef}`, "SQL_PARSE_ERROR", name, filePath, { suggestion: "Variables should be in the format ${varName}" });
 						const varName = varRef.replace("${", "").replace("}", "");
 						const value = getVariable(varName);
 						if (to > from) sql.appendSql(content.slice(from, to));
@@ -280,7 +542,7 @@ function parseSQLQueries(filePath, extraVariables) {
 				config
 			});
 			const query = new SQLQuery(filePath, name, sqlContentStr, sql.toSqlWithAnonymousPlaceholders(), sql.toSqlWithNamedPlaceholders(), sql.toSqlWithPositionalPlaceholders(), queryType, isOne, isPluck, variables, config);
-			if (queryNames.has(name)) throw new Error(`Duplicate query name in ${filePath}: ${name}`);
+			if (queryNames.has(name)) throw SqgError.inFile(`Duplicate query name '${name}'`, "DUPLICATE_QUERY", filePath, { suggestion: `Rename one of the queries to have a unique name` });
 			queryNames.add(name);
 			queries.push(query);
 			consola.debug(`Added query: ${name} (${queryType})`);
@@ -322,12 +584,16 @@ const duckdb = new class {
 		this.db = await DuckDBInstance.create(":memory:");
 		this.connection = await this.db.connect();
 		await initializeDatabase(queries, async (query) => {
-			await this.connection.run(query.rawQuery);
+			try {
+				await this.connection.run(query.rawQuery);
+			} catch (e) {
+				throw new SqlExecutionError(e.message, query.id, query.filename, query.rawQuery, e);
+			}
 		});
 	}
 	async executeQueries(queries) {
 		const connection = this.connection;
-		if (!connection) throw new Error("Database not initialized");
+		if (!connection) throw new DatabaseError("DuckDB connection not initialized", "duckdb", "This is an internal error. Check that migrations completed successfully.");
 		try {
 			const executableQueries = queries.filter((q) => !q.skipGenerateFunction);
 			for (const query of executableQueries) {
@@ -400,8 +666,8 @@ const duckdb = new class {
 //#endregion
 //#region src/db/postgres.ts
 const databaseName = "sqg-db-temp";
-const connectionString = "postgresql://sqg:secret@localhost:15432/sqg-db";
-const connectionStringTemp = `postgresql://sqg:secret@localhost:15432/${databaseName}`;
+const connectionString = process.env.SQG_POSTGRES_URL || "postgresql://sqg:secret@localhost:15432/sqg-db";
+const connectionStringTemp = process.env.SQG_POSTGRES_URL ? process.env.SQG_POSTGRES_URL.replace(/\/[^/]+$/, `/${databaseName}`) : `postgresql://sqg:secret@localhost:15432/${databaseName}`;
 const typeIdToName = /* @__PURE__ */ new Map();
 for (const [name, id] of Object.entries(types.builtins)) typeIdToName.set(Number(id), name);
 const postgres = new class {
@@ -410,23 +676,35 @@ const postgres = new class {
 	async initializeDatabase(queries) {
 		this.dbInitial = new Client({ connectionString });
 		this.db = new Client({ connectionString: connectionStringTemp });
-		await this.dbInitial.connect();
+		try {
+			await this.dbInitial.connect();
+		} catch (e) {
+			throw new DatabaseError(`Failed to connect to PostgreSQL: ${e.message}`, "postgres", `Check that PostgreSQL is running and accessible at ${connectionString}. Set SQG_POSTGRES_URL environment variable to use a different connection string.`);
+		}
 		try {
 			await this.dbInitial.query(`DROP DATABASE "${databaseName}";`);
 		} catch (error) {}
 		try {
 			await this.dbInitial.query(`CREATE DATABASE "${databaseName}";`);
 		} catch (error) {
-			consola.error("Error creating database:", error);
+			throw new DatabaseError(`Failed to create temporary database: ${error.message}`, "postgres", "Check PostgreSQL user permissions to create databases");
+		}
+		try {
+			await this.db.connect();
+		} catch (e) {
+			throw new DatabaseError(`Failed to connect to temporary database: ${e.message}`, "postgres");
 		}
-		await this.db.connect();
 		await initializeDatabase(queries, async (query) => {
-			await this.db.query(query.rawQuery);
+			try {
+				await this.db.query(query.rawQuery);
+			} catch (e) {
+				throw new SqlExecutionError(e.message, query.id, query.filename, query.rawQuery, e);
+			}
 		});
 	}
 	async executeQueries(queries) {
 		const db = this.db;
-		if (!db) throw new Error("Database not initialized");
+		if (!db) throw new DatabaseError("PostgreSQL database not initialized", "postgres", "This is an internal error. Check that migrations completed successfully.");
 		try {
 			const executableQueries = queries.filter((q) => !q.skipGenerateFunction);
 			for (const query of executableQueries) {
@@ -488,14 +766,18 @@ const sqlite = new class {
 	async initializeDatabase(queries) {
 		const db = new BetterSqlite3(":memory:");
 		await initializeDatabase(queries, (query) => {
-			db.exec(query.rawQuery);
+			try {
+				db.exec(query.rawQuery);
+			} catch (e) {
+				throw new SqlExecutionError(e.message, query.id, query.filename, query.rawQuery, e);
+			}
 			return Promise.resolve();
 		});
 		this.db = db;
 	}
 	executeQueries(queries) {
 		const db = this.db;
-		if (!db) throw new Error("Database not initialized");
+		if (!db) throw new DatabaseError("SQLite database not initialized", "sqlite", "This is an internal error. Migrations may have failed silently.");
 		try {
 			const executableQueries = queries.filter((q) => !q.skipGenerateFunction);
 			for (const query of executableQueries) {
@@ -582,7 +864,7 @@ var TypeMapper = class {
 		}
 		if (column.type instanceof StructType) return path + this.formatStructTypeName(column.name);
 		if (column.type instanceof MapType) return path + this.formatMapTypeName(column.name);
-		if (!column.type) throw new Error(`Expected ColumnType ${JSON.stringify(column)}`);
+		if (!column.type) throw new TypeMappingError(`Missing type information`, column.name);
 		return this.mapPrimitiveType(column.type.toString(), column.nullable);
 	}
 	/**
@@ -887,8 +1169,15 @@ var TypeScriptTypeMapper = class extends TypeMapper {
 			return `    ${field.name}: ${fieldType};`;
 		}).join("\n")}\n  };\n}`;
 	}
-	parseValue(column, value) {
-		return "/// TODO: parseValue";
+	/**
+	* Generates code to parse/convert a raw DuckDB value to the target TypeScript type.
+	* DuckDB returns complex types with specific wrapper structures that need to be preserved.
+	*/
+	parseValue(column, value, path = "") {
+		if (column.type instanceof ListType) return value;
+		if (column.type instanceof StructType) return value;
+		if (column.type instanceof MapType) return value;
+		return value;
 	}
 };
 
@@ -1292,7 +1581,10 @@ function getGenerator(generator) {
 		case "java/duckdb-arrow": return new JavaDuckDBArrowGenerator("templates/java-duckdb-arrow.hbs");
 		case "typescript/better-sqlite3": return new TsGenerator("templates/better-sqlite3.hbs");
 		case "typescript/duckdb": return new TsDuckDBGenerator("templates/typescript-duckdb.hbs");
-		default: throw new Error(`Unsupported generator: ${generator}`);
+		default: {
+			const similar = findSimilarGenerators(generator);
+			throw new InvalidGeneratorError(generator, [...GENERATOR_NAMES], similar.length > 0 ? similar[0] : void 0);
+		}
 	}
 }
 
@@ -1426,24 +1718,27 @@ function generateSourceFile(name, queries, templatePath, generator, config) {
 		allowProtoMethodsByDefault: true
 	});
 }
+/**
+* Project configuration schema with descriptions for validation messages
+*/
 const ProjectSchema = z.object({
-	version: z.number(),
-	name: z.string(),
+	version: z.number().describe("Configuration version (currently 1)"),
+	name: z.string().min(1, "Project name is required").describe("Project name used for generated class names"),
 	sql: z.array(z.object({
-		engine: z.string(),
-		files: z.array(z.string()),
+		engine: z.enum(SUPPORTED_ENGINES).describe(`Database engine: ${SUPPORTED_ENGINES.join(", ")}`),
+		files: z.array(z.string().min(1)).min(1, "At least one SQL file is required").describe("SQL files to process"),
 		gen: z.array(z.object({
-			generator: z.string(),
-			name: z.string().optional(),
-			template: z.string().optional(),
-			output: z.string(),
-			config: z.any().optional()
-		}))
-	})),
+			generator: z.enum(GENERATOR_NAMES).describe(`Code generator: ${GENERATOR_NAMES.join(", ")}`),
+			name: z.string().optional().describe("Override the generated class/module name"),
+			template: z.string().optional().describe("Custom Handlebars template path"),
+			output: z.string().min(1, "Output path is required").describe("Output file or directory path"),
+			config: z.any().optional().describe("Generator-specific configuration")
+		})).min(1, "At least one generator is required").describe("Code generators to run")
+	})).min(1, "At least one SQL configuration is required").describe("SQL file configurations"),
 	sources: z.array(z.object({
-		path: z.string(),
-		name: z.string().optional()
-	})).optional()
+		path: z.string().describe("Path to source file (supports $HOME)"),
+		name: z.string().optional().describe("Variable name override")
+	})).optional().describe("External source files to include as variables")
 });
 var ExtraVariable = class {
 	constructor(name, value) {
@@ -1460,13 +1755,39 @@ function createExtraVariables(sources) {
 		return new ExtraVariable(varName, `'${resolvedPath}'`);
 	});
 }
+/**
+* Parse and validate project configuration with helpful error messages
+*/
 function parseProjectConfig(filePath) {
-	const content = readFileSync(filePath, "utf-8");
-	const result = ProjectSchema.safeParse(YAML.parse(content));
-	if (!result.success) {
-		const prettyError = z.prettifyError(result.error);
-		throw new Error(`Error parsing project file ${filePath}:\n${prettyError}`);
+	if (!existsSync(filePath)) throw new FileNotFoundError(filePath, process.cwd());
+	let content;
+	try {
+		content = readFileSync(filePath, "utf-8");
+	} catch (e) {
+		throw new SqgError(`Cannot read config file: ${filePath}`, "CONFIG_PARSE_ERROR", "Check file permissions and that the path is correct");
+	}
+	let parsed;
+	try {
+		parsed = YAML.parse(content);
+	} catch (e) {
+		throw new SqgError(`Invalid YAML syntax in ${filePath}: ${e.message}`, "CONFIG_PARSE_ERROR", "Check YAML syntax - common issues: incorrect indentation, missing colons, unquoted special characters");
+	}
+	if (parsed && typeof parsed === "object") {
+		const obj = parsed;
+		if (obj.sql && Array.isArray(obj.sql)) for (let i = 0; i < obj.sql.length; i++) {
+			const sqlConfig = obj.sql[i];
+			if (sqlConfig.engine && !SUPPORTED_ENGINES.includes(sqlConfig.engine)) throw new InvalidEngineError(String(sqlConfig.engine), [...SUPPORTED_ENGINES]);
+			if (sqlConfig.gen && Array.isArray(sqlConfig.gen)) for (let j = 0; j < sqlConfig.gen.length; j++) {
+				const genConfig = sqlConfig.gen[j];
+				if (genConfig.generator && !GENERATOR_NAMES.includes(genConfig.generator)) {
+					const similar = findSimilarGenerators(String(genConfig.generator));
+					throw new InvalidGeneratorError(String(genConfig.generator), [...GENERATOR_NAMES], similar.length > 0 ? similar[0] : void 0);
+				}
+			}
+		}
 	}
+	const result = ProjectSchema.safeParse(parsed);
+	if (!result.success) throw new ConfigError(`Configuration error in ${filePath}:\n${z.prettifyError(result.error)}`, "Check the configuration format against the documentation at https://sqg.dev", { file: filePath });
 	return result.data;
 }
 function detectParameterType(value) {
@@ -1491,7 +1812,7 @@ function getOutputPath(projectDir, sqlFileName, gen, generator) {
 }
 function validateQueries(queries) {
 	for (const query of queries) {
-		if (query.isQuery && query.isPluck && query.columns.length !== 1) throw new Error(`Query ${query.id} in ${query.filename} has the ':pluck: option, must have exactly one column, but has ${query.columns.length} columns`);
+		if (query.isQuery && query.isPluck && query.columns.length !== 1) throw SqgError.inQuery(`':pluck' modifier requires exactly 1 column, but query has ${query.columns.length} columns`, "VALIDATION_ERROR", query.id, query.filename, { suggestion: query.columns.length === 0 ? "Ensure the query returns at least one column" : `Remove ':pluck' or select only one column. Current columns: ${query.columns.map((c) => c.name).join(", ")}` });
 		const columns = query.columns.map((col) => {
 			const configColumn = query.config?.getColumnInfo(col.name);
 			if (configColumn) return configColumn;
@@ -1515,44 +1836,476 @@ async function writeGeneratedFile(projectDir, gen, generator, file, queries) {
 	await generator.afterGenerate(outputPath);
 	return outputPath;
 }
+/**
+* Validate project configuration without executing queries
+* Use this for pre-flight checks before generation
+*/
+async function validateProject(projectPath) {
+	const errors = [];
+	const projectDir = resolve(dirname(projectPath));
+	let project;
+	try {
+		project = parseProjectConfig(projectPath);
+	} catch (e) {
+		if (e instanceof SqgError) return {
+			valid: false,
+			errors: [{
+				code: e.code,
+				message: e.message,
+				suggestion: e.suggestion,
+				context: e.context
+			}]
+		};
+		return {
+			valid: false,
+			errors: [{
+				code: "UNKNOWN_ERROR",
+				message: String(e)
+			}]
+		};
+	}
+	const sqlFiles = [];
+	const generators = [];
+	for (const sql of project.sql) for (const sqlFile of sql.files) {
+		const fullPath = join(projectDir, sqlFile);
+		sqlFiles.push(sqlFile);
+		if (!existsSync(fullPath)) errors.push({
+			code: "FILE_NOT_FOUND",
+			message: `SQL file not found: ${sqlFile}`,
+			suggestion: `Check that ${sqlFile} exists relative to ${projectDir}`,
+			context: { file: fullPath }
+		});
+		for (const gen of sql.gen) {
+			generators.push(gen.generator);
+			if (!SUPPORTED_GENERATORS[gen.generator].compatibleEngines.includes(sql.engine)) errors.push({
+				code: "GENERATOR_ENGINE_MISMATCH",
+				message: `Generator '${gen.generator}' is not compatible with engine '${sql.engine}'`,
+				suggestion: `For '${sql.engine}', use one of: ${Object.entries(SUPPORTED_GENERATORS).filter(([_, info]) => info.compatibleEngines.includes(sql.engine)).map(([name]) => name).join(", ")}`,
+				context: {
+					generator: gen.generator,
+					engine: sql.engine
+				}
+			});
+		}
+	}
+	return {
+		valid: errors.length === 0,
+		project: {
+			name: project.name,
+			version: project.version
+		},
+		sqlFiles: [...new Set(sqlFiles)],
+		generators: [...new Set(generators)],
+		errors: errors.length > 0 ? errors : void 0
+	};
+}
+/**
+* Process a project configuration and generate code
+*/
 async function processProject(projectPath) {
 	const projectDir = resolve(dirname(projectPath));
 	const project = parseProjectConfig(projectPath);
 	const extraVariables = createExtraVariables(project.sources ?? []);
 	if (extraVariables.length > 0) consola.info("Extra variables:", extraVariables);
 	const files = [];
-	for (const sql of project.sql) for (const sqlFile of sql.files) {
-		let queries;
-		try {
-			queries = parseSQLQueries(join(projectDir, sqlFile), extraVariables);
-			const dbEngine = getDatabaseEngine(sql.engine);
-			await dbEngine.initializeDatabase(queries);
-			await dbEngine.executeQueries(queries);
-			validateQueries(queries);
-			await dbEngine.close();
-		} catch (e) {
-			consola.error(`Error processing SQL file ${sqlFile}: ${e}`);
-			throw e;
-		}
+	for (const sql of project.sql) {
 		for (const gen of sql.gen) {
-			const generator = getGenerator(gen.generator);
-			if (!generator.isCompatibleWith(sql.engine)) throw new Error(`File ${sqlFile}: Generator ${gen.generator} is not compatible with engine ${sql.engine}`);
-			const outputPath = await writeGeneratedFile(projectDir, gen, generator, sqlFile, queries);
-			files.push(outputPath);
+			const generatorInfo = SUPPORTED_GENERATORS[gen.generator];
+			if (!generatorInfo.compatibleEngines.includes(sql.engine)) throw new GeneratorEngineMismatchError(gen.generator, sql.engine, generatorInfo.compatibleEngines);
+		}
+		for (const sqlFile of sql.files) {
+			const fullPath = join(projectDir, sqlFile);
+			if (!existsSync(fullPath)) throw new FileNotFoundError(fullPath, projectDir);
+			let queries;
+			try {
+				queries = parseSQLQueries(fullPath, extraVariables);
+			} catch (e) {
+				if (e instanceof SqgError) throw e;
+				throw SqgError.inFile(`Failed to parse SQL file: ${e.message}`, "SQL_PARSE_ERROR", sqlFile, { suggestion: "Check SQL syntax and annotation format" });
+			}
+			try {
+				const dbEngine = getDatabaseEngine(sql.engine);
+				await dbEngine.initializeDatabase(queries);
+				await dbEngine.executeQueries(queries);
+				validateQueries(queries);
+				await dbEngine.close();
+			} catch (e) {
+				if (e instanceof SqgError) throw e;
+				throw new SqgError(`Database error processing ${sqlFile}: ${e.message}`, "DATABASE_ERROR", `Check that the SQL is valid for engine '${sql.engine}'`, {
+					file: sqlFile,
+					engine: sql.engine
+				});
+			}
+			for (const gen of sql.gen) {
+				const outputPath = await writeGeneratedFile(projectDir, gen, getGenerator(gen.generator), sqlFile, queries);
+				files.push(outputPath);
+			}
 		}
 	}
 	return files;
 }
 
+//#endregion
+//#region src/init.ts
+/**
+* SQG Project Initialization - Creates new SQG projects with example files
+*/
+/**
+* Get the default generator for an engine
+*/
+function getDefaultGenerator(engine) {
+	return {
+		sqlite: "typescript/better-sqlite3",
+		duckdb: "typescript/duckdb",
+		postgres: "java/jdbc"
+	}[engine];
+}
+/**
+* Generate example SQL content based on engine
+*/
+function getExampleSql(engine) {
+	return {
+		sqlite: `-- MIGRATE 1
+-- Create the users table (SQG Example - https://sqg.dev/guides/sql-syntax/)
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  email TEXT UNIQUE NOT NULL,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+-- MIGRATE 2
+CREATE TABLE posts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL REFERENCES users(id),
+  title TEXT NOT NULL,
+  content TEXT,
+  published INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+-- TESTDATA seed_data
+INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');
+INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
+INSERT INTO posts (user_id, title, content, published) VALUES (1, 'Hello World', 'My first post!', 1);
+`,
+		duckdb: `-- MIGRATE 1
+-- Create the users table (SQG Example - https://sqg.dev/guides/sql-syntax/)
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  name VARCHAR NOT NULL,
+  email VARCHAR UNIQUE NOT NULL,
+  metadata STRUCT(role VARCHAR, active BOOLEAN),
+  tags VARCHAR[],
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- MIGRATE 2
+CREATE TABLE posts (
+  id INTEGER PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id),
+  title VARCHAR NOT NULL,
+  content VARCHAR,
+  published BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- TESTDATA seed_data
+INSERT INTO users (id, name, email, metadata, tags)
+VALUES (1, 'Alice', 'alice@example.com', {'role': 'admin', 'active': true}, ['developer', 'lead']);
+INSERT INTO users (id, name, email, metadata, tags)
+VALUES (2, 'Bob', 'bob@example.com', {'role': 'user', 'active': true}, ['developer']);
+INSERT INTO posts (id, user_id, title, content, published)
+VALUES (1, 1, 'Hello World', 'My first post!', TRUE);
+`,
+		postgres: `-- MIGRATE 1
+-- Create the users table (SQG Example - https://sqg.dev/guides/sql-syntax/)
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT UNIQUE NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- MIGRATE 2
+CREATE TABLE posts (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id),
+  title TEXT NOT NULL,
+  content TEXT,
+  published BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- TESTDATA seed_data
+INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');
+INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
+INSERT INTO posts (user_id, title, content, published) VALUES (1, 'Hello World', 'My first post!', TRUE);
+`
+	}[engine] + `
+-- QUERY list_users
+SELECT id, name, email, created_at
+FROM users
+ORDER BY created_at DESC;
+
+-- QUERY get_user_by_id :one
+@set id = 1
+SELECT id, name, email, created_at
+FROM users
+WHERE id = \${id};
+
+-- QUERY get_user_by_email :one
+@set email = 'alice@example.com'
+SELECT id, name, email, created_at
+FROM users
+WHERE email = \${email};
+
+-- QUERY count_users :one :pluck
+SELECT COUNT(*) FROM users;
+
+-- QUERY list_posts_by_user
+@set user_id = 1
+SELECT p.id, p.title, p.content, p.published, p.created_at
+FROM posts p
+WHERE p.user_id = \${user_id}
+ORDER BY p.created_at DESC;
+
+-- QUERY list_published_posts
+SELECT
+  p.id,
+  p.title,
+  p.content,
+  p.created_at,
+  u.name as author_name,
+  u.email as author_email
+FROM posts p
+JOIN users u ON p.user_id = u.id
+WHERE p.published = 1
+ORDER BY p.created_at DESC;
+` + {
+		sqlite: `
+-- EXEC create_user
+@set name = 'New User'
+@set email = 'new@example.com'
+INSERT INTO users (name, email)
+VALUES (\${name}, \${email});
+
+-- EXEC create_post
+@set user_id = 1
+@set title = 'New Post'
+@set content = 'Post content here'
+INSERT INTO posts (user_id, title, content)
+VALUES (\${user_id}, \${title}, \${content});
+
+-- EXEC publish_post
+@set id = 1
+UPDATE posts SET published = 1 WHERE id = \${id};
+
+-- EXEC delete_post
+@set id = 1
+DELETE FROM posts WHERE id = \${id};
+`,
+		duckdb: `
+-- EXEC create_user
+@set id = 100
+@set name = 'New User'
+@set email = 'new@example.com'
+INSERT INTO users (id, name, email)
+VALUES (\${id}, \${name}, \${email});
+
+-- EXEC create_post
+@set id = 100
+@set user_id = 1
+@set title = 'New Post'
+@set content = 'Post content here'
+INSERT INTO posts (id, user_id, title, content)
+VALUES (\${id}, \${user_id}, \${title}, \${content});
+
+-- EXEC publish_post
+@set id = 1
+UPDATE posts SET published = TRUE WHERE id = \${id};
+
+-- EXEC delete_post
+@set id = 1
+DELETE FROM posts WHERE id = \${id};
+`,
+		postgres: `
+-- EXEC create_user
+@set name = 'New User'
+@set email = 'new@example.com'
+INSERT INTO users (name, email)
+VALUES (\${name}, \${email});
+
+-- EXEC create_post
+@set user_id = 1
+@set title = 'New Post'
+@set content = 'Post content here'
+INSERT INTO posts (user_id, title, content)
+VALUES (\${user_id}, \${title}, \${content});
+
+-- EXEC publish_post
+@set id = 1
+UPDATE posts SET published = TRUE WHERE id = \${id};
+
+-- EXEC delete_post
+@set id = 1
+DELETE FROM posts WHERE id = \${id};
+`
+	}[engine];
+}
+/**
+* Generate sqg.yaml configuration
+*/
+function getConfigYaml(engine, generator, output) {
+	SUPPORTED_GENERATORS[generator];
+	const config = {
+		version: 1,
+		name: "my-project",
+		sql: [{
+			engine,
+			files: ["queries.sql"],
+			gen: [{
+				generator,
+				output: output.endsWith("/") ? output : `${output}/`
+			}]
+		}]
+	};
+	if (generator.startsWith("java/")) config.sql[0].gen[0].config = { package: "generated" };
+	return `# SQG Configuration
+# Generated by: sqg init
+# Documentation: https://sqg.dev
+
+version: 1
+name: my-project
+
+sql:
+  - engine: ${engine}
+    files:
+      - queries.sql
+    gen:
+      - generator: ${generator}
+        output: ${output.endsWith("/") ? output : `${output}/`}${generator.startsWith("java/") ? `
+        config:
+          package: generated` : ""}
+`;
+}
+/**
+* Initialize a new SQG project
+*/
+async function initProject(options) {
+	const engine = options.engine || "sqlite";
+	const output = options.output || "./generated";
+	if (!SUPPORTED_ENGINES.includes(engine)) throw new InvalidEngineError(engine, [...SUPPORTED_ENGINES]);
+	let generator;
+	if (options.generator) {
+		if (!(options.generator in SUPPORTED_GENERATORS)) {
+			const similar = findSimilarGenerators(options.generator);
+			throw new InvalidGeneratorError(options.generator, Object.keys(SUPPORTED_GENERATORS), similar.length > 0 ? similar[0] : void 0);
+		}
+		generator = options.generator;
+		if (!SUPPORTED_GENERATORS[generator].compatibleEngines.includes(engine)) throw new SqgError(`Generator '${generator}' is not compatible with engine '${engine}'`, "GENERATOR_ENGINE_MISMATCH", `For '${engine}', use one of: ${Object.entries(SUPPORTED_GENERATORS).filter(([_, info]) => info.compatibleEngines.includes(engine)).map(([name]) => name).join(", ")}`);
+	} else generator = getDefaultGenerator(engine);
+	const configPath = "sqg.yaml";
+	const sqlPath = "queries.sql";
+	if (!options.force) {
+		if (existsSync(configPath)) throw new SqgError(`File already exists: ${configPath}`, "VALIDATION_ERROR", "Use --force to overwrite existing files");
+		if (existsSync(sqlPath)) throw new SqgError(`File already exists: ${sqlPath}`, "VALIDATION_ERROR", "Use --force to overwrite existing files");
+	}
+	if (!existsSync(output)) {
+		mkdirSync(output, { recursive: true });
+		consola.success(`Created output directory: ${output}`);
+	}
+	writeFileSync(configPath, getConfigYaml(engine, generator, output));
+	consola.success(`Created ${configPath}`);
+	writeFileSync(sqlPath, getExampleSql(engine));
+	consola.success(`Created ${sqlPath}`);
+	consola.box(`
+SQG project initialized!
+
+Engine:    ${engine}
+Generator: ${generator}
+Output:    ${output}
+
+Next steps:
+  1. Edit queries.sql to add your SQL queries
+  2. Run: sqg sqg.yaml
+  3. Import the generated code from ${output}
+
+Documentation: https://sqg.dev
+  `);
+}
+
 //#endregion
 //#region src/sqg.ts
-const version = process.env.npm_package_version ?? "0.1.1";
+const version = process.env.npm_package_version ?? "0.2.1";
 const description = process.env.npm_package_description ?? "SQG - SQL Query Generator - Type-safe code generation from SQL (https://sqg.dev)";
 consola.level = LogLevels.info;
-const program = new Command().name("sqg").description(description).version(version, "-v, --version", "output the version number").option("--verbose", "Enable debug logging").argument("<project>", "Path to the project YAML config").showHelpAfterError().showSuggestionAfterError().hook("preAction", (thisCommand) => {
-	if (thisCommand.opts().verbose) consola.level = LogLevels.debug;
-}).action(async (projectPath) => {
-	await processProject(projectPath);
+const program = new Command().name("sqg").description(`${description}
+
+Generate type-safe database access code from annotated SQL files.
+
+Supported Engines:
+${formatEnginesHelp()}
+
+Supported Generators:
+${formatGeneratorsHelp()}`).version(version, "-v, --version", "output the version number").option("--verbose", "Enable debug logging (shows SQL execution details)").option("--format <format>", "Output format: text (default) or json", "text").option("--validate", "Validate configuration without generating code").showHelpAfterError().showSuggestionAfterError();
+program.argument("<project>", "Path to the project YAML config (sqg.yaml)").hook("preAction", (thisCommand) => {
+	const opts = thisCommand.opts();
+	if (opts.verbose) consola.level = LogLevels.debug;
+	if (opts.format === "json") consola.level = LogLevels.silent;
+}).action(async (projectPath, options) => {
+	try {
+		if (options.validate) {
+			const result = await validateProject(projectPath);
+			if (options.format === "json") console.log(JSON.stringify(result, null, 2));
+			else if (result.valid) {
+				consola.success("Configuration is valid");
+				consola.info(`Project: ${result.project?.name}`);
+				consola.info(`SQL files: ${result.sqlFiles?.join(", ")}`);
+				consola.info(`Generators: ${result.generators?.join(", ")}`);
+			} else {
+				consola.error("Validation failed");
+				for (const error of result.errors || []) {
+					consola.error(`  ${error.message}`);
+					if (error.suggestion) consola.info(`    Suggestion: ${error.suggestion}`);
+				}
+			}
+			exit(result.valid ? 0 : 1);
+		}
+		const files = await processProject(projectPath);
+		if (options.format === "json") console.log(JSON.stringify({
+			status: "success",
+			generatedFiles: files
+		}));
+	} catch (err) {
+		if (options.format === "json") console.log(JSON.stringify(formatErrorForOutput(err)));
+		else if (err instanceof SqgError) {
+			consola.error(err.message);
+			if (err.suggestion) consola.info(`Suggestion: ${err.suggestion}`);
+			if (err.context && options.verbose) consola.debug("Context:", err.context);
+		} else consola.error(err);
+		exit(1);
+	}
+});
+program.command("init").description("Initialize a new SQG project with example configuration").option("-e, --engine <engine>", `Database engine (${SUPPORTED_ENGINES.join(", ")})`, "sqlite").option("-g, --generator <generator>", `Code generator (${GENERATOR_NAMES.join(", ")})`).option("-o, --output <dir>", "Output directory for generated files", "./generated").option("-f, --force", "Overwrite existing files").action(async (options) => {
+	const parentOpts = program.opts();
+	try {
+		await initProject(options);
+		if (parentOpts.format === "json") console.log(JSON.stringify({
+			status: "success",
+			message: "Project initialized"
+		}));
+	} catch (err) {
+		if (parentOpts.format === "json") console.log(JSON.stringify(formatErrorForOutput(err)));
+		else if (err instanceof SqgError) {
+			consola.error(err.message);
+			if (err.suggestion) consola.info(`Suggestion: ${err.suggestion}`);
+		} else consola.error(err);
+		exit(1);
+	}
+});
+program.command("syntax").description("Show SQL annotation syntax reference").action(() => {
+	console.log(SQL_SYNTAX_REFERENCE);
 });
 if (process.argv.length <= 2) {
 	program.outputHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqg/sqg",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "SQG - SQL Query Generator - Type-safe code generation from SQL (https://sqg.dev)",
   "type": "module",
   "bin": {
@@ -20,7 +20,21 @@
   "bugs": {
     "url": "https://github.com/sqg-dev/sqg/issues"
   },
-  "keywords": [],
+  "keywords": [
+    "sql",
+    "codegen",
+    "code-generation",
+    "typescript",
+    "java",
+    "sqlite",
+    "duckdb",
+    "postgres",
+    "postgresql",
+    "type-safe",
+    "database",
+    "orm-alternative",
+    "query-builder"
+  ],
   "author": "Uwe Maurer",
   "license": "Apache-2.0",
   "dependencies": {