@housekit/kit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pablo Fernandez Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# HouseKit CLI 🏠⚡️
+
+**The modern schema management tool for ClickHouse.**
+
+HouseKit CLI brings a modern, streamlined developer experience to the ClickHouse ecosystem. Manage your sharded clusters, analytical tables, and complex materialized views using purely TypeScript—no more manual SQL migration files or structural drift.
+
+[![npm version](https://img.shields.io/npm/v/housekit.svg)](https://www.npmjs.com/package/housekit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🚀 Why HouseKit CLI?
+
+- **Declarative Workflows**: Define your source of truth in TypeScript.
+- **Automatic Drift Detection**: Compares your code against the live DB schema instantly.
+- **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.
+
+---
+
+## 🛠 Installation
+
+```bash
+# Recommended: install as a dev dependency
+npm install -D @housekit/kit @housekit/orm
+# or
+bun add -D @housekit/kit @housekit/orm
+```
+
+---
+
+## 📖 The Two Workflows
+
+HouseKit supports two distinct ways of working depending on your environment.
+
+### 1. Rapid Development: `housekit push`
+Perfect for early-stage projects or local development. It computes the delta between your TS files and the database and applies it immediately.
+- **Safe**: Asks for confirmation before any destructive change.
+- **Fast**: Skips the creation of migration files.
+- **Smart**: Handles column renames and type changes.
+
+### 2. Controlled Production: `housekit generate` & `migrate`
+The standard for CI/CD and production environments.
+- **Generate**: Compares your code against a `snapshot.json` and creates a timestamped `.sql` file in your migrations folder.
+- **Migrate**: Executes pending SQL files against the target database, tracking history in `system.migrations`.
+
+---
+
+## 💻 Commands
+
+| Command | Description |
+| :--- | :--- |
+| `init` | Bootstraps a new HouseKit project with config and folder structure. |
+| `push` | Syncs local schema directly to the database. Supports `--log-explain`. |
+| `generate` | Creates a new SQL migration file based on schema changes. |
+| `migrate` | Applies pending SQL migrations to the database. |
+| `pull` | **Introspection**: Connects to a DB and generates typed TS schema files. |
+| `schema` | Prints a beautiful, color-coded summary of your tables and types. |
+| `status` | Lists all detected differences between your code and the database. |
+| `validate` | Checks if code and DB are in sync (exit code 1 on drift). Great for CI. |
+| `list` | Summarizes row counts, engines, and sizes for all tables. |
+| `reset` | Wipes the database and restarts from your code schema (Dev only). |
+
+---
+
+## ⚙️ Configuration
+
+Create a `housekit.config.ts` (or `.js`, `.mjs`) in your project root.
+
+```typescript
+import type { HouseKitConfig } from 'housekit';
+
+export default {
+  // Path to your table/view definitions
+  schema: './src/schema',
+  
+  // Where migrations and snapshots will be stored
+  out: './housekit',
+  
+  // Multi-database support
+  databases: {
+    default: {
+      host: 'localhost',
+      port: 8123,
+      database: 'analytics_dev',
+      username: 'default',
+      password: process.env.CLICKHOUSE_PASSWORD || '',
+    },
+    production: {
+      url: process.env.CLICKHOUSE_PROD_URL,
+      database: 'analytics_prod',
+    }
+  }
+} satisfies HouseKitConfig;
+```
+
+---
+
+## 🏗 Advanced Usage
+
+### Working with Clusters
+HouseKit simplifies managing Replicated and Distributed tables across a cluster.
+
+```typescript
+// Define a table that lives on a cluster
+export const events = defineTable('events', { ... }, {
+  engine: Engine.ReplicatedMergeTree(),
+  
+  // High Portability: Using '{cluster}' tells ClickHouse to use the 
+  // cluster name defined in the server's configuration macros.
+  // This allows the same code to run on 'dev_cluster', 'prod_cluster', etc.
+  onCluster: '{cluster}', 
+  
+  shardKey: 'user_id',
+  orderBy: 'id'
+});
+```
+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.
+
+### Safe Materialized View Updates
+ClickHouse doesn't allow `ALTER` on Materialized View queries. HouseKit solves this via **Blue-Green Deployments**:
+1. Creates a `__shadow` table with the new query.
+2. Swaps the names atomically using `RENAME`.
+3. Ensures zero data loss during the transition.
+
+### Database Introspection (`pull`)
+Have an existing database with 100 tables? Don't write the code by hand.
+```bash
+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.
+
+---
+
+## 🛡 Security & Best Practices
+
+- **Credentials**: Never hardcode passwords. Use `process.env`.
+- **Read-Only Mode**: In `housekit.config.ts`, you can mark databases as `readOnly: true` to prevent accidental `push` or `migrate` calls.
+- **Validation**: Add `housekit validate` to your CI pipeline to ensure no developer forgot to generate a migration before merging.
+
+---
+
+## License
+
+MIT © [Pablo Fernandez Ruiz](https://github.com/pablofdezr)

package/dist/commands/check.d.ts

@@ -0,0 +1 @@
+export declare function checkCommand(): Promise<void>;

package/dist/commands/drop.d.ts

@@ -0,0 +1,4 @@
+export declare function dropCommand(options: {
+    database?: string;
+    tables?: string;
+}): Promise<void>;

package/dist/commands/dry-run.d.ts

@@ -0,0 +1,3 @@
+export declare function dryRunCommand(options: {
+    database?: string;
+}): Promise<void>;

package/dist/commands/generate.d.ts

@@ -0,0 +1 @@
+export declare function generateCommand(): Promise<void>;

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(): Promise<void>;

package/dist/commands/list.d.ts

@@ -0,0 +1,3 @@
+export declare function listCommand(options: {
+    database?: string;
+}): Promise<void>;

package/dist/commands/migrate.d.ts

@@ -0,0 +1,3 @@
+export declare function migrateCommand(options: {
+    database?: string;
+}): Promise<void>;

package/dist/commands/pull.d.ts

@@ -0,0 +1,3 @@
+export declare function pullCommand(options: {
+    database?: string;
+}): Promise<void>;

package/dist/commands/push.d.ts

@@ -0,0 +1,5 @@
+export declare function pushCommand(options: {
+    database?: string;
+    logExplain?: boolean;
+    autoUpgradeMetadata?: boolean;
+}): Promise<void>;

package/dist/commands/reset.d.ts

@@ -0,0 +1,3 @@
+export declare function resetCommand(options: {
+    database?: string;
+}): Promise<void>;

package/dist/commands/schema.d.ts

@@ -0,0 +1,4 @@
+export declare function schemaCommand(options: {
+    database?: string;
+    tables?: string[];
+}): Promise<void>;

package/dist/commands/status.d.ts

@@ -0,0 +1,3 @@
+export declare function statusCommand(options: {
+    database?: string;
+}): Promise<void>;

package/dist/commands/truncate.d.ts

@@ -0,0 +1,4 @@
+export declare function truncateCommand(options: {
+    database?: string;
+    tables?: string;
+}): Promise<void>;

package/dist/commands/validate.d.ts

@@ -0,0 +1,4 @@
+export declare function validateCommand(options: {
+    database?: string;
+    autoUpgradeMetadata?: boolean;
+}): Promise<void>;

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+export interface DatabaseConnection {
+    host?: string;
+    port?: number;
+    database: string;
+    username?: string;
+    password?: string;
+    url?: string;
+}
+export interface HouseKitConfig {
+    /**
+     * Path to the directory containing your schema files (.ts or .js).
+     * Can be a single path or a mapping for multiple databases.
+     */
+    schema: string | Record<string, string>;
+    /**
+     * Directory where SQL migrations and snapshots will be generated.
+     */
+    out: string;
+    language?: 'ts' | 'js';
+    /**
+     * ClickHouse connection configuration.
+     * Each key represents the database name you will use in the CLI with `--database`.
+     */
+    databases: Record<string, DatabaseConnection>;
+}
+export type { HouseKitConfig as default };
+/**
+ * Helper to get all database configurations
+ */
+export declare function getDatabaseConfigs(config: HouseKitConfig): Record<string, DatabaseConnection>;
+/**
+ * Helper to get schema paths mapped to databases
+ */
+export declare function getSchemaMapping(config: HouseKitConfig): Record<string, string>;

package/dist/db.d.ts

@@ -0,0 +1,8 @@
+import { type ClickHouseClient } from '@clickhouse/client';
+import { type HouseKitConfig } from './config';
+export interface ResolvedDatabase {
+    name: string;
+    client: ClickHouseClient;
+    schemaPath?: string;
+}
+export declare function resolveDatabase(config: HouseKitConfig, name?: string): ResolvedDatabase;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { type HouseKitConfig } from './config';

package/dist/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import chalk from "chalk";
+import { createRequire } from "module";
+import { generateCommand } from "./commands/generate";
+import { pushCommand } from "./commands/push";
+import { migrateCommand } from "./commands/migrate";
+import { pullCommand } from "./commands/pull";
+import { schemaCommand } from "./commands/schema";
+import { checkCommand } from "./commands/check";
+import { dropCommand } from "./commands/drop";
+import { truncateCommand } from "./commands/truncate";
+import { dryRunCommand } from "./commands/dry-run";
+import { statusCommand } from "./commands/status";
+import { initCommand } from "./commands/init";
+import { resetCommand } from "./commands/reset";
+import { listCommand } from "./commands/list";
+import { validateCommand } from "./commands/validate";
+import { setGlobalYesMode } from "./ui";
+var program = new Command;
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+program.name("housekit").description("CLI to manage ClickHouse schemas").version(version).option("-y, --yes", "Auto-confirm all prompts");
+program.hook("preAction", (thisCommand) => {
+  const opts = thisCommand.optsWithGlobals?.() ?? thisCommand.opts();
+  setGlobalYesMode(Boolean(opts.yes));
+});
+function withErrorHandling(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      console.error(chalk.red(`
+✖ Error: ` + (error.message || String(error))));
+      if (process.env.DEBUG) {
+        console.error(error);
+      }
+      process.exit(1);
+    }
+  };
+}
+var asciiLogo = [
+  "░█░█░█▀█░█░█░█▀▀░█▀▀░█░█░▀█▀░▀█▀",
+  "░█▀█░█░█░█░█░▀▀█░█▀▀░█▀▄░░█░░░█░",
+  "░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀▀▀░░▀░"
+].join(`
+`);
+program.addHelpText("before", () => [
+  chalk.white(asciiLogo),
+  "",
+  chalk.bold("Housekit — The Modern ORM for ClickHouse"),
+  chalk.gray("Build, migrate, introspect, and query ClickHouse schemas with type-safe, ergonomic tooling. Zero friction. Maximum speed.")
+].join(`
+`));
+program.addHelpText("after", () => [
+  "",
+  chalk.gray("Tips:"),
+  chalk.gray("  - Configure your databases in housekit.config.{ts,js}."),
+  chalk.gray("  - Use --database to target a specific DB."),
+  chalk.gray('  - Try "housekit schema --tables=foo,bar" to inspect specific tables.')
+].join(`
+`));
+program.command("generate").description("Generate SQL migration files based on schema changes").action(withErrorHandling(generateCommand));
+program.command("push").description("Synchronize code schema directly with database").option("-d, --database <name>", "Database to use").option("--log-explain", "Write EXPLAIN plans to .housekit (disabled by default)").option("--auto-upgrade-metadata", "Automatically upgrade housekit metadata to the version declared in code").action(withErrorHandling(pushCommand));
+program.command("dry-run").description("Preview changes that would be applied without executing them").option("-d, --database <name>", "Database to use").action(withErrorHandling(dryRunCommand));
+program.command("migrate").description("Apply generated SQL migrations to the database").option("-d, --database <name>", "Database to use").action(withErrorHandling(migrateCommand));
+program.command("pull").description("Introspect the database schema and generate TS schema files").option("-d, --database <name>", "Database to use").action(withErrorHandling(pullCommand));
+program.command("schema").description("Print current database schema with types").option("-d, --database <name>", "Database to use").option("-t, --tables <tables>", "Table(s) to display, comma-separated", (value) => value.split(",").map((t) => t.trim()).filter(Boolean)).action(withErrorHandling(schemaCommand));
+program.command("check").description("Check migration files for collisions or inconsistencies").action(withErrorHandling(checkCommand));
+program.command("drop").description("Drop tables from the database (requires confirmation)").option("-d, --database <name>", "Database to use").option("-t, --tables <tables>", "Comma-separated list of tables to drop").action(withErrorHandling(dropCommand));
+program.command("truncate").description("Truncate tables (remove all data but keep table structure)").option("-d, --database <name>", "Database to use").option("-t, --tables <tables>", "Comma-separated list of tables to truncate").action(withErrorHandling(truncateCommand));
+program.command("status").description("Show migration status (applied vs pending)").option("-d, --database <name>", "Database to use").action(withErrorHandling(statusCommand));
+program.command("init").description("Initialize a new HouseKit project").action(withErrorHandling(initCommand));
+program.command("reset").description("Reset database by dropping all tables (requires confirmation)").option("-d, --database <name>", "Database to use").action(withErrorHandling(resetCommand));
+program.command("list").description("List all tables in the database with basic information").option("-d, --database <name>", "Database to use").action(withErrorHandling(listCommand));
+program.command("validate").description("Validate that code schema matches the database schema").option("-d, --database <name>", "Database to use").option("--auto-upgrade-metadata", "Automatically upgrade housekit metadata to the version declared in code").action(withErrorHandling(validateCommand));
+program.command("help").description("Show help").action(() => program.outputHelp());

package/dist/loader.d.ts

@@ -0,0 +1,5 @@
+export declare function loadSchema(schemaPath: string, options?: {
+    quiet?: boolean;
+}): Promise<Record<string, any>>;
+export declare function getConfigPath(root?: string): Promise<string>;
+export declare function loadConfig(): Promise<import("./config").HouseKitConfig>;

package/dist/schema/analyzer.d.ts

@@ -0,0 +1,35 @@
+import type { ClickHouseClient } from '@clickhouse/client';
+import { type RemoteTableDescription } from './diff';
+export interface TableAnalysis {
+    name: string;
+    type: 'create' | 'modify' | 'no_changes';
+    adds: string[];
+    modifies: string[];
+    drops: string[];
+    optionChanges: string[];
+    destructiveReasons: string[];
+    warnings: string[];
+    plan: string[];
+    shadowPlan: string[] | null;
+    rowCount: number;
+    table: any;
+    remote: RemoteTableDescription | null;
+    externallyManaged: boolean;
+}
+export interface AnalysisOptions {
+    autoUpgradeMetadata?: boolean;
+    quiet?: boolean;
+}
+/**
+ * Detects schema drift between the local schema and the remote database.
+ * Centralizes the logic used by push, dry-run, and validate commands.
+ */
+export declare function detectSchemaDrift(client: ClickHouseClient, localSchema: Record<string, any>, options?: AnalysisOptions): Promise<TableAnalysis[]>;
+/**
+ * Fetches the description of a remote table, including its columns, defaults, and options.
+ */
+export declare function describeTable(client: ClickHouseClient, tableName: string, quiet?: boolean): Promise<RemoteTableDescription | null>;
+/**
+ * Counts rows in a given table.
+ */
+export declare function countRows(client: ClickHouseClient, tableName: string): Promise<number>;

package/dist/schema/diff.d.ts

@@ -0,0 +1,20 @@
+import { ClickHouseColumn } from '@housekit/orm';
+import type { ParsedCreateOptions } from './parser';
+export type RemoteTableDescription = {
+    columns: Record<string, string>;
+    defaults: Record<string, string>;
+    options: ParsedCreateOptions;
+    comment: string | null;
+};
+export declare function diffTable(table: any, localCols: Record<string, ClickHouseColumn>, remote: RemoteTableDescription, opts?: {
+    autoUpgradeMetadata?: boolean;
+}): {
+    plan: string[];
+    destructiveReasons: string[];
+    drops: string[];
+    warnings: string[];
+    shadowPlan: string[] | null;
+    adds: string[];
+    modifies: string[];
+    optionChanges: string[];
+};

package/dist/schema/parser.d.ts

@@ -0,0 +1,49 @@
+export type StatementType = 'CREATE_TABLE' | 'ALTER_ADD_COLUMN' | 'ALTER_MODIFY_COLUMN' | 'ALTER_MODIFY_COMMENT' | 'ALTER_TABLE' | 'DROP_TABLE' | 'UNKNOWN';
+export interface ParsedStatement {
+    type: StatementType;
+    tableName?: string;
+    columnName?: string;
+    columnType?: string;
+    comment?: string;
+    statement: string;
+}
+export interface ParsedIndex {
+    name: string;
+    expression: string;
+    type: string;
+    granularity?: number;
+}
+export interface ParsedProjection {
+    name: string;
+    query: string;
+}
+export interface ParsedCreateOptions {
+    engine?: string;
+    onCluster?: string;
+    orderBy?: string;
+    partitionBy?: string;
+    ttl?: string;
+    primaryKey?: string;
+    indices?: ParsedIndex[];
+    projections?: ParsedProjection[];
+}
+/**
+ * Parses a single SQL statement to extract semantic information.
+ */
+export declare function parseStatement(statement: string): ParsedStatement;
+/**
+ * Parses a SHOW CREATE TABLE statement into structured options.
+ */
+export declare function parseCreate(statement: string): ParsedCreateOptions;
+/**
+ * Extracts column definitions from a CREATE TABLE statement.
+ */
+export declare function parseColumnsFromCreate(statement: string): Array<{
+    name: string;
+    definition: string;
+    defaultValue?: string;
+}>;
+/**
+ * Analyzes EXPLAIN output for potential performance issues.
+ */
+export declare function analyzeExplain(explainText: string): string[];

package/dist/ui.d.ts

@@ -0,0 +1,32 @@
+export declare function format(message: string): string;
+export declare function info(message: string): void;
+export declare function warn(message: string): void;
+export declare function success(message: string): void;
+export declare function error(message: string): void;
+export declare function createSpinner(message: string): import("ora").Ora;
+export declare function setGlobalYesMode(enabled: boolean): void;
+export declare function confirmPrompt(message: string, defaultYes?: boolean): Promise<boolean>;
+export interface ListChoice<T = string> {
+    name: string;
+    value: T;
+}
+export declare function listPrompt<T = string>(message: string, choices: ListChoice<T>[], defaultValue?: T): Promise<T>;
+export declare function inputPrompt(message: string, defaultValue?: string, validate?: (input: string) => boolean | string): Promise<string>;
+export declare function checkboxPrompt<T = string>(message: string, choices: ListChoice<T>[], defaultSelected?: T[]): Promise<T[]>;
+/**
+ * Quote a name (table, column, database, etc.) with double quotes
+ */
+export declare function quoteName(name: string): string;
+/**
+ * Quote a list of names, separated by commas
+ */
+export declare function quoteList(items: string[]): string;
+/**
+ * Format a default value, detecting if it's a SQL expression or literal
+ * SQL expressions (like now(), 'USD') are not quoted, literals are quoted
+ */
+export declare function quoteValue(value: string | undefined, defaultType?: string): string;
+/**
+ * Quote a comment value
+ */
+export declare function quoteComment(comment: string | undefined): string;

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "@housekit/kit",
+    "version": "0.1.1",
+    "description": "CLI tool for HouseKit - manage ClickHouse schemas, migrations, and database operations with type-safe workflows.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "license": "MIT",
+    "author": "Pablo Fernandez Ruiz",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/pablofdezr/housekit.git",
+        "directory": "packages/kit"
+    },
+    "homepage": "https://github.com/pablofdezr/housekit#readme",
+    "bugs": {
+        "url": "https://github.com/pablofdezr/housekit/issues"
+    },
+    "keywords": [
+        "clickhouse",
+        "cli",
+        "migrations",
+        "schema",
+        "database",
+        "devtools",
+        "typescript",
+        "orm",
+        "housekit"
+    ],
+    "bin": {
+        "housekit": "dist/index.js"
+    },
+    "files": [
+        "dist/**/*",
+        "LICENSE",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "bun build ./src/index.ts --outdir ./dist --target node --external \"*\" && tsc --project tsconfig.build.json && mv dist/packages/kit/src/* dist/ && rm -rf dist/packages",
+        "clean": "rm -rf dist"
+    },
+    "dependencies": {
+        "@clickhouse/client": "^1.14.0",
+        "@housekit/orm": "^0.1.1",
+        "chalk": "^5.6.2",
+        "cli-table3": "^0.6.5",
+        "commander": "^12.0.0",
+        "inquirer": "^13.0.1",
+        "jiti": "^2.6.1",
+        "ora": "^9.0.0",
+        "random-word-slugs": "^0.1.7"
+    },
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "glob": "^10.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}