feat: embed appkit CLI and AI-targeted docs into the appkit and appkit-ui packages

.release-it.json

@@ -20,7 +20,7 @@
   "npm": false,
   "hooks": {
     "after:bump": "tsx tools/sync-versions.ts ${version} && pnpm build:notice && git add NOTICE.md",
-    "before:release": "pnpm build && pnpm --filter=@databricks/appkit dist && pnpm --filter=@databricks/appkit-ui dist",
+    "before:release": "pnpm build && pnpm --filter=docs build && pnpm --filter=@databricks/appkit dist && pnpm --filter=@databricks/appkit-ui dist",
     "after:release": "npm publish packages/appkit/tmp --access public --provenance && npm publish packages/appkit-ui/tmp --access public --provenance"
   },
   "plugins": {

apps/dev-playground/client/src/appKitTypes.d.ts

@@ -1,5 +1,5 @@
 // Auto-generated by AppKit - DO NOT EDIT
-// Generated by 'npx appkit-generate-types' or Vite plugin during build
+// Generated by 'npx @databricks/appkit generate-types' or Vite plugin during build
 import "@databricks/appkit-ui/react";
 import type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from "@databricks/appkit-ui/js";
 

apps/dev-playground/client/src/routes/type-safety.route.tsx

@@ -525,13 +525,13 @@ export default defineConfig({
             <CardContent>
               <CodeBlock
                 code={`# Generate types from project root
-npx appkit-generate-types
+npx @databricks/appkit generate-types
 
 # Custom output path
-npx appkit-generate-types . client/src/types.d.ts
+npx @databricks/appkit generate-types . client/src/types.d.ts
 
 # Force regeneration (skip cache)
-npx appkit-generate-types --no-cache`}
+npx @databricks/appkit generate-types --no-cache`}
                 lang="bash"
               />
             </CardContent>

docs/docs/development/type-generation.mdx → docs/docs/development/type-generation.md

@@ -42,33 +42,33 @@ 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: `npx @databricks/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 @databricks/appkit generate-types [rootDir] [outFile] [warehouseId]
 ```
 
 ### Examples
 
 - Generate types using warehouse ID from environment
 
   ```bash
-  npx appkit-generate-types . client/src/appKitTypes.d.ts
+  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts
   ```
 
 - Generate types using warehouse ID explicitly
 
   ```bash
-  npx appkit-generate-types . client/src/appKitTypes.d.ts abc123...
+  npx @databricks/appkit generate-types . client/src/appKitTypes.d.ts abc123...
   ```
 
 - Force regeneration (skip cache)
 
   ```bash
-  npx appkit-generate-types --no-cache
+  npx @databricks/appkit generate-types --no-cache
   ```
 
 ## How it works

package.json

@@ -26,7 +26,7 @@
     "format": "biome format --write .",
     "lint:fix": "biome lint --write .",
     "lint": "biome lint .",
-    "pack:sdk": "pnpm build && pnpm -r tarball",
+    "pack:sdk": "pnpm build && pnpm --filter=docs build && pnpm -r tarball",
     "prepare": "husky",
     "release": "release-it",
     "release:dry": "release-it --dry-run",

packages/appkit-ui/package.json

@@ -11,8 +11,8 @@
     "dist",
     "bin",
     "scripts",
+    "docs",
     "CLAUDE.md",
-    "AGENTS.md",
     "llms.txt",
     "README.md",
     "DCO",
@@ -39,7 +39,7 @@
     "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",
+    "tarball": "rm -rf tmp && pnpm dist && npm pack ./tmp --pack-destination ./tmp",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

packages/appkit/package.json

@@ -13,9 +13,9 @@
     "dist",
     "bin",
     "scripts",
+    "docs",
     "CLAUDE.md",
     "llms.txt",
-    "AGENTS.md",
     "README.md",
     "DCO",
     "NOTICE.md"
@@ -25,23 +25,23 @@
       "development": "./src/index.ts",
       "default": "./dist/index.js"
     },
+    "./type-generator": {
+      "types": "./dist/type-generator/index.d.ts",
+      "development": "./src/type-generator/index.ts",
+      "default": "./dist/type-generator/index.js"
+    },
     "./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",
+    "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",
@@ -81,6 +81,7 @@
   "publishConfig": {
     "exports": {
       ".": "./dist/index.js",
+      "./type-generator": "./dist/type-generator/index.js",
       "./package.json": "./package.json"
     }
   }

packages/appkit/src/index.ts

@@ -42,5 +42,5 @@ export {
   type TelemetryConfig,
 } from "./telemetry";
 
-// Vite plugin
+// Vite plugin and type generation
 export { appKitTypesPlugin } from "./type-generator/vite-plugin";

packages/appkit/src/type-generator/index.ts

@@ -28,7 +28,7 @@ function generateTypeDeclarations(querySchemas: QuerySchema[] = []): string {
   const querySection = queryEntries ? `\n${queryEntries};\n  ` : "";
 
   return `// Auto-generated by AppKit - DO NOT EDIT
-// Generated by 'npx appkit-generate-types' or Vite plugin during build
+// Generated by 'npx @databricks/appkit generate-types' or Vite plugin during build
 import "@databricks/appkit-ui/react";
 import type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from "@databricks/appkit-ui/js";
 

packages/shared/bin/appkit.js

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

packages/shared/package.json

@@ -8,6 +8,10 @@
       "development": "./src/index.ts",
       "default": "./dist/index.js"
     },
+    "./cli": {
+      "development": "./src/cli/index.ts",
+      "default": "./dist/cli/index.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -29,10 +33,12 @@
   "publishConfig": {
     "exports": {
       ".": "./dist/index.js",
+      "./cli": "./dist/cli/index.js",
       "./package.json": "./package.json"
     }
   },
   "dependencies": {
-    "fast-glob": "^3.3.3"
+    "@ast-grep/napi": "^0.37.0",
+    "commander": "^12.1.0"
   }
 }

packages/shared/scripts/postinstall.js

@@ -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/src/cli/commands/docs.ts

@@ -0,0 +1,66 @@
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function findPackageRoot(): string {
+  let dir = __dirname;
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  throw new Error("Could not find package root");
+}
+
+function runDocs(docPath?: string) {
+  const packageRoot = findPackageRoot();
+
+  if (!docPath) {
+    // Display llms.txt by default
+    const llmsPath = path.join(packageRoot, "llms.txt");
+
+    if (!fs.existsSync(llmsPath)) {
+      console.error("Error: llms.txt not found in package");
+      process.exit(1);
+    }
+
+    const content = fs.readFileSync(llmsPath, "utf-8");
+    console.log(content);
+    return;
+  }
+
+  // Handle path - remove leading ./ and / first, then strip prefixes
+  let normalizedPath = docPath;
+
+  // Strip leading ./ or /
+  normalizedPath = normalizedPath.replace(/^\.\//, "");
+  normalizedPath = normalizedPath.replace(/^\//, "");
+
+  // Remove /appkit/docs/ or docs/ prefix since files are in packageRoot/docs/
+  normalizedPath = normalizedPath.replace(/^appkit\/docs\//, "");
+  normalizedPath = normalizedPath.replace(/^docs\//, "");
+
+  const fullPath = path.join(packageRoot, "docs", normalizedPath);
+
+  if (!fs.existsSync(fullPath)) {
+    console.error(`Error: Documentation file not found: ${docPath}`);
+    console.error(`Tried: ${fullPath}`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(fullPath, "utf-8");
+  console.log(content);
+}
+
+export const docsCommand = new Command("docs")
+  .description("Display embedded documentation")
+  .argument(
+    "[path]",
+    "Path to specific documentation file (e.g., /appkit/docs/api/appkit-ui/components/Sidebar.md)",
+  )
+  .action(runDocs);

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

@@ -0,0 +1,65 @@
+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/type-generator"
+    );
+
+    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);