wip

Author: pkosiec

docs/docs/development/type-generation.mdx

@@ -42,26 +42,26 @@ export default defineConfig({
 
 When the frontend is served through AppKit in dev mode, AppKit's dev server already includes `appKitTypesPlugin()` internally. You still want it in your client build pipeline if you run `vite build` separately.
 
-## CLI: `appkit-generate-types`
+## CLI: `appkit generate-types`
 
 For manual type generation or CI/CD pipelines, use the CLI command:
 
 ```bash
 # Requires DATABRICKS_WAREHOUSE_ID (or pass as 3rd arg)
-npx appkit-generate-types [rootDir] [outFile] [warehouseId]
+npx appkit generate-types [rootDir] [outFile] [warehouseId]
 ```
 
 ### Examples
 
 ```bash
 # Generate types using warehouse ID from environment
-npx appkit-generate-types . client/src/appKitTypes.d.ts
+npx appkit generate-types . client/src/appKitTypes.d.ts
 
 # Force regeneration (skip cache)
-npx appkit-generate-types --no-cache
+npx appkit generate-types --no-cache
 
 # Specify warehouse ID explicitly
-npx appkit-generate-types . client/src/appKitTypes.d.ts abc123...
+npx appkit generate-types . client/src/appKitTypes.d.ts abc123...
 ```
 
 ## How It Works

packages/appkit-ui/package.json

@@ -38,8 +38,8 @@
     "build:watch": "tsdown --config tsdown.config.ts --watch",
     "clean:full": "rm -rf dist node_modules tmp",
     "clean": "rm -rf dist tmp",
-    "dist": "tsx ../../tools/dist.ts",
-    "tarball": "rm -rf tmp && tsx ../../tools/dist.ts && npm pack ./tmp --pack-destination ./tmp",
+    "dist": "pnpm --filter=docs build && tsx ../../tools/dist.ts",
+    "tarball": "rm -rf tmp && pnpm dist && npm pack ./tmp --pack-destination ./tmp",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

packages/appkit/bin/generate-types.js

@@ -27,21 +27,16 @@
     },
     "./package.json": "./package.json"
   },
-  "bin": {
-    "appkit-generate-types": "./bin/generate-types.js",
-    "appkit-lint": "./bin/appkit-lint.js"
-  },
   "scripts": {
     "build:package": "tsdown --config tsdown.config.ts",
     "build:watch": "tsdown --config tsdown.config.ts --watch",
     "clean:full": "rm -rf dist node_modules tmp",
     "clean": "rm -rf dist tmp",
-    "dist": "tsx ../../tools/dist.ts",
-    "tarball": "rm -rf tmp && tsx ../../tools/dist.ts && npm pack ./tmp --pack-destination ./tmp",
+    "dist": "pnpm --filter=docs build && tsx ../../tools/dist.ts",
+    "tarball": "rm -rf tmp && pnpm dist && npm pack ./tmp --pack-destination ./tmp",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ast-grep/napi": "^0.37.0",
     "@databricks/sdk-experimental": "^0.15.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.208.0",

packages/appkit/package.json

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../dist/cli/index.js";

packages/shared/bin/appkit.js

@@ -33,6 +33,8 @@
     }
   },
   "dependencies": {
+    "@ast-grep/napi": "^0.37.0",
+    "commander": "^12.1.0",
     "fast-glob": "^3.3.3"
   }
 }

packages/shared/package.json

@@ -2,5 +2,5 @@
 console.log("");
 console.log("[@databricks/appkit] To setup AI assistant instructions, run:");
 console.log("");
-console.log("  npx appkit-setup --write");
+console.log("  npx appkit setup --write");
 console.log("");

packages/shared/scripts/postinstall.js

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+import path from "node:path";
+
+/**
+ * Generate types command implementation
+ */
+async function runGenerateTypes(
+  rootDir?: string,
+  outFile?: string,
+  warehouseId?: string,
+  options?: { noCache?: boolean }
+) {
+  try {
+    // Try to import the type generator from @databricks/appkit
+    const { generateFromEntryPoint } = await import(
+      "@databricks/appkit/dist/type-generator/index.js"
+    );
+
+    const resolvedRootDir = rootDir || process.cwd();
+    const resolvedOutFile =
+      outFile || path.join(process.cwd(), "client/src/appKitTypes.d.ts");
+
+    const queryFolder = path.join(resolvedRootDir, "config/queries");
+
+    const resolvedWarehouseId =
+      warehouseId || process.env.DATABRICKS_WAREHOUSE_ID;
+    if (!resolvedWarehouseId) {
+      console.error(
+        "Error: DATABRICKS_WAREHOUSE_ID is not set. Please provide it as an argument or environment variable."
+      );
+      process.exit(1);
+    }
+
+    await generateFromEntryPoint({
+      queryFolder,
+      outFile: resolvedOutFile,
+      warehouseId: resolvedWarehouseId,
+      noCache: options?.noCache || false,
+    });
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message.includes("Cannot find module")
+    ) {
+      console.error(
+        "Error: The 'generate-types' command is only available in @databricks/appkit."
+      );
+      console.error(
+        "Please install @databricks/appkit to use this command."
+      );
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+
+export const generateTypesCommand = new Command("generate-types")
+  .description("Generate TypeScript types from SQL queries")
+  .argument("[rootDir]", "Root directory of the project", process.cwd())
+  .argument(
+    "[outFile]",
+    "Output file path",
+    path.join(process.cwd(), "client/src/appKitTypes.d.ts")
+  )
+  .argument("[warehouseId]", "Databricks warehouse ID")
+  .option("--no-cache", "Disable caching for type generation")
+  .action(runGenerateTypes);

packages/shared/src/cli/commands/generate-types.ts

@@ -1,14 +1,17 @@
-#!/usr/bin/env node
-/**
- * AST-based linting using ast-grep.
- * Catches patterns that ESLint/TypeScript miss or handle poorly.
- * Usage: npx appkit-lint
- */
+import { Command } from "commander";
 import { parse, Lang } from "@ast-grep/napi";
 import fs from "node:fs";
 import path from "node:path";
 
-const rules = [
+interface Rule {
+  id: string;
+  pattern: string;
+  message: string;
+  includeTests?: boolean;
+  filter?: (code: string) => boolean;
+}
+
+const rules: Rule[] = [
   {
     id: "no-double-type-assertion",
     pattern: "$X as unknown as $Y",
@@ -37,13 +40,13 @@ const rules = [
   },
 ];
 
-function isTestFile(filePath) {
+function isTestFile(filePath: string): boolean {
   return (
     /\.(test|spec)\.(ts|tsx)$/.test(filePath) || filePath.includes("/tests/")
   );
 }
 
-function findTsFiles(dir, files = []) {
+function findTsFiles(dir: string, files: string[] = []): string[] {
   const entries = fs.readdirSync(dir, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -61,8 +64,17 @@ function findTsFiles(dir, files = []) {
   return files;
 }
 
-function lintFile(filePath, rules) {
-  const violations = [];
+interface Violation {
+  file: string;
+  line: number;
+  column: number;
+  rule: string;
+  message: string;
+  code: string;
+}
+
+function lintFile(filePath: string, rules: Rule[]): Violation[] {
+  const violations: Violation[] = [];
   const content = fs.readFileSync(filePath, "utf-8");
   const lang = filePath.endsWith(".tsx") ? Lang.Tsx : Lang.TypeScript;
   const testFile = isTestFile(filePath);
@@ -96,13 +108,16 @@ function lintFile(filePath, rules) {
   return violations;
 }
 
-function main() {
+/**
+ * Lint command implementation
+ */
+function runLint() {
   const rootDir = process.cwd();
   const files = findTsFiles(rootDir);
 
   console.log(`Scanning ${files.length} TypeScript files...\n`);
 
-  const allViolations = [];
+  const allViolations: Violation[] = [];
 
   for (const file of files) {
     const violations = lintFile(file, rules);
@@ -126,4 +141,6 @@ function main() {
   process.exit(1);
 }
 
-main();
+export const lintCommand = new Command("lint")
+  .description("Run AST-based linting on TypeScript files")
+  .action(runLint);

packages/appkit/bin/appkit-lint.js packages/shared/src/cli/commands/lint.tspackages/appkit/bin/appkit-lint.js renamed to packages/shared/src/cli/commands/lint.ts

@@ -1,16 +1,4 @@
-#!/usr/bin/env node
-
-/**
- * CLI tool to setup CLAUDE.md for Databricks AppKit packages.
- *
- * This bin is included in both @databricks/appkit and @databricks/appkit-ui
- * so it's available regardless of which package the user installs.
- *
- * Usage:
- *   npx appkit-setup          # Show detected packages and content
- *   npx appkit-setup --write  # Create or update CLAUDE.md file
- */
-
+import { Command } from "commander";
 import fs from "node:fs";
 import path from "node:path";
 
@@ -26,15 +14,15 @@ const SECTION_START = "<!-- appkit-instructions-start -->";
 const SECTION_END = "<!-- appkit-instructions-end -->";
 
 /**
- * Find which AppKit packages are installed by checking for CLAUDE.md
+ * Find which AppKit packages are installed by checking for package.json
  */
 function findInstalledPackages() {
   const cwd = process.cwd();
   const installed = [];
 
   for (const pkg of PACKAGES) {
-    const claudePath = path.join(cwd, "node_modules", pkg.name, "package.json");
-    if (fs.existsSync(claudePath)) {
+    const packagePath = path.join(cwd, "node_modules", pkg.name, "package.json");
+    if (fs.existsSync(packagePath)) {
       installed.push(pkg);
     }
   }
@@ -45,7 +33,7 @@ function findInstalledPackages() {
 /**
  * Generate the AppKit section content
  */
-function generateSection(packages) {
+function generateSection(packages: typeof PACKAGES) {
   const links = packages
     .map((pkg) => {
       const docPath = `./node_modules/${pkg.name}/CLAUDE.md`;
@@ -65,7 +53,7 @@ ${SECTION_END}`;
 /**
  * Generate standalone CLAUDE.md content (when no existing file)
  */
-function generateStandalone(packages) {
+function generateStandalone(packages: typeof PACKAGES) {
   const links = packages
     .map((pkg) => {
       const docPath = `./node_modules/${pkg.name}/CLAUDE.md`;
@@ -88,7 +76,7 @@ ${SECTION_END}
 /**
  * Update existing content with AppKit section
  */
-function updateContent(existingContent, packages) {
+function updateContent(existingContent: string, packages: typeof PACKAGES) {
   const newSection = generateSection(packages);
 
   // Check if AppKit section already exists
@@ -107,27 +95,10 @@ function updateContent(existingContent, packages) {
 }
 
 /**
- * Main CLI logic
+ * Setup command implementation
  */
-function main() {
-  const args = process.argv.slice(2);
-  const shouldWrite = args.includes("--write") || args.includes("-w");
-  const help = args.includes("--help") || args.includes("-h");
-
-  if (help) {
-    console.log(`
-Usage: npx appkit-setup [options]
-
-Options:
-  --write, -w   Create or update CLAUDE.md file in current directory
-  --help, -h    Show this help message
-
-Examples:
-  npx appkit-setup              # Show detected packages and preview content
-  npx appkit-setup --write      # Create or update CLAUDE.md
-`);
-    return;
-  }
+function runSetup(options: { write?: boolean }) {
+  const shouldWrite = options.write;
 
   // Find installed packages
   const installed = findInstalledPackages();
@@ -151,8 +122,8 @@ Examples:
     ? fs.readFileSync(claudePath, "utf-8")
     : null;
 
-  let finalContent;
-  let action;
+  let finalContent: string;
+  let action: string;
 
   if (existingContent) {
     finalContent = updateContent(existingContent, installed);
@@ -168,7 +139,7 @@ Examples:
     console.log(`  Path: ${claudePath}`);
   } else {
     console.log("\nTo create/update CLAUDE.md, run:");
-    console.log("  npx appkit-setup --write\n");
+    console.log("  npx appkit setup --write\n");
 
     if (existingContent) {
       console.log(
@@ -187,4 +158,7 @@ Examples:
   }
 }
 
-main();
+export const setupCommand = new Command("setup")
+  .description("Setup CLAUDE.md with AppKit package references")
+  .option("-w, --write", "Create or update CLAUDE.md file in current directory")
+  .action(runSetup);