@housekit/kit 0.1.16 → 0.1.19

package/README.md

@@ -15,6 +15,7 @@ HouseKit CLI brings a modern, streamlined developer experience to the ClickHouse
 
 - **Declarative Workflows**: Define your source of truth in TypeScript.
 - **Automatic Drift Detection**: Compares your code against the live DB schema instantly.
+- **Engine-Aware Diffing**: Normalizes local engine objects vs. remote SQL to avoid false changes.
 - **Blue-Green Deployments**: Safe, zero-downtime structural changes for Materialized Views and Tables.
 - **Cluster Awareness**: First-class support for sharded clusters using `{cluster}` macros and sharding keys.
 - **Zero Runtime Dependencies**: Powered by `jiti` for native TS loading—no pre-compilation or heavy binaries required.
@@ -104,8 +105,14 @@ export default {
 HouseKit simplifies managing Replicated and Distributed tables across a cluster.
 
 ```typescript
-// Define a table that lives on a cluster
-export const events = defineTable('events', { ... }, {
+import { defineTable, t, Engine } from '@housekit/orm';
+
+// Define a table that lives on a cluster (object syntax still supported)
+export const events = defineTable('events', {
+  id: t.uuid('id').primaryKey(),
+  userId: t.uuid('user_id'),
+  createdAt: t.timestamp('created_at').default('now()'),
+}, {
   engine: Engine.ReplicatedMergeTree(),
   
   // High Portability: Using '{cluster}' tells ClickHouse to use the 
@@ -116,6 +123,9 @@ export const events = defineTable('events', { ... }, {
   shardKey: 'user_id',
   orderBy: 'id'
 });
+
+// Callback syntax is also available when you want presets or composition:
+// defineTable('events', (t) => ({ ... }), { ... })
 ```
 When you run `housekit push`, the CLI automatically detects the cluster configuration and executes the `ALTER` or `CREATE` statements across all nodes using the specified macro.
 
@@ -131,6 +141,7 @@ Have an existing database with 100 tables? Don't write the code by hand.
 bunx housekit pull --database production
 ```
 This will scan your ClickHouse instance and generate a clean, readable `schema.ts` file with all table definitions, engines, and settings preserved.
+Engine strings from ClickHouse are stored as `customEngine` to guarantee a lossless round-trip.
 
 ---
 
@@ -144,4 +155,4 @@ This will scan your ClickHouse instance and generate a clean, readable `schema.t
 
 ## License
 
-MIT © [Pablo Fernandez Ruiz](https://github.com/pablofdezr)
+MIT © [Pablo Fernandez Ruiz](https://github.com/pablofdezr)

package/dist/index.js

@@ -6004,7 +6004,7 @@ function resolveDatabase(config, name) {
 import { detectMaterializedViewDrift, extractMVQuery } from "@housekit/orm";
 
 // src/schema/diff.ts
-import { normalizeHousekitMetadata, upgradeMetadataVersion } from "@housekit/orm";
+import { normalizeHousekitMetadata, upgradeMetadataVersion, renderEngineSQL } from "@housekit/orm";
 function columnType(col) {
   return col.toSQL();
 }
@@ -6290,9 +6290,20 @@ function diffTable(table, localCols, remote, opts) {
       warnings.push(`${label} differs (remote="${r || "unset"}", local="${l || "unset"}")`);
     }
   };
-  compare("engine", localOpts.engine || "MergeTree", remoteOpts.engine, () => {
-    destructiveReasons.push("engine change (requires shadow swap)");
-  });
+  let localEngineSQL = "MergeTree";
+  if (localOpts.customEngine) {
+    localEngineSQL = localOpts.customEngine;
+  } else if (localOpts.engine) {
+    localEngineSQL = renderEngineSQL(localOpts.engine);
+  }
+  const normalizeEngine = (engine) => engine.replace(/\s+/g, "").replace(/\(\)/g, "").toLowerCase();
+  const localEngineNorm = normalizeEngine(localEngineSQL);
+  const remoteEngineNorm = normalizeEngine(remoteOpts.engine || "MergeTree");
+  if (localEngineNorm !== remoteEngineNorm) {
+    optionChanges.push("engine");
+    destructiveReasons.push(`engine change (local="${localEngineSQL}", remote="${remoteOpts.engine}") (requires shadow swap)`);
+    warnings.push("Engine mismatch requires full table recreation");
+  }
   compare("orderBy", localOpts.orderBy, remoteOpts.orderBy, () => {
     destructiveReasons.push("order by change");
     plan.push(`ALTER TABLE \`${tableName}\` MODIFY ORDER BY (${normalizeClause(localOpts.orderBy)})`);
@@ -7314,7 +7325,11 @@ function extractHousekitMetadata2(comment) {
   }
   return null;
 }
-function buildTableFile(table, columns, format3 = "ts", metadata) {
+function extractEngineFromCreate(statement) {
+  const match2 = statement.match(/ENGINE\s*=\s*(.+?)(\s+(?:ORDER|PARTITION|PRIMARY|SAMPLE|TTL|SETTINGS|COMMENT)|$)/i);
+  return match2 ? match2[1].trim() : "MergeTree()";
+}
+function buildTableFile(table, columns, engineSQL, format3 = "ts", metadata) {
   const mappedColumns = columns.map((col) => ({
     name: col.name,
     comment: col.comment,
@@ -7341,6 +7356,8 @@ function buildTableFile(table, columns, format3 = "ts", metadata) {
   const comment = `// Auto-generated on ${timestamp}
 `;
   const optionLines = [];
+  const escapedEngine = engineSQL.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+  optionLines.push(`    customEngine: "${escapedEngine}"`);
   if (metadata?.version) {
     optionLines.push(`    metadataVersion: "${metadata.version}"`);
   } else {
@@ -7359,9 +7376,12 @@ ${optionLines.join(`,
   const exportStatement = `export const ${variableName} = defineTable('${table}', (t) => ({
 ${columnLines}
 })${optionsBlock});`;
-  return `${comment}import { t, defineTable, Engine } from '@housekit/orm';
+  const importLine = `import { t, defineTable, Engine } from '@housekit/orm';`;
+  const typeAlias = `
+`;
+  return `${comment}${importLine}
 
-${exportStatement}
+${exportStatement}${typeAlias}
 `;
 }
 function persistLanguagePreference(configPath, lang) {
@@ -7543,6 +7563,7 @@ async function pullCommand(options) {
         const createParsed = await createResult.json();
         const createRows = Array.isArray(createParsed) ? createParsed : createParsed?.data ?? [];
         const createStatement = Array.isArray(createRows) && createRows.length > 0 ? createRows[0]?.statement || "" : "";
+        const engineSQL = extractEngineFromCreate(createStatement);
         let tableMetadata = null;
         try {
           const commentRes = await client.query({
@@ -7691,7 +7712,7 @@ async function pullCommand(options) {
             comment: commentFromDescribe || commentFromCreate
           };
         });
-        const content = buildTableFile(tableName, columns, fileFormat, tableMetadata);
+        const content = buildTableFile(tableName, columns, engineSQL, fileFormat, tableMetadata);
         writeFileSync3(join4(targetDir, `${tableName}.${fileExtension}`), content);
         describeSpinner.stop();
         success(`Wrote schema file for ${quoteName(tableName)}`);
@@ -8764,22 +8785,25 @@ export default {
     mkdirSync4(schemaPath, { recursive: true });
     success(`Created schema directory: ${quoteName(schemaPath)}`);
     const exampleSchemaPath = join7(schemaPath, `logs.${fileType}`);
+    const importLine = `import { t, defineTable, Engine } from '@housekit/orm';`;
+    const typeAliasLine = `
+`;
     const exampleSchemaContent = `// Example table - This is a sample schema file to demonstrate HouseKit usage
-import { t, defineTable, Engine } from '@housekit/orm';
+${importLine}
 
-export const logs = defineTable('logs', {
+export const logs = defineTable('logs', (t) => ({
     id: t.uuid('id').autoGenerate().primaryKey(),
     message: t.string('message').comment('Log message content'),
     level: t.enum('level', ['info', 'warning', 'error']).default('info').comment('Log severity level'),
     tags: t.array(t.string('tag')).nullable().comment('Array of tags for categorizing logs'),
     metadata: t.json('metadata').nullable().comment('Additional log metadata'),
     createdAt: t.timestamp('created_at').default('now()'),
-}, {
+}), {
     engine: Engine.MergeTree(),
     orderBy: ['createdAt', 'id'],
     appendOnly: false
 });
-`;
+${typeAliasLine}`;
     writeFileSync4(exampleSchemaPath, exampleSchemaContent);
     info(`Created example schema: ${quoteName(exampleSchemaPath)}`);
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@housekit/kit",
-    "version": "0.1.16",
+    "version": "0.1.19",
     "description": "CLI tool for HouseKit - manage ClickHouse schemas, migrations, and database operations with type-safe workflows.",
     "type": "module",
     "main": "./dist/index.js",
@@ -48,7 +48,7 @@
     },
     "dependencies": {
         "@clickhouse/client": "^1.14.0",
-        "@housekit/orm": "^0.1.16",
+        "@housekit/orm": "workspace:*",
         "chalk": "^5.6.2",
         "cli-table3": "^0.6.5",
         "commander": "^12.0.0",